This guide describes how to create and manage tags on Cloud Key Management Service key rings. You can use tags to group related Cloud KMS key rings and store metadata about those resources based on their tags. ## About tags A tag is a key-value pair that can attach to a resource within Google Cloud. You can use tags to conditionally allow or deny policies based on whether a resource has a specific tag. For example, you can conditionally grant Identity and Access Management (IAM) roles based on whether a resource has a specific tag. For more information about tags, see [Tags overview](https://docs.cloud.google.com/resource-manager/docs/tags/tags-overview.md.txt). Tags are attached to resources by creating a tag binding resource that links the value to the Google Cloud resource. To group key rings within Cloud KMS for automation and billing purposes, use [labels](https://docs.cloud.google.com/kms/docs/creating-managing-labels.md.txt). Tags and labels work independently of each other, and you can apply both to resources. ## Required permissions To get the permissions that you need to manage tags, ask your administrator to grant you the following IAM roles: - [Tag Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/resourcemanager.md.txt#resourcemanager.tagViewer) (`roles/resourcemanager.tagViewer`) on the resources the tags are attached to - View and manage tags at the organization level: [Organization Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/resourcemanager.md.txt#resourcemanager.organizationViewer) (`roles/resourcemanager.organizationViewer`) on the organization - Create, update, and delete tag definitions: [Tag Administrator](https://docs.cloud.google.com/iam/docs/roles-permissions/resourcemanager.md.txt#resourcemanager.tagAdmin) (`roles/resourcemanager.tagAdmin`) on the resource you're creating, updating, or deleting tags for - Attach and remove tags from resources: [Tag User](https://docs.cloud.google.com/iam/docs/roles-permissions/resourcemanager.md.txt#resourcemanager.tagUser) (`roles/resourcemanager.tagUser`) on the tag value and the resources that you are attaching or removing the tag value to For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt). You might also be able to get the required permissions through [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined). To attach tags to Cloud KMS key rings, you need the [Cloud KMS Admin](https://docs.cloud.google.com/kms/docs/reference/permissions-and-roles.md.txt#predefined) role (`roles/cloudkms.admin`). ## Create tag keys and values Before you can attach a tag, you need to create a tag and configure its value. To create tag keys and tag values, see [Creating a tag](https://docs.cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing.md.txt#creating_tag) and [Adding a tag value](https://docs.cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing.md.txt#adding_tag_values). ## Add tags to existing resources To add a tag to existing key rings, follow these steps: ### Console 1. Go to the **Key management** page in the Google Cloud console. 2. [Go to Key management](https://console.cloud.google.com/security/kms/keyrings) 3. Select the key ring for which you would like to attach a tag. 4. Click **Tags**. 5. If your organization doesn't appear in the **Tags** panel, click **Select scope** . Select your organization and click **Open**. 6. Click **Add tag**. 7. Select the key for the tag you want to attach from the list. You can filter the list by typing keywords. 8. Select the value for the tag you want to attach from the list. You can filter the list by typing keywords. 9. Click **Save**. 10. In the **Confirm** dialog, click **Confirm** to attach the tag. 11. A notification confirms that your tags updated. ### gcloud To attach a tag to a key ring, you must create a tag binding resource by using the `gcloud resource-manager tags bindings create` command: ``` gcloud resource-manager tags bindings create \ --tag-value=TAGVALUE_NAME \ --parent=RESOURCE_ID \ --location=LOCATION ``` Replace the following: - `TAGVALUE_NAME`: the permanent ID or namespaced name of the tag value that you attach to a resource---for example, `tagValues/567890123456`. - `RESOURCE_ID` is the full ID of the resource, including the API domain name to identify the type of resource (`//cloudkms.googleapis.com/`). For example, to attach a tag to `projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`, the full ID is: `//cloudkms.googleapis.com/projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`. - `LOCATION`: the location of your resource. If you're attaching a tag to a global resource, such as a folder or a project, omit this flag. If you're attaching a tag to a regional or a zonal resource, you must specify the location---for example, `us-central1` (region) or `us-central1-a` (zone). For help with locating a Cloud KMS resource ID, see [Retrieving a resource's ID](https://docs.cloud.google.com/kms/docs/resource-hierarchy.md.txt#retrieve_resource_id). ## List tags attached to resources You can view a list of tag bindings directly attached to or inherited by the key ring. ### Console 1. Go to the **Key management** page in the Google Cloud console. 2. [Go to Key management](https://console.cloud.google.com/security/kms/keyrings) 3. Tags are displayed in the **Tags** column of the key ring. ### gcloud To get a list of tag bindings attached to a resource, use the `gcloud resource-manager tags bindings list` command: ``` gcloud resource-manager tags bindings list \ --parent=RESOURCE_ID \ --location=LOCATION ``` Replace the following: - `RESOURCE_ID` is the full ID of the resource, including the API domain name to identify the type of resource (`//cloudkms.googleapis.com/`). For example, to attach a tag to `projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`, the full ID is: `//cloudkms.googleapis.com/projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`. - `LOCATION`: the location of your resource. If you're viewing a tag attached to a global resource, such as a folder or a project, omit this flag. If you're viewing a tag attached to a regional or a zonal resource, you must specify the location---for example, `us-central1` (region) or `us-central1-a` (zone). You should get a response similar to the following: ``` name: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F7890123456/tagValues/567890123456 tagValue: tagValues/567890123456 resource: //cloudkms.googleapis.com/projects/project-abc/locations/global/keyRings/keyring-xyz ``` ## Detach tags from resources You can detach tags that have been directly attached to a key ring. Inherited tags can be overridden by attaching a tag with the same key and a different value, but they can't be detached. ### Console 1. Go to the **Key management** page in the Google Cloud console. 2. [Go to Key management](https://console.cloud.google.com/security/kms/keyrings) 3. Select the key ring from which you want to remove a tag. 4. Click **Tags**. 5. In the **Tags** panel, next to the tag you want to detach, click **Delete item**. 6. Click **Save**. 7. In the **Confirm** dialog, click **Confirm** to detach the tag. A notification confirms that your tags updated. ### gcloud To delete a tag binding, use the `gcloud resource-manager tags bindings delete` command: ``` gcloud resource-manager tags bindings delete \ --tag-value=TAGVALUE_NAME \ --parent=RESOURCE_ID \ --location=LOCATION ``` Replace the following: - `TAGVALUE_NAME`: the permanent ID or namespaced name of the tag value that is attached---for example, `tagValues/567890123456`. - `RESOURCE_ID` is the full ID of the resource, including the API domain name to identify the type of resource (`//cloudkms.googleapis.com/`). For example, to attach a tag to `projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`, the full ID is: `//cloudkms.googleapis.com/projects/PROJECT_ID/locations/LOCATION_NAME/keyRings/KEYRING_NAME`. - `LOCATION`: the location of your resource. If you're attaching a tag to a global resource, such as a folder or a project, omit this flag. If you're attaching a tag to a regional or a zonal resource, you must specify the location---for example, `us-central1` (region) or `us-central1-a` (zone). ## Delete tag keys and values When removing a tag key or value definition, ensure that the tag is detached from the key ring. You must delete existing tag attachments, called tag bindings, before deleting the tag definition itself. To delete tag keys and tag values, see [Deleting tags](https://docs.cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing.md.txt#deleting). ## Identity and Access Management conditions and tags You can use tags and IAM conditions to conditionally grant role bindings to users in your hierarchy. Changing or deleting the tag attached to a resource can remove user access to that resource if an IAM policy with conditional role bindings has been applied. For more information, see [Identity and Access Management conditions and tags](https://docs.cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing.md.txt#iam_conditions_and_tags). ## What's next - See the other [services that support tags](https://docs.cloud.google.com/resource-manager/docs/tags/tags-supported-services.md.txt). - See [Tags and access control](https://docs.cloud.google.com/iam/docs/tags-access-control.md.txt) to learn how to use tags with IAM.