0
# Tag Bindings Management
1

2
Association and management of tag values with specific Google Cloud resources, including listing effective tags that apply to resources through inheritance. TagBindings create the actual association between TagValues and cloud resources, enabling policy enforcement and resource organization.
3

4
## Capabilities
5

6
### Tag Binding Creation
7

8
Create associations between TagValues and Google Cloud resources. This is a long-running operation.
9

10
```python { .api }
11
def create_tag_binding(
12
    self,
13
    request: CreateTagBindingRequest = None,
14
    *,
15
    tag_binding: TagBinding = None,
16
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
17
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
18
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
19
) -> operation.Operation:
20
    """
21
    Creates a TagBinding between a TagValue and a cloud resource. This is a long-running operation.
22

23
    Args:
24
        tag_binding (TagBinding): The TagBinding resource to create
25
        retry: Retry configuration for the request
26
        timeout: Request timeout in seconds
27
        metadata: Additional metadata to send with the request
28

29
    Returns:
30
        Operation: Long-running operation that resolves to the created TagBinding
31
    """
32
```
33

34
Usage example:
35

36
```python
37
from google.cloud.resourcemanager import TagBindingsClient
38
from google.cloud.resourcemanager_v3.types import TagBinding
39

40
client = TagBindingsClient()
41

42
new_binding = TagBinding(
43
    parent="//cloudresourcemanager.googleapis.com/projects/my-project-123",
44
    tag_value="tagValues/281484271805522"  # Must be an existing TagValue
45
)
46

47
operation = client.create_tag_binding(tag_binding=new_binding)
48
result = operation.result()  # Wait for completion
49
print(f"Created TagBinding: {result.name}")
50
print(f"Resource: {result.parent}")
51
print(f"TagValue: {result.tag_value_namespaced_name}")
52
```
53

54
### Tag Binding Listing
55

56
List all TagBindings for a specified Google Cloud resource.
57

58
```python { .api }
59
def list_tag_bindings(
60
    self,
61
    request: ListTagBindingsRequest = None,
62
    *,
63
    parent: str = None,
64
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
65
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
66
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
67
) -> pagers.ListTagBindingsPager:
68
    """
69
    Lists TagBindings for a Google Cloud resource.
70

71
    Args:
72
        parent (str): The resource whose TagBindings are to be listed.
73
            Format: //SERVICE.googleapis.com/RESOURCE_TYPE/RESOURCE_ID
74
            Examples:
75
            - //cloudresourcemanager.googleapis.com/projects/my-project
76
            - //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-vm
77
        retry: Retry configuration for the request
78
        timeout: Request timeout in seconds
79
        metadata: Additional metadata to send with the request
80

81
    Returns:
82
        ListTagBindingsPager: An iterator over TagBindings that automatically
83
                             handles pagination
84
    """
85
```
86

87
Usage example:
88

89
```python
90
client = TagBindingsClient()
91

92
# List TagBindings for a project
93
for binding in client.list_tag_bindings(
94
    parent="//cloudresourcemanager.googleapis.com/projects/my-project"
95
):
96
    print(f"TagBinding: {binding.name}")
97
    print(f"  TagValue: {binding.tag_value_namespaced_name}")
98
    print(f"  Resource: {binding.parent}")
99

100
# List TagBindings for a specific resource
101
for binding in client.list_tag_bindings(
102
    parent="//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-vm"
103
):
104
    print(f"VM TagBinding: {binding.tag_value_namespaced_name}")
105
```
106

107
### Tag Binding Deletion
108

109
Remove TagBinding associations between TagValues and cloud resources. This is a long-running operation.
110

111
```python { .api }
112
def delete_tag_binding(
113
    self,
114
    request: DeleteTagBindingRequest = None,
115
    *,
116
    name: str = None,
117
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
118
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
119
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
120
) -> operation.Operation:
121
    """
122
    Deletes a TagBinding. This is a long-running operation.
123

124
    Args:
125
        name (str): The resource name of the TagBinding to delete.
126
                   Format: tagBindings/{tag_binding_id}
127
        retry: Retry configuration for the request
128
        timeout: Request timeout in seconds
129
        metadata: Additional metadata to send with the request
130

131
    Returns:
132
        Operation: Long-running operation with no return value
133
    """
134
```
135

136
Usage example:
137

138
```python
139
client = TagBindingsClient()
140

141
# Delete a specific TagBinding
142
operation = client.delete_tag_binding(name="tagBindings/some-binding-id")
143
operation.result()  # Wait for completion
144
print("TagBinding deleted successfully")
145
```
146

147
### Effective Tags Listing
148

149
List effective tags for a Google Cloud resource, including tags inherited from parent resources in the hierarchy.
150

151
```python { .api }
152
def list_effective_tags(
153
    self,
154
    request: ListEffectiveTagsRequest = None,
155
    *,
156
    parent: str = None,
157
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
158
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
159
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
160
) -> pagers.ListEffectiveTagsPager:
161
    """
162
    Lists effective tags for a Google Cloud resource, including inherited tags.
163

164
    Args:
165
        parent (str): The resource whose effective tags are to be listed.
166
            Format: //SERVICE.googleapis.com/RESOURCE_TYPE/RESOURCE_ID
167
            Examples:
168
            - //cloudresourcemanager.googleapis.com/projects/my-project
169
            - //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-vm
170
        retry: Retry configuration for the request
171
        timeout: Request timeout in seconds
172
        metadata: Additional metadata to send with the request
173

174
    Returns:
175
        ListEffectiveTagsPager: An iterator over EffectiveTag resources
176
    """
177
```
178

179
Usage example:
180

181
```python
182
client = TagBindingsClient()
183

184
# List all effective tags for a project (direct + inherited)
185
for effective_tag in client.list_effective_tags(
186
    parent="//cloudresourcemanager.googleapis.com/projects/my-project"
187
):
188
    print(f"Effective Tag: {effective_tag.namespaced_tag_key}/{effective_tag.namespaced_tag_value}")
189
    print(f"  Inherited: {effective_tag.inherited}")
190
    if effective_tag.inherited:
191
        print(f"  Inherited from: {effective_tag.tag_key_parent_name}")
192

193
# List effective tags for a specific resource
194
for effective_tag in client.list_effective_tags(
195
    parent="//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-vm"
196
):
197
    print(f"VM Effective Tag: {effective_tag.namespaced_tag_key}/{effective_tag.namespaced_tag_value}")
198
```
199

200
## Types
201

202
```python { .api }
203
class TagBinding:
204
    name: str  # Resource name: tagBindings/{tag_binding_id}
205
    parent: str  # Cloud resource name: //SERVICE.googleapis.com/RESOURCE_TYPE/RESOURCE_ID
206
    tag_value: str  # TagValue resource name: tagValues/{tag_value_id}
207
    tag_value_namespaced_name: str  # Human-readable TagValue reference
208

209
class EffectiveTag:
210
    tag_key: str  # TagKey resource name: tagKeys/{tag_key_id}
211
    tag_key_parent_name: str  # Parent resource of the TagKey
212
    tag_value: str  # TagValue resource name: tagValues/{tag_value_id}
213
    namespaced_tag_key: str  # Human-readable TagKey reference
214
    namespaced_tag_value: str  # Human-readable TagValue reference
215
    inherited: bool  # True if tag is inherited from a parent resource
216

217
# Request/Response types
218
class CreateTagBindingRequest:
219
    tag_binding: TagBinding
220
    validate_only: bool  # If true, validate request without creating
221

222
class ListTagBindingsRequest:
223
    parent: str  # Cloud resource name
224
    page_token: str
225
    page_size: int
226

227
class ListTagBindingsResponse:
228
    tag_bindings: MutableSequence[TagBinding]
229
    next_page_token: str
230

231
class DeleteTagBindingRequest:
232
    name: str  # TagBinding resource name
233

234
class ListEffectiveTagsRequest:
235
    parent: str  # Cloud resource name
236
    page_token: str
237
    page_size: int
238

239
class ListEffectiveTagsResponse:
240
    effective_tags: MutableSequence[EffectiveTag]
241
    next_page_token: str
242

243
# Metadata types for long-running operations
244
class CreateTagBindingMetadata:
245
    # Empty metadata message
246

247
class DeleteTagBindingMetadata:
248
    # Empty metadata message
249
```
250

251
## Resource Name Formats
252

253
TagBindings work with fully qualified cloud resource names. Here are common formats:
254

255
### Resource Manager Resources
256
```python
257
# Projects
258
"//cloudresourcemanager.googleapis.com/projects/my-project-id"
259

260
# Folders
261
"//cloudresourcemanager.googleapis.com/folders/123456789"
262

263
# Organizations
264
"//cloudresourcemanager.googleapis.com/organizations/123456789"
265
```
266

267
### Compute Engine Resources
268
```python
269
# VM Instances
270
"//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-vm"
271

272
# Disks
273
"//compute.googleapis.com/projects/my-project/zones/us-central1-a/disks/my-disk"
274

275
# Networks
276
"//compute.googleapis.com/projects/my-project/global/networks/my-network"
277
```
278

279
### Storage Resources
280
```python
281
# Cloud Storage Buckets
282
"//storage.googleapis.com/projects/_/buckets/my-bucket"
283
```
284

285
## Notes
286

287
- TagBindings create direct associations between TagValues and resources
288
- Effective tags include both direct TagBindings and inherited tags from parent resources in the hierarchy
289
- Tag inheritance follows the Google Cloud resource hierarchy: Organization → Folder → Project → Resource
290
- TagBindings can be created on any Google Cloud resource that supports tagging
291
- The `parent` field in TagBinding and EffectiveTag requests uses the full cloud resource name format