CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-google-cloud-resource-manager

Google Cloud Resource Manager API client library for managing projects, folders, organizations, and tags in Google Cloud Platform

—

Pending
Overview
Eval results
Files

tag-keys.mddocs/

Tag Keys Management

Management of tag categories that define the taxonomy for organizing and controlling Google Cloud resources through policy and automation. TagKeys represent the "key" portion of key-value tags and define what types of tags can be applied to resources.

Capabilities

Tag Key Retrieval

Retrieve detailed information about a specific TagKey using its resource name.

def get_tag_key(
    self,
    request: GetTagKeyRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> TagKey:
    """
    Retrieves a TagKey identified by the specified resource name.

    Args:
        name (str): The resource name of the TagKey to retrieve.
            Format: tagKeys/{tag_key_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        TagKey: The requested TagKey resource

    Raises:
        google.api_core.exceptions.NotFound: If the TagKey doesn't exist
        google.api_core.exceptions.PermissionDenied: If access is denied
    """

Namespaced Tag Key Retrieval

Retrieve a TagKey using its namespaced name format for more intuitive access.

def get_namespaced_tag_key(
    self,
    request: GetNamespacedTagKeyRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> TagKey:
    """
    Retrieves a TagKey by its namespaced name.

    Args:
        name (str): The namespaced name of the TagKey.
            Format: {parent_id}/{tag_key_short_name}
            Example: 123456789/environment
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        TagKey: The requested TagKey resource
    """

Usage example:

from google.cloud.resourcemanager import TagKeysClient

client = TagKeysClient()

# Get by resource name
tag_key = client.get_tag_key(name="tagKeys/281484271805521")
print(f"TagKey: {tag_key.short_name} - {tag_key.description}")

# Get by namespaced name (more intuitive)
tag_key = client.get_namespaced_tag_key(name="123456789/environment")
print(f"TagKey: {tag_key.short_name} (Purpose: {tag_key.purpose})")

Tag Key Listing

List all TagKeys under a specified parent resource (organization or project).

def list_tag_keys(
    self,
    request: ListTagKeysRequest = None,
    *,
    parent: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> pagers.ListTagKeysPager:
    """
    Lists TagKeys that are direct children of the specified parent resource.

    Args:
        parent (str): The parent resource whose TagKeys are to be listed.
            Formats: organizations/{organization_id} or projects/{project_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        ListTagKeysPager: An iterator over TagKeys that automatically
                         handles pagination
    """

Usage example:

client = TagKeysClient()

# List all TagKeys under an organization
for tag_key in client.list_tag_keys(parent="organizations/123456789"):
    print(f"TagKey: {tag_key.short_name} - {tag_key.description}")
    print(f"  Purpose: {tag_key.purpose}")
    print(f"  Namespaced: {tag_key.namespaced_name}")

Tag Key Creation

Create new TagKeys to define tag categories. This is a long-running operation with a limit of 1000 TagKeys per parent resource.

def create_tag_key(
    self,
    request: CreateTagKeyRequest = None,
    *,
    tag_key: TagKey = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Creates a new TagKey. This is a long-running operation.
    
    Maximum of 1000 TagKeys per parent resource.

    Args:
        tag_key (TagKey): The TagKey resource to create
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the created TagKey
    """

Usage example:

from google.cloud.resourcemanager import TagKeysClient
from google.cloud.resourcemanager_v3.types import TagKey, Purpose

client = TagKeysClient()

new_tag_key = TagKey(
    parent="organizations/123456789",
    short_name="environment",
    description="Environment classification for resources",
    purpose=Purpose.GCE_FIREWALL  # Optional: specific purpose for the tag
)

operation = client.create_tag_key(tag_key=new_tag_key)
result = operation.result()  # Wait for completion
print(f"Created TagKey: {result.short_name} ({result.name})")
print(f"Namespaced name: {result.namespaced_name}")

Tag Key Updates

Update TagKey attributes such as description and purpose data. This is a long-running operation.

def update_tag_key(
    self,
    request: UpdateTagKeyRequest = None,
    *,
    tag_key: TagKey = None,
    update_mask: field_mask_pb2.FieldMask = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Updates the specified TagKey. This is a long-running operation.

    Args:
        tag_key (TagKey): The TagKey resource with updated values
        update_mask (FieldMask): Fields to update. If not provided,
                               all mutable fields are updated
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation that resolves to the updated TagKey
    """

Usage example:

from google.protobuf import field_mask_pb2

client = TagKeysClient()

# Get existing TagKey
tag_key = client.get_tag_key(name="tagKeys/281484271805521")

# Update description
tag_key.description = "Updated environment classification for all resources"

# Specify which fields to update
update_mask = field_mask_pb2.FieldMask(paths=["description"])

operation = client.update_tag_key(
    tag_key=tag_key,
    update_mask=update_mask
)
result = operation.result()
print(f"Updated TagKey: {result.description}")

Tag Key Deletion

Delete TagKeys if no child TagValues exist. This is a long-running operation that permanently removes the TagKey.

def delete_tag_key(
    self,
    request: DeleteTagKeyRequest = None,
    *,
    name: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> operation.Operation:
    """
    Deletes a TagKey if no child TagValues exist. This is a long-running operation.
    
    The TagKey must have no child TagValues to be deleted.

    Args:
        name (str): The resource name of the TagKey to delete.
                   Format: tagKeys/{tag_key_id}
        retry: Retry configuration for the request
        timeout: Request timeout in seconds
        metadata: Additional metadata to send with the request

    Returns:
        Operation: Long-running operation with no return value

    Raises:
        google.api_core.exceptions.FailedPrecondition: If TagKey has child TagValues
    """

Usage example:

client = TagKeysClient()

# Delete a TagKey (only works if no child TagValues exist)
operation = client.delete_tag_key(name="tagKeys/281484271805521")
operation.result()  # Wait for completion
print("TagKey deleted successfully")

IAM Policy Management

Manage IAM (Identity and Access Management) policies for TagKeys, controlling who can create TagValues and bind tags.

def get_iam_policy(
    self,
    request: iam_policy_pb2.GetIamPolicyRequest = None,
    *,
    resource: str = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> policy_pb2.Policy:
    """
    Gets the IAM access control policy for a TagKey.

    Args:
        resource (str): Resource name of the TagKey.
                       Format: tagKeys/{tag_key_id}

    Returns:
        Policy: The IAM policy for the TagKey
    """

def set_iam_policy(
    self,
    request: iam_policy_pb2.SetIamPolicyRequest = None,
    *,
    resource: str = None,
    policy: policy_pb2.Policy = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> policy_pb2.Policy:
    """
    Sets the IAM access control policy for a TagKey.

    Args:
        resource (str): Resource name of the TagKey
        policy (Policy): The new IAM policy

    Returns:
        Policy: The updated IAM policy
    """

def test_iam_permissions(
    self,
    request: iam_policy_pb2.TestIamPermissionsRequest = None,
    *,
    resource: str = None,
    permissions: MutableSequence[str] = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
) -> iam_policy_pb2.TestIamPermissionsResponse:
    """
    Tests the specified permissions against the IAM policy for a TagKey.

    Args:
        resource (str): Resource name of the TagKey
        permissions (Sequence[str]): List of permissions to test

    Returns:
        TestIamPermissionsResponse: Results of the permission test
    """

Types

class TagKey:
    name: str  # Resource name: tagKeys/{tag_key_id}
    parent: str  # Parent resource: organizations/{org_id} or projects/{project_id}
    short_name: str  # User-assigned short name (e.g., "environment")
    namespaced_name: str  # Computed field: {parent_id}/{short_name}
    display_name: str  # Human-readable display name
    description: str  # Description of the TagKey's purpose
    purpose: Purpose  # Specific purpose for the TagKey
    purpose_data: MutableMapping[str, str]  # Additional purpose-specific data
    create_time: timestamp_pb2.Timestamp  # Creation timestamp
    update_time: timestamp_pb2.Timestamp  # Last update timestamp
    etag: str  # Entity tag for optimistic concurrency

class Purpose(proto.Enum):
    """Enum defining specific purposes for TagKeys."""
    PURPOSE_UNSPECIFIED = 0
    GCE_FIREWALL = 1  # Used for GCE firewall rules

# Request/Response types
class GetTagKeyRequest:
    name: str

class GetNamespacedTagKeyRequest:
    name: str  # Format: {parent_id}/{tag_key_short_name}

class ListTagKeysRequest:
    parent: str
    page_token: str
    page_size: int

class ListTagKeysResponse:
    tag_keys: MutableSequence[TagKey]
    next_page_token: str

class CreateTagKeyRequest:
    tag_key: TagKey
    validate_only: bool  # If true, validate request without creating

class UpdateTagKeyRequest:
    tag_key: TagKey
    update_mask: field_mask_pb2.FieldMask
    validate_only: bool

class DeleteTagKeyRequest:
    name: str
    validate_only: bool
    etag: str  # Current etag for optimistic concurrency

# Metadata types for long-running operations
class CreateTagKeyMetadata:
    # Empty metadata message

class UpdateTagKeyMetadata:
    # Empty metadata message

class DeleteTagKeyMetadata:
    # Empty metadata message

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-resource-manager

docs

folders.md

index.md

organizations.md

projects.md

tag-bindings.md

tag-holds.md

tag-keys.md

tag-values.md

tile.json