Actualiza los buckets de observabilidad

Puedes actualizar el nombre visible, la descripción o la clave de Cloud Key Management Service de un bucket de observabilidad para reflejar los cambios organizacionales o rotar las claves de encriptación.

No puedes usar estas operaciones de actualización para resolver problemas de cumplimiento. Por ejemplo, no puedes usar estas operaciones para cambiar la ubicación de un bucket de observabilidad ni aplicar una clave de Cloud KMS a un bucket que usa la encriptación predeterminada de Google.

Efectos de actualizar una clave de Cloud KMS

Actualizar la clave de Cloud KMS para un bucket de observabilidad no afecta los datos almacenados. Es decir, antes de que se complete la actualización, la clave original encripta los datos nuevos. Una vez que se completa la actualización, la clave actualizada encripta los datos nuevos.

Puedes seguir accediendo a los datos almacenados y consultándolos, siempre que la clave de Cloud KMS original permanezca habilitada y la cuenta de servicio de Google Cloud Observability conserve los permisos de encriptador o desencriptador.

Si inhabilitas o destruyes la clave de Cloud KMS original, los datos escritos mientras esa clave estaba activa se vuelven inaccesibles y no se pueden leer de forma permanente.

Limitaciones

Se aplican las siguientes restricciones:

  • No puedes modificar la ubicación.
  • No puedes aplicar una clave de Cloud KMS a un bucket de observabilidad que usa la encriptación predeterminada de Google.
  • El nombre visible no debe superar los 100 bytes codificados.
  • La descripción no debe superar los 1,000 bytes codificados.
  • Los datos se almacenan durante 30 días. Puedes omitir el período de retención o configurarlo como 30.
  • Si actualizas la clave de Cloud KMS, la ubicación de la clave debe coincidir exactamente con la ubicación superior del bucket de observabilidad.

Antes de comenzar

Configura tu proyecto y tus roles de IAM, y selecciona la interfaz que planeas usar.

Configura tu proyecto y tus 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. Para obtener los permisos que necesitas para crear buckets de observabilidad, pídele a tu administrador que te otorgue el rol de IAM de editor de Observability (roles/observability.editor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Configura interfaces

gcloud

Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI con el siguiente comando: 

gcloud init

REST

Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

    Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada.

Para obtener más información, consulta Autentícate para usar REST en la Google Cloud documentación de autenticación de.

Configura la clave de Cloud KMS

Es opcional. Si planeas actualizar la clave de Cloud KMS que usa el bucket de observabilidad, haz lo siguiente:

  1. Habilita la API de Cloud Key Management Service.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar la API

  2. Crea un llavero de claves y una clave.

    La ubicación del bucket de observabilidad debe coincidir con la ubicación de la clave.

  3. Reemplaza PROJECT_ID por el ID de tu proyecto y, luego, ejecuta el siguiente comando:

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

    La respuesta al comando anterior muestra el ID de la cuenta de servicio de Google Cloud Observability.

  4. Otorga el rol Encriptador/Desencriptador de CryptoKey de Cloud KMS a la cuenta de servicio de Google Cloud Observability.

    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

    Antes de ejecutar el comando anterior, realiza los siguientes reemplazos:

    • KMS_PROJECT_ID: Es el identificador alfanumérico único, compuesto por el nombre de tu proyecto Google Cloud y un número asignado de forma aleatoria, del proyecto que ejecuta Cloud KMS Google Cloud . Para obtener información sobre cómo obtener este identificador, consulta Cómo identificar proyectos.
    • service-PROJECT_NUMBER: Es el nombre de la cuenta de servicio de Google Cloud Observability que se enumeró en el paso anterior.
    • KMS_KEY_LOCATION: Es la región de la clave de Cloud KMS.
    • KMS_KEY_RING: Es el nombre del llavero de claves de Cloud KMS.
    • KMS_KEY_NAME: Es el nombre de la clave de Cloud KMS. Tiene el siguiente formato: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Actualiza un bucket de observabilidad

REST

Para actualizar un bucket de observabilidad, envía una solicitud a projects.locations.buckets.patch.

Debes especificar el parámetro superior, que identifica el bucket que se actualizará. Este parámetro tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Los campos de la expresión anterior tienen los siguientes significados:

  • PROJECT_ID: Es el identificador del proyecto.
  • LOCATION: Es la ubicación del bucket de observabilidad.
  • BUCKET_ID: Es el ID del bucket de observabilidad. Por ejemplo, este ID podría ser _Trace.

El parámetro de consulta debe especificar un campo updateMask, que identifica qué campos se modificarán. Por ejemplo:

  • Para actualizar la descripción, usa updateMask=description.
  • Para actualizar la clave de Cloud KMS y la descripción, usa updateMask=description,cmekSettings.kmsKey.

El cuerpo de la solicitud es un Bucket objeto. Debes propagar cada campo especificado por la máscara de actualización. No propagues los campos que no estés actualizando.

Por ejemplo, para actualizar solo el campo description, puedes usar el siguiente objeto Bucket:

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

La respuesta es un Operation objeto. Por lo general, este método tarda menos de un minuto en completarse.

Por lo general, para determinar si se completó un método que muestra un objeto Operationobjeto está completo, debes sondear el objeto llamando a projects.locations.operations.get hasta que el campo Operation.done se establezca en true. Luego, puedes usar otros campos en la estructura Operation para determinar si el método se realizó correctamente o falló.

Sin embargo, el método patch se completa rápidamente. Por lo tanto, una alternativa es esperar un minuto y, luego, verificar la actualización enumerando tus buckets de observabilidad.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • LOCATION: Es la ubicación de los buckets de observabilidad. Para enumerar todos los buckets de observabilidad, sin importar la ubicación, establece la ubicación en un guion (-).
  • PROJECT_ID: Es el identificador del proyecto.

Ejecuta el gcloud beta observability buckets list comando:

Linux, macOS o 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

La respuesta muestra el nombre, la descripción y la hora de creación de cada buckets de observabilidad. A continuación, se muestra un ejemplo de respuesta cuando el comando se ejecuta correctamente: 

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

REST

Para enumerar los buckets de observabilidad que se encuentran en tu proyecto y en una ubicación específica, envía una solicitud al extremo projects.locations.buckets.list.

Debes especificar el parámetro superior, que tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION

Los campos de la expresión anterior tienen los siguientes significados:

  • PROJECT_ID: Es el identificador del proyecto.
  • LOCATION: Es la ubicación del bucket de observabilidad. Si estableces LOCATION en un guion, (-), se enumerarán todos los buckets de observabilidad de tu proyecto.

La respuesta es un array de Bucket objetos. Para cada objeto, el valor del campo name tiene el siguiente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Por ejemplo, cuando se emitió un comando al extremo buckets.list con el parámetro superior establecido en projects/my-project/locations/us, la respuesta fue la siguiente:

{
  "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
    }
  ]
}

Puedes emitir comandos a otros extremos de la API de Observability para obtener más información sobre el bucket cuyo ID es BUCKET_ID. Por ejemplo, puedes enumerar los conjuntos de datos en ese bucket, y las vistas y los vínculos en cada conjunto de datos. Para obtener una lista completa de los extremos de la API de Observability, consulta la documentación de referencia de la API de Observability.

¿Qué sigue?