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.

  1. 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.

  2. 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.

  3. 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.

  4. Enable the Cloud KMS Inventory API.

    Enable the API

View key usage information

Console

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

    Go to Key Inventory

  2. 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.

  3. Click the name of the key for which you want to view usage information.

  4. Click the Usage Tracking tab.

  5. 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
    Artifact Registry artifactregistry.googleapis.com/Repository
    BigQuery bigquery.googleapis.com/Dataset
    BigQuery bigquery.googleapis.com/Model
    BigQuery bigquery.googleapis.com/Table
    BigQuery bigquerydatatransfer.googleapis.com/TransferConfig
    Bigtable bigtableadmin.googleapis.com/Backup
    Bigtable bigtableadmin.googleapis.com/Cluster
    Bigtable bigtableadmin.googleapis.com/Table
    Cloud Composer composer.googleapis.com/Environment
    Cloud Data Fusion datafusion.googleapis.com/Instance
    Cloud Healthcare API healthcare.googleapis.com/Dataset
    Cloud Logging logging.googleapis.com/LogBucket
    Cloud Run run.googleapis.com/Revision
    Cloud Run functions cloudfunctions.googleapis.com/CloudFunction
    Cloud Run functions cloudfunctions.googleapis.com/Function
    Cloud SQL sqladmin.googleapis.com/BackupRun
    Cloud SQL sqladmin.googleapis.com/Instance
    Cloud Storage storage.googleapis.com/Bucket
    Cloud Workstations workstations.googleapis.com/Workstation
    Cloud Workstations workstations.googleapis.com/WorkstationConfig
    Compute Engine compute.googleapis.com/Disk
    Compute Engine compute.googleapis.com/Image
    Compute Engine compute.googleapis.com/MachineImage
    Compute Engine compute.googleapis.com/Snapshot
    Database Migration Service datamigration.googleapis.com/MigrationJob
    Database Migration Service datamigration.googleapis.com/ConnectionProfile
    Dataflow dataflow.googleapis.com/Job
    Dataproc dataproc.googleapis.com/Cluster
    Dataproc dataproc.googleapis.com/Batch
    Dataproc Metastore metastore.googleapis.com/Service
    Datastream datastream.googleapis.com/Stream
    Document AI documentai.googleapis.com/HumanReviewConfig
    Document AI documentai.googleapis.com/Processor
    Document AI documentai.googleapis.com/ProcessorVersion
    Filestore file.googleapis.com/Instance
    Filestore file.googleapis.com/Backup
    Firestore firestore.googleapis.com/Database
    Firestore datastore.googleapis.com/Database
    Google Kubernetes Engine container.googleapis.com/Cluster
    Looker (Google Cloud core) looker.googleapis.com/Instance
    Memorystore for Redis redis.googleapis.com/Instance
    Migrate to Virtual Machines vmmigration.googleapis.com/Source
    Pub/Sub pubsub.googleapis.com/Topic
    Secret Manager secretmanager.googleapis.com/Secret
    Secret Manager secretmanager.googleapis.com/SecretVersion
    Secure Source Manager securesourcemanager.googleapis.com/Instance
    Spanner spanner.googleapis.com/Database
    Vertex AI aiplatform.googleapis.com/Dataset
    Vertex AI aiplatform.googleapis.com/Featurestore
    Vertex AI aiplatform.googleapis.com/Tensorboard
    Vertex AI aiplatform.googleapis.com/BatchPredictionJob
    Vertex AI aiplatform.googleapis.com/CustomJob
    Vertex AI aiplatform.googleapis.com/Endpoint
    Vertex AI aiplatform.googleapis.com/Model
    Vertex AI aiplatform.googleapis.com/TrainingPipeline
    Vertex AI aiplatform.googleapis.com/PipelineJob
    Vertex AI aiplatform.googleapis.com/MetadataStore
    Vertex AI Agent Builder discoveryengine.googleapis.com/DataStore
    Vertex AI Workbench instances notebooks.googleapis.com/Instance
    Workflows workflows.googleapis.com/Workflow