É 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 girar chaves de criptografia.
Não é possível usar essas operações de atualização para resolver problemas de conformidade. Por exemplo, não é possível usar essas operações para mudar 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
A atualização da chave do Cloud KMS para 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. Após a conclusão da atualização, a chave atualizada criptografa novos dados.
Você pode 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 criptografador/descriptografador.
Se você desativar ou destruir a chave original do Cloud KMS, todos os dados gravados enquanto essa chave estava ativa ficarão permanentemente inacessíveis e ilegíveis.
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 seu projeto e seus papéis do IAM e selecione a interface que você planeja usar.
Configurar seu projeto e papéis
- Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Para receber as permissões necessárias para criar buckets de observabilidade, peça ao administrador para conceder a você o papel do IAM de editor de observabilidade (
roles/observability.editor) no seu 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 com papéis personalizados ou outros papéis predefinidos.
Configurar interfaces
gcloud
No Google Cloud console, ative o Cloud Shell.
Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
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 Google Cloud CLI.
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 que o bucket de observabilidade usa, faça o seguinte:
-
Ative a API Cloud Key Management Service.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter a 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, você pode receber essa permissão pelo papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. -
O local do bucket de observabilidade precisa corresponder ao local da chave.
Substitua PROJECT_ID pelo ID do seu projeto e execute o seguinte comando:
gcloud beta observability settings describe \ --location=global --project=PROJECT_IDA resposta ao comando anterior lista o ID da conta de serviço do Google Cloud Observability.
Conceda o papel Criptografador/Descriptografador do Cloud KMS CryptoKey à conta de serviço do Google Cloud Observability.
gcloud kms keys add-iam-policy-binding \ --project=KMS_PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability.iam.gserviceaccount.com \ --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \ --location=KMS_KEY_LOCATION \ --keyring=KMS_KEY_RING \ KMS_KEY_NAMEAntes de executar o comando anterior, faça as seguintes substituições:
- KMS_PROJECT_ID: o identificador alfanumérico exclusivo, composto pelo nome do Google Cloud projeto e um número atribuído aleatoriamente, do Google Cloud projeto que executa o Cloud KMS. Para informações sobre como receber esse identificador, consulte Identificar projetos.
- service-PROJECT_NUMBER: o nome da conta de serviço do Google Cloud Observability 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 desta maneira:
projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.
Atualizar um bucket de observabilidade
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 modificar. Por 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 Bucket objeto. É preciso preencher todos os campos especificados pela máscara de atualização. Não preencha os campos que não estão sendo atualizados.
Por exemplo, para atualizar apenas o campo description, você pode usar o seguinte objeto Bucket:
{
"description": "Updated description for my observability bucket."
}
A resposta é um Operation objeto.
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ê consulta o objeto chamando projects.locations.operations.get até que o campo Operation.done seja definido como true. Em seguida, é possível usar outros campos na estrutura Operation para determinar se o método foi bem-sucedido ou falhou.
No entanto, o método patch é concluído rapidamente. Portanto, uma alternativa é aguardar um minuto e verificar a atualização listando seus buckets de observabilidade.
gcloud
Antes de usar os dados do comando abaixo, faça estas substituições:
- LOCATION: o local dos buckets de observabilidade. Para listar todos os buckets de observabilidade,
independente do local, defina o local como um hífen (
-). - PROJECT_ID: o identificador do projeto.
Execute o
gcloud beta observability buckets list
comando:
Linux, macOS ou 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
A resposta lista o nome, a descrição e o horário de criação de cada bucket de observabilidade. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:
--- 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 listar os buckets de observabilidade que estão no seu projeto e em um local específico, envie uma solicitação para o
projects.locations.buckets.list
endpoint.
É preciso especificar o parâmetro pai, que tem o seguinte formato:
projects/PROJECT_ID/locations/LOCATION
Os campos na expressão anterior têm os seguintes significados:
- PROJECT_ID: o identificador do projeto.
- LOCATION: O local do bucket de observabilidade.
Se você definir LOCATION como um hífen,
(-), todos os buckets de observabilidade no seu projeto serão listados.
A resposta é uma matriz de
Bucket objetos. Para cada objeto, o valor do campo name tem o seguinte formato:
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
Por exemplo, quando um comando foi emitido para o endpoint buckets.list com o parâmetro pai definido como projects/my-project/locations/us, a resposta foi:
{
"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
}
]
}
É possível emitir comandos para outros endpoints da API Observability para receber mais informações sobre o bucket cujo ID é BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados nesse bucket e as visualizações e links em cada conjunto de dados. Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.