View key usage

This topic shows you how to view the Google Cloud resources within your organization that are protected by your Cloud KMS keys.

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 topic assumes that you're using Cloud KMS within a Google Cloud organization resource.

Have your organization administrator grant your Cloud KMS service account the Cloud KMS Organization Service Agent (cloudkms.orgServiceAgent) role on your organization resource. This role isn't available in the Google Cloud console, so you must use the gcloud CLI to grant the role:
gcloud CLI
```
gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member="serviceAccount:service-org-ORGANIZATION_ID@gcp-sa-cloudkms.iam.gserviceaccount.com" \
    --role='roles/cloudkms.orgServiceAgent'
```
Replace ORGANIZATION_ID with the numerical ID of your organization.
Grant the Cloud KMS Viewer (roles/cloudkms.viewer) role to anyone who needs to view key usage summaries. For information about granting roles, see Manage access.
Grant the Cloud KMS Protected Resources Viewer (roles/cloudkms.protectedResourcesViewer) role on your organization resource to anyone who needs to view key usage details. This role isn't available in the Google Cloud console, so you must use the gcloud CLI to grant the role:
gcloud CLI
```
gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member="user:USER_EMAIL" \
    --role='roles/cloudkms.protectedResourcesViewer'
```
Replace the following:
- ORGANIZATION_ID: the numerical ID of your organization.
- USER_EMAIL: the email address of the user.
Enable the Cloud KMS Inventory API.
Enable the API

View key usage information

Console

In the Google Cloud console, go to the Key Inventory page.

Go to Key Inventory
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:

aiplatform.googleapis.com/BatchPredictionJob
aiplatform.googleapis.com/CustomJob
aiplatform.googleapis.com/Dataset
aiplatform.googleapis.com/Endpoint
aiplatform.googleapis.com/Featurestore
aiplatform.googleapis.com/Model
aiplatform.googleapis.com/PipelineJob
aiplatform.googleapis.com/Tensorboard
aiplatform.googleapis.com/TrainingPipeline
artifactregistry.googleapis.com/Repository
bigquery.googleapis.com/Dataset
bigquery.googleapis.com/Model
bigquery.googleapis.com/Table
bigquerydatatransfer.googleapis.com/TransferConfig
bigtableadmin.googleapis.com/Backup
bigtableadmin.googleapis.com/Cluster
bigtableadmin.googleapis.com/Table
cloudfunctions.googleapis.com/CloudFunction
cloudfunctions.googleapis.com/Function
composer.googleapis.com/Environment
compute.googleapis.com/Disk
compute.googleapis.com/Image
compute.googleapis.com/MachineImage
compute.googleapis.com/Snapshot
container.googleapis.com/Cluster
dataflow.googleapis.com/Job
datafusion.googleapis.com/Instance
datamigration.googleapis.com/ConnectionProfile
datamigration.googleapis.com/MigrationJob
dataproc.googleapis.com/Batch
dataproc.googleapis.com/Cluster
documentai.googleapis.com/HumanReviewConfig
documentai.googleapis.com/Processor
documentai.googleapis.com/ProcessorVersion
file.googleapis.com/Backup
file.googleapis.com/Instance
logging.googleapis.com/LogBucket
metastore.googleapis.com/Service
pubsub.googleapis.com/Topic
redis.googleapis.com/Instance
run.googleapis.com/Revision
secretmanager.googleapis.com/Secret
secretmanager.googleapis.com/SecretVersion
spanner.googleapis.com/Database
sqladmin.googleapis.com/BackupRun
sqladmin.googleapis.com/Instance
storage.googleapis.com/Bucket
workstations.googleapis.com/Workstation
workstations.googleapis.com/WorkstationConfig