Update observability buckets

You can update the display name, description, or Cloud Key Management Service key of an observability bucket to reflect organizational changes or rotate encryption keys.

You can't use these update operations to resolve compliance issues. For example, you can't use these operations to change the location of an observability bucket or apply a Cloud KMS key to a bucket that uses Google-default encryption.

Effects of updating a Cloud KMS key

Updating the Cloud KMS key for an observability bucket doesn't affect stored data. That is, before the update completes, the original key encrypts new data. After the update completes, the updated key encrypts new data.

You can continue to access and view the stored data provided that the original Cloud KMS key remains enabled and the Google Cloud Observability service account retains the encrypter/decrypter permissions.

If you disable or destroy the original Cloud KMS key, then any data written while that key was active immediately becomes permanently inaccessible and unreadable.

Limitations

The following restrictions apply:

  • You can't modify the location.
  • You can't apply a Cloud KMS key to an observability bucket that uses Google-default encryption.
  • The display name must not exceed 100 encoded bytes.
  • The description must not exceed 1000 encoded bytes.
  • Data is stored for 30 days. You can omit the retention period or set it to 30.
  • If you update the Cloud KMS key, then the location of the key must exactly match the parent location of the observability bucket.

Before you begin

Configure your project and your IAM roles, and select the interface that you plan to use.

Configure your project and roles

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. To get the permissions that you need to create observability buckets, ask your administrator to grant you the Observability Editor (roles/observability.editor) IAM role on your project. 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.

Configure interfaces

gcloud

Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

gcloud init

REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

    Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Configure Cloud KMS key

Optional. If you plan to update the Cloud KMS key that the observability bucket uses, then do the following:

  1. Enable the Cloud Key Management Service API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  2. Create a key ring and key.

    The location of the observability bucket must match the location of the key.

  3. Replace PROJECT_ID with your project's ID, and then run the following command:

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    The response to the preceding command lists the ID of the Google Cloud Observability service account.

  4. Grant the Cloud KMS CryptoKey Encrypter/Decrypter role to the Google Cloud Observability service account.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    Before running the preceding command, make the following replacements:

    • KMS_PROJECT_ID: The unique alphanumeric identifier, composed of your Google Cloud project name and a randomly assigned number, of the Google Cloud project running Cloud KMS. For information about getting this identifier, see Identifying projects.
    • service-PROJECT_NUMBER: The name of the Google Cloud Observability service account that was listed in the preceding step.
    • KMS_KEY_LOCATION: The Cloud KMS key's region.
    • KMS_KEY_RING: The Cloud KMS key ring's name.
    • KMS_KEY_NAME: The Cloud KMS key's name. It is formatted like this: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Update an observability bucket

REST

To update an observability bucket, send a request to projects.locations.buckets.patch.

You must specify the parent parameter, which identifies the bucket to update. This parameter has the following form:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

The fields in the preceding expression have the following meanings:

  • PROJECT_ID: The identifier of the project.
  • LOCATION: The location of the observability bucket.
  • BUCKET_ID: The ID of the observability bucket. For example, this ID might be _Trace.

The query parameter must specify an updateMask field, which identifies which fields to modify. For example:

  • To update the description, use updateMask=description.
  • To update the Cloud KMS key and the description, use updateMask=description,cmekSettings.kmsKey.

The request body is a Bucket object. You must populate every field specified by the update mask. Don't populate fields that you aren't updating.

For example, to update only the description field, you could use the following Bucket object:

{
    "description": "Updated description for my observability bucket."
}

The response is an Operation object. Typically, this method takes less than a minute to complete.

Typically, to determine whether a method that returns an Operation object is complete, you poll the object by calling projects.locations.operations.get until the Operation.done field is set to true. You can then use other fields in the Operation structure to determine whether the method succeeded or failed.

However, the patch method completes quickly. Therefore, an alternative is to wait a minute and then verify the update by listing your observability buckets.

gcloud

Before using any of the command data below, make the following replacements:

  • LOCATION: The location of the observability buckets. To list all observability buckets, regardless of location, set the location to a hyphen (-).
  • PROJECT_ID: The identifier of the project..

Execute the gcloud beta observability buckets list command:

Linux, macOS, or Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

The response lists the name, description, and create time of each observability buckets. The following is an example of a response when the command is successful: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

To list the observability buckets that are in your project and in a specific location, send a request to the projects.locations.buckets.list endpoint.

You must specify the parent parameter, which has the following form:

projects/PROJECT_ID/locations/LOCATION

The fields in the previous expression have the following meanings:

  • PROJECT_ID: The identifier of the project.
  • LOCATION: The location of the observability bucket. If you set LOCATION to a hyphen, (-), then all observability buckets in your project are listed.

The response is an array of Bucket objects. For each object, the value of the name field has the following format:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

For example, when a command was issued to the buckets.list endpoint with the parent parameter set to projects/my-project/locations/us, the response was:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

You can issue commands to other Observability API endpoints to get more information about the bucket whose ID is BUCKET_ID. For example, you can list the datasets on that bucket, and the views and links on each dataset. For a complete list of Observability API endpoints, see the Observability API reference documentation.

What's next