This page shows you how to view the Google Cloud resources within your organization that are protected by your Cloud KMS keys. Key usage tracking is only available within organization resources.
You can view information about the resources that your keys protect at two levels:
- Key usage summary information for each key includes the number of protected resources, projects, and unique Google Cloud products that use the key. This level of detail is available to anyone with the Cloud KMS Viewer role on the key.
- Key usage detail information identifies which resources are protected by and depend on this key. This level of detail is privileged and is only available to accounts with the Cloud KMS Protected Resources Viewer role on the organization.
Before you begin
This page assumes that you're using Cloud KMS within a Google Cloud organization resource.
- Enable the Cloud KMS Inventory API.
Required roles
To ensure that your Cloud KMS service account has the necessary
permissions to enable key usage tracking, ask your administrator to grant your
Cloud KMS service account the Cloud KMS Organization Service Agent
(roles/cloudkms.orgServiceAgent) IAM role
on your organization.
To get the permissions that you need to view key usage information, ask your administrator to grant you the following IAM roles on your keys:
-
To view key usage summaries:
Cloud KMS Viewer (
roles/cloudkms.viewer) -
To view key usage details:
Cloud KMS Protected Resources Viewer (
roles/cloudkms.protectedResourcesViewer)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
View key usage information
Console
In the Google Cloud console, go to the Key Inventory page.
Optional: To filter the list of keys, enter your search terms in the filter_list Filter box and then press enter. For example, you can filter by location, key ring, status, or other properties of the keys.
Click the name of the key for which you want to view usage information.
Click the Usage Tracking tab.
Optional: To filter the list of protected resources, enter your search terms in the filter_list Filter box and then press Enter.
Key usage summary and details are shown for the selected key.
gcloud CLI
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
To view the key usage summary, use the
get-protected-resources-summary method:
gcloud kms inventory get-protected-resources-summary \
--keyname projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME \
Replace the following:
PROJECT_ID: the ID of the project that contains the key ring.LOCATION: the Cloud KMS location of the key ring.KEY_RING: the name of the key ring that contains the key.KEY_NAME: the name of the key for which you want to view the usage summary.
To view key usage details, use the search-protected-resources method:
gcloud kms inventory search-protected-resources \
--keyname projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME \
--scope=organizations/ORGANIZATION_ID
Replace the following:
PROJECT_ID: the ID of the project that contains the key ring.LOCATION: the Cloud KMS location of the key ring.KEY_RING: the name of the key ring that contains the key.KEY_NAME: the name of the key for which you want to view usage details.ORGANIZATION_ID: the numerical ID of your organization.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To view the key usage summary, use the
cryptoKeys.getProtectedResourcesSummary method:
curl "https://kmsinventory.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/protectedResourcesSummary"
--request "GET" \
--header "x-goog-user-project: CALLING_PROJECT_ID"
--header "Content-Type: application/json" \
--header "Authorization: Bearer TOKEN"Replace the following:
PROJECT_ID: the ID of the project that contains the key ring.LOCATION: the Cloud KMS location of the key ring.KEY_RING: the name of the key ring that contains the key.KEY_NAME: the name of the key for which you want to view the usage summary.CALLING_PROJECT_ID: the ID of the project from which you are calling the KMS Inventory API.
To view key usage details, use the
protectedResources.search method:
curl "https://kmsinventory.googleapis.com/v1/organizations/ORGANIZATION_ID/protectedResources:search?crypto_key=projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
--request "GET" \
--header "x-goog-user-project: CALLING_PROJECT_ID"
--header "Content-Type: application/json" \
--header "Authorization: Bearer TOKEN"Replace the following:
ORGANIZATION_ID: the numerical ID of your organization.PROJECT_ID: the ID of the project that contains the key ring.LOCATION: the Cloud KMS location of the key ring.KEY_RING: the name of the key ring that contains the key.KEY_NAME: the name of the key for which you want to view usage details.CALLING_PROJECT_ID: the ID of the project from which you are calling the KMS Inventory API.
Key usage details
Usage details about the protected resources that are encrypted with the selected key include the following:
- Name: The name of the Google Cloud resource protected by the selected key.
- Project: The name of the project that contains the protected resource.
- Crypto key version: The key version used to encrypt this resource. Some protected resources don't report the crypto key version.
- Cloud product: The Google Cloud product associated with this resource.
- Resource type: The type of resource protected, for example Bucket (Cloud Storage) or Disk (Compute Engine).
- Location: The Google Cloud region associated with the resource.
- Creation date: The time at which the resource was created.
- Labels: A set of key-value pairs associated with the resource.
List key versions that protect a resource
If a resource is protected by several key versions, you might not be able to see the full list of key versions in the Usage tracking tab.
To list the key versions that protect a resource, use the gcloud CLI to run the following command:
gcloud beta kms inventory search-protected-resources \
--keyname=KEY_NAME \
--scope=organizations/ORGANIZATION_ID \
--filter="name:RESOURCE_NAME" \
--flatten="cryptoKeyVersions" \
--format="value(cryptoKeyVersions)"
Replace the following:
KEY_NAME: the name of the key for which you want to list key versions.ORGANIZATION_ID: the numerical ID of your organization.RESOURCE_NAME: the name of the resource for which you want to list key versions.
Limitations
When using key usage tracking, note the following:
- Key usage tracking is only available for CMEK key usage. If you're using a key version in your applications inside or outside of Google Cloud, that usage isn't included in the Usage tracking tab.
- Some CMEK resources aren't tracked. For resource types that aren't listed in
Tracked resource types, key usage information
might not be included in the key usage details. For example, key usage by
Datastream to encrypt
ConnectionProfile(datastream.googleapis.com/ConnectionProfile) resources isn't shown on the Usage tracking tab. - Data might be delayed. For example, if you create a new protected resource, the protected resource and associated key version aren't immediately added to the Usage tracking tab.
- Cloud Storage key usage data is subject to the following additional
limitations:
- Key usage data is aggregated from objects to buckets. Object names aren't shown. A bucket will be shown as using a key if the bucket has at least one object using that key.
- Key usage tracking might not be complete for buckets that contain objects protected with over 4000 unique key versions.
- Key usage tracking details are for informational purposes only. Conduct your own due diligence using other sources before making changes that could result in outages or loss of data. Don't disable or destroy key versions based only on key usage tracking information.
Tracked resource types
The following resource types are supported:
| Service | Resource |
|---|---|
| AlloyDB for PostgreSQL | your keys |
| AlloyDB for PostgreSQL | your keys |
| Apigee | your keys |
| Apigee | your keys |
| Apigee API hub | your keys |
| Artifact Registry | your keys |
| BigQuery | your keys |
| BigQuery | your keys |
| BigQuery | your keys |
| BigQuery | your keys |
| Bigtable | your keys |
| Bigtable | your keys |
| Bigtable | your keys |
| Cloud Composer | your keys |
| Cloud Data Fusion | your keys |
| Cloud Healthcare API | your keys |
| Cloud Logging | your keys |
| Cloud Run | your keys |
| Cloud Run functions | your keys |
| Cloud Run functions | your keys |
| Cloud SQL | your keys |
| Cloud SQL | your keys |
| Cloud Storage | your keys |
| Cloud Workstations | your keys |
| Cloud Workstations | your keys |
| Compute Engine | your keys |
| Compute Engine | your keys |
| Compute Engine | your keys |
| Compute Engine | your keys |
| Database Migration Service | your keys |
| Database Migration Service | your keys |
| Dataflow | your keys |
| Dataproc | your keys |
| Dataproc | your keys |
| Dataproc Metastore | your keys |
| Datastream | your keys |
| Document AI | your keys |
| Document AI | your keys |
| Document AI | your keys |
| Filestore | your keys |
| Filestore | your keys |
| Firestore | your keys |
| Firestore | your keys |
| Google Agentspace Enterprise | your keys |
| Google Kubernetes Engine | your keys |
| Looker (Google Cloud core) | your keys |
| Memorystore for Redis | your keys |
| Migrate to Virtual Machines | your keys |
| Pub/Sub | your keys |
| Secret Manager | your keys |
| Secret Manager | your keys |
| Secure Source Manager | your keys |
| Spanner | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI | your keys |
| Vertex AI Search | your keys |
| Vertex AI Workbench instances | your keys |
| Workflows | your keys |