Atualizar buckets de observabilidade

É possível atualizar o nome de exibição, a descrição ou a chave do Cloud Key Management Service de um bucket de observabilidade para refletir mudanças organizacionais ou alternar chaves de criptografia.

Não é possível usar essas operações de atualização para resolver problemas de compliance. Por exemplo, não é possível usar essas operações para alterar o local de um bucket de observabilidade ou aplicar uma chave do Cloud KMS a um bucket que usa a criptografia padrão do Google.

Efeitos da atualização de uma chave do Cloud KMS

Atualizar a chave do Cloud KMS de um bucket de observabilidade não afeta os dados armazenados. Ou seja, antes da conclusão da atualização, a chave original criptografa novos dados. Depois que a atualização for concluída, a chave atualizada vai criptografar os novos dados.

É possível continuar acessando e visualizando os dados armazenados, desde que a chave original do Cloud KMS permaneça ativada e a conta de serviço do Google Cloud Observability mantenha as permissões de criptografia/descriptografia.

Se você desativar ou destruir a chave original do Cloud KMS, todos os dados gravados enquanto essa chave estava ativa ficarão imediatamente inacessíveis e ilegíveis de forma permanente.

Limitações

As seguintes restrições são aplicadas:

• Não é possível modificar o local.
• Não é possível aplicar uma chave do Cloud KMS a um bucket de observabilidade que usa a criptografia padrão do Google.
• O nome de exibição não pode exceder 100 bytes codificados.
• A descrição não pode exceder 1.000 bytes codificados.
• Os dados são armazenados por 30 dias. É possível omitir o período de armazenamento ou defini-lo como 30.
• Se você atualizar a chave do Cloud KMS, o local dela precisará corresponder exatamente ao local pai do bucket de observabilidade.

Antes de começar

Configure o projeto e os papéis do IAM e selecione a interface que você planeja usar.

Configurar o projeto e os papéis

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

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

1. Para receber as permissões necessárias para atualizar buckets de observabilidade, peça ao administrador para conceder a você o papel do IAM de Editor de observabilidade (roles/observability.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar interfaces

gcloud

Observação: use a CLI gcloud versão 586.0.0 ou mais recente.

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

Terraform

Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

1. Instale a CLI do Google Cloud.

2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

   gcloud auth application-default login

   Não é necessário fazer isso se você estiver usando o Cloud Shell.

   Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

Saiba mais em Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Configurar a chave do Cloud KMS

Opcional. Se você planeja atualizar a chave do Cloud KMS usada pelo bucket de observabilidade, faça o seguinte:

1. Ative a API Cloud Key Management Service, se ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

2. Crie um keyring e uma chave.

   O local do bucket de observabilidade precisa corresponder ao local da chave.

3. Substitua PROJECT_ID pelo ID do projeto e execute o seguinte comando:

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

   A resposta ao comando anterior lista o ID da conta de serviço do Google Cloud Observability.

4. Conceda o papel Criptografador/Descriptografador de CryptoKey do Cloud KMS à conta de serviço do Google Cloud Observability.

   gcloud kms keys add-iam-policy-binding \
   --project=KMS_PROJECT_ID \
   --member=serviceAccount:[e-mail] \
   --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
   --location=KMS_KEY_LOCATION \
   --keyring=KMS_KEY_RING \
   KMS_KEY_NAME
   

   Antes de executar o comando anterior, faça as seguintes substituições:

   • KMS_PROJECT_ID: o identificador alfanumérico exclusivo, composto pelo nome do projeto do Google Cloud e um número atribuído aleatoriamente, do projeto do Google Cloud que executa o Cloud KMS. Para saber como conseguir esse identificador, consulte Como identificar projetos.
   • service-PROJECT_NUMBER: o nome da conta de serviço do Google Cloud Observability que foi listada na etapa anterior.
   • KMS_KEY_LOCATION: a região da chave do Cloud KMS.
   • KMS_KEY_RING: o nome do keyring do Cloud KMS.
   • KMS_KEY_NAME: o nome da chave do Cloud KMS. Ele é formatado assim: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Atualizar um bucket de observabilidade

gcloud

Observação: use a CLI gcloud versão 586.0.0 ou mais recente.

Antes de usar os dados do comando abaixo, faça estas substituições:

• BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, esse ID pode ser _Trace.
• LOCATION: o local do bucket de observabilidade.
• DESCRIPTION: uma descrição Este campo é opcional.
• DISPLAY_NAME: o nome de exibição Este campo é opcional.
• PROJECT_ID: o identificador do projeto.

O comando da CLI gcloud também oferece opções para atualizar a chave do Cloud KMS. Para ver mais informações, consulte gcloud observability buckets update.

Execute o comando gcloud observability buckets update:

Linux, macOS ou Cloud Shell

gcloud observability buckets update BUCKET_ID \
 --location=LOCATION \
 --description="DESCRIPTION" \
 --display-name="DISPLAY_NAME" \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud observability buckets update BUCKET_ID `
 --location=LOCATION `
 --description="DESCRIPTION" `
 --display-name="DISPLAY_NAME" `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud observability buckets update BUCKET_ID ^
 --location=LOCATION ^
 --description="DESCRIPTION" ^
 --display-name="DISPLAY_NAME" ^
 --project=PROJECT_ID

O comando de atualização inicia uma operação de longa duração e bloqueia até que ela seja concluída. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

Request issued for: [_Trace]
Waiting for operation [projects/my-project/locations/us/operations/operation-1790096940299-65c156c3d730f-5fbc9362-10d93b76] to complete...done.
Updated bucket [_Trace].
createTime: '2026-09-09T21:06:30.590367694Z'
description: Updated bucket for storing trace data
displayName: Updated display name
name: projects/my-project/locations/us/buckets/_Trace
updateTime: '2026-09-22T17:09:00.301850190Z'

Terraform

Para atualizar o nome de exibição, a descrição ou a CMEK, use o recurso do Terraform google_observability_bucket e defina os seguintes campos:

• project: o ID do seu projeto.
• location: o local do bucket de observabilidade. Saiba mais em Locais.
• bucket_id: o ID do bucket de observabilidade. Esse campo precisa ser definido como _Trace.

Só é possível atualizar a descrição, o nome de exibição e a CMEK. Para mais informações, consulte a documentação do recurso.

REST

Para atualizar um bucket de observabilidade, envie uma solicitação para projects.locations.buckets.patch.

É preciso especificar o parâmetro pai, que identifica o bucket a ser atualizado. Esse parâmetro tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Os campos na expressão anterior têm os seguintes significados:

• PROJECT_ID: o identificador do projeto.
• LOCATION: o local do bucket de observabilidade.
• BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, esse ID pode ser _Trace.

O parâmetro de consulta precisa especificar um campo updateMask, que identifica quais campos serão modificados. Exemplo:

• Para atualizar a descrição, use updateMask=description.
• Para atualizar a chave do Cloud KMS e a descrição, use updateMask=description,cmekSettings.kmsKey.

O corpo da solicitação é um objeto Bucket. É necessário preencher todos os campos especificados pela máscara de atualização. Não preencha campos que você não está atualizando.

Por exemplo, para atualizar apenas o campo description, use o seguinte objeto Bucket:

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

A resposta é um objeto Operation. Normalmente, esse método leva menos de um minuto para ser concluído.

Normalmente, para determinar se um método que retorna um objeto Operation está concluído, você pesquisa o objeto chamando projects.locations.operations.get até que o campo Operation.done seja definido como true. Em seguida, use outros campos na estrutura Operation para determinar se o método foi bem-sucedido ou não.

No entanto, o método patch é concluído rapidamente. Portanto, uma alternativa é aguardar um minuto e verificar a atualização listando os buckets de observabilidade.

A seguir

• Ver e analisar a telemetria
• Definir padrões para buckets de observabilidade: configure um local de armazenamento padrão e uma chave de criptografia gerenciada pelo cliente (CMEK) padrão para seus buckets de observabilidade.