Corrigir os requisitos de residência de dados e CMEK

É possível reprovisionar um bucket de observabilidade para atender aos requisitos regulatórios de residência de dados e criptografia. Após o reprovisionamento, o local de armazenamento e a configuração de criptografia do bucket _Trace correspondem às configurações padrão para buckets de observabilidade.

Para reprovisionar um bucket, defina as configurações padrão e chame o método de reprovisionamento. A operação de reprovisionamento pode fazer o seguinte:

  • Aplique retroativamente uma chave do Cloud Key Management Service a um bucket de observabilidade sem mudar o local de armazenamento.
  • Mudar o local de armazenamento de um bucket de observabilidade e usar a criptografia padrão do Google.
  • Mudar o local de armazenamento de um bucket de observabilidade e usar uma chave do Cloud KMS para criptografar os dados armazenados.

Não reprovisione um bucket de observabilidade quando quiser mudar o nome de exibição, a descrição ou a chave do Cloud KMS dele. Nesses casos, atualize o bucket de observabilidade.

Como funciona o reprovisionamento

Quando você inicia uma operação de reprovisionamento, o sistema executa as seguintes etapas:

  1. O sistema determina se o bucket de observabilidade está qualificado para reprovisionamento. Um bucket de observabilidade é qualificado quando todas as seguintes verificações são aprovadas:

    • O bucket de observabilidade é chamado de _Trace.
    • O bucket não foi reprovisionado.
    • As configurações padrão para buckets de observabilidade são encontradas.
    • Para que as configurações padrão sejam seguidas, o local do bucket de observabilidade precisa mudar ou a criptografia precisa ser alterada da criptografia padrão do Google para CMEK.

  2. O sistema atualiza a configuração do bucket. Esse processo leva de quatro a cinco horas.

Limitações

Considere as seguintes limitações:

  • O sistema permite no máximo uma operação de reprovisionamento por bucket de observabilidade. As solicitações subsequentes falham com um erro FAILED_PRECONDITION.

  • Só é possível reprovisionar buckets chamados _Trace.

  • Não é possível acessar dados armazenados antes do início do reprovisionamento. Esses dados foram excluídos e não podem ser recuperados.

  • Se o local do bucket mudar, os links e os conjuntos de dados vinculados do BigQuery serão excluídos. É necessário recriar os links.

  • Se o local do bucket mudar, você precisará atualizar manualmente as visualizações de análise atuais.

  • Não é possível cancelar ou desfazer uma operação de reprovisionamento. As tentativas de cancelar a operação são ignoradas.

  • O comportamento das consultas durante uma operação de reprovisionamento é indefinido.

Auditoria

Para determinar o histórico de reprovisionamento de um bucket de observabilidade, use os registros de auditoria. Os registros de atividades do administrador registram quem fez uma solicitação de reprovisionamento, o bucket de observabilidade afetado e a resposta inicial.

Para encontrar esses registros, aplique os seguintes filtros na Análise de Registros:

logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity" AND
resource.type="audited_resource" AND
resource.labels.service="observability.googleapis.com" AND
resource.labels.method="google.cloud.observability.v1.Observability.ReprovisionBucket"

O exemplo parcial a seguir mostra um registro de auditoria de atividade do administrador:

  {
    "logName": "projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity",
    "resource": {
      "type": "audited_resource",
      "labels": {
        "project_id": "PROJECT_ID",
        "service": "observability.googleapis.com",
        "method": "google.cloud.observability.v1.Observability.ReprovisionBucket"
      }
    },
    "protoPayload": {
      "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
      "status": {
        "code": 0,
        "message": "OK"
      },
      ...
      "serviceName": "observability.googleapis.com",
      "methodName": "google.cloud.observability.v1.Observability.ReprovisionBucket",
      "authorizationInfo": [...]
      "resourceName": "projects/PROJECT_ID/locations/us/buckets/_Trace",
      "request": {
        "@type": "type.googleapis.com/google.cloud.observability.v1.ReprovisionBucketRequest",
        "name": "projects/PROJECT_ID/locations/us/buckets/_Trace"
      },
      "response": {
        "@type": "type.googleapis.com/google.longrunning.Operation",
        "name": "projects/PROJECT_ID/locations/us/operations/reprovision-123456789-0",
        "done": false,
        "metadata": {
          "@type": "type.googleapis.com/google.cloud.observability.v1.OperationMetadata",
          "target": "projects/PROJECT_ID/locations/us/buckets/_Trace",
          "verb": "reprovision",
          "apiVersion": "v1"
        }
      }
    },
    "severity": "NOTICE",
    "timestamp": "2026-06-30T16:54:02.123456Z"
  }

Antes de começar

  1. Leia sobre as Limitações.

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

    O papel de Editor de Observabilidade concede permissões para criar e excluir buckets de observabilidade, conjuntos de dados de observabilidade e links em conjuntos de dados. Você precisa dessas permissões porque a operação de reprovisionamento emite comandos de criação e exclusão.

    Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Reprovisionar um bucket de observabilidade

Para reprovisionar um bucket de observabilidade, siga estas etapas:

  1. Definir as configurações padrão para buckets de observabilidade
  2. Reprovisionar o bucket
  3. Monitorar o progresso
  4. Criar links manualmente e atualizar as visualizações de análise

Definir as configurações padrão para buckets de observabilidade

Defina um local de armazenamento padrão e, se quiser, uma chave padrão do Cloud KMS. É possível definir essas configurações no nível do projeto, da pasta ou da organização. Por exemplo, se você definir as configurações padrão para uma pasta, os descendentes dela vão usar essas configurações, a menos que um descendente também tenha configurações padrão definidas.

Para mais informações sobre como visualizar e definir as configurações padrão, consulte Definir padrões para buckets de observabilidade.

Reprovisionar o bucket

Use scripts que emitem a solicitação de reprovisionamento de forma assíncrona e faça uma sondagem para determinar quando a operação de reprovisionamento é concluída. Para reprovisionar um bucket de observabilidade, use o método projects.locations.buckets.reprovision.

Especifique o nome do bucket de observabilidade, que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

A resposta é um objeto Operation. O campo Operation.done fornece informações de progresso:

  • done é false: a operação está em andamento. Para informações sobre como fazer uma sondagem da operação, consulte Monitorar o progresso.

  • done é true: a operação foi concluída e o campo error ou response está definido:

    • response está definido: indica a conclusão da operação assíncrona. O valor reflete o estado mais recente do bucket de observabilidade que era o destino de reprovisionamento.

    • error está definido: indica que a operação assíncrona falhou. O valor desse campo é um objeto Status que contém um código do erro do gRPC e uma mensagem de erro. Para informações sobre mensagens de erro comuns, consulte Mensagens de erro.

O reprovisionamento geralmente leva de quatro a cinco horas para ser concluído.

Monitorar o progresso

O objeto Operation contém informações de progresso. Sonde a operação até que o valor do campo Operation.done seja true. Em seguida, use os campos Operation.response e Operation.error para determinar se o reprovisionamento foi bem-sucedido ou não.

Para consultar o Operation, use o método folders.locations.operations.get.

Defina o parâmetro de caminho como o nome da operação:

operations/UNIQUE_ID

O campo UNIQUE_ID é o identificador exclusivo da operação.

A resposta é um objeto Operation atualizado.

Se o aplicativo receber uma resposta HTTP 503 / UNAVAILABLE ao fazer a sondagem, implemente uma espera exponencial e tente novamente a solicitação. Esse erro indica que a solicitação falhou na camada de transporte ou de rede.

Criar links e atualizar visualizações de análise manualmente

Depois que a operação de reprovisionamento for concluída, recrie os links e atualize as visualizações de análise.

Por exemplo, você pode fazer o seguinte:

  1. Liste os links no conjunto de dados de observabilidade. Em alguns cenários, a operação de reprovisionamento mantém os links. Para mais informações sobre essa etapa, consulte Listar links em um conjunto de dados.

  2. Recrie o conjunto de dados vinculado do BigQuery. Para mais informações sobre essa etapa, consulte Criar um link em um conjunto de dados.

  3. Revise as visualizações de análise e atualize o caminho para o bucket de observabilidade, conforme necessário.

Mensagens de erro

Nesta seção, listamos códigos do erro comuns e, quando aplicável, ações de recuperação.

FAILED_PRECONDITION

A mensagem de erro FAILED_PRECONDITION indica que o bucket de observabilidade não está qualificado para reprovisionamento.

Exemplo de mensagem de erro:

{
    "error":{
        "code": 400,
        "message": "Only _Trace buckets can be reprovisioned.",
        "status": "FAILED_PRECONDITION",
        "details": [ ... ]
    }
}

Não há nenhuma ação que você possa realizar para tornar o bucket de observabilidade qualificado para o reprovisionamento.

INVALID_ARGUMENT

A mensagem de erro INVALID_ARGUMENT indica que o local do bucket de observabilidade e a configuração da CMEK são consistentes com as configurações padrão dos buckets de observabilidade.

Para resolver essa falha, atualize as configurações padrão dos buckets de observabilidade do projeto, da pasta ou da organização e tente reprovisionar o bucket de observabilidade.

PERMISSION_DENIED

A mensagem de erro PERMISSION_DENIED indica que você não tem os papéis do IAM necessários para reprovisionar um bucket de observabilidade.

Para resolver essa falha, peça a um administrador para conceder a você os papéis do IAM listados na seção Antes de começar deste documento.

Solução de problemas

Nesta seção, descrevemos como resolver problemas comuns e responder a perguntas que podem surgir depois que você reprovisionar um bucket de observabilidade.

Como saber se um bucket foi reprovisionado?

Consulte os registros de auditoria e filtre as entradas de registro por nome, serviço e método. Para mais informações, consulte a seção deste documento intitulada Auditoria.

Por que meu projeto lista dois buckets para dados de trace?

Durante uma nova provisionamento do bucket de observabilidade _Trace, o sistema pode precisar criar um novo bucket. Quando esse valor é verdadeiro, o projeto contém dois buckets de observabilidade chamados _Trace durante a operação de reprovisionamento.

  • Se você listar os buckets de observabilidade no seu projeto, os dois buckets serão informados nos resultados.

  • Se você usa a Análise de Observabilidade para consultar seus dados de trace, uma visualização _AllSpans está disponível para os dois buckets.

Não é necessário realizar nenhuma ação.

Se o sistema tiver criado um bucket de observabilidade como parte de uma operação de reprovisionamento, após a conclusão dessa operação, o bucket de destino será excluído. Se a operação de reprovisionamento falhar, o novo bucket será excluído.

Por que meus dados consultados são diferentes após o reprovisionamento?

Uma operação de reprovisionamento exclui todos os dados que foram armazenados antes do início da operação. Não é possível recuperar esses dados.

Por que o Trace Explorer não mostra dados após o reprovisionamento?

O Trace Explorer usa o cache para melhorar o desempenho. O cache está vinculado ao bucket de observabilidade que está sendo consultado e, se esse bucket não estiver disponível no momento de uma consulta, ela vai falhar.

Durante uma operação de reprovisionamento, é possível que o projeto do Google Cloud contenha dois buckets de observabilidade chamados _Trace. Além disso, quando essa operação é concluída, um desses buckets é excluído. Nesse cenário, é possível que o cache usado pelo Trace Explorer esteja vinculado a um bucket que não existe mais.

Essa falha é corrigida automaticamente após o tempo limite do cache, o que leva cerca de 10 minutos.

Por que meu bucket de observabilidade não pode ser provisionado novamente?

Se uma operação de reprovisionamento falhar com um status FAILED_PRECONDITION, o bucket de observabilidade de destino não estará qualificado para reprovisionamento. Veja a seguir alguns motivos para um bucket não estar qualificado para reprovisionamento:

  • O bucket de observabilidade não se chama _Trace.
  • O número de vezes que o bucket de observabilidade foi reprovisionado excede um. É possível consultar os registros de auditoria para determinar se o bucket foi reprovisionado.
  • As configurações padrão para buckets de observabilidade não foram encontradas. Para resolver essa falha, defina as configurações padrão para buckets de observabilidade e tente executar o comando novamente.
  • A configuração do bucket de observabilidade está de acordo com as configurações padrão. Ou seja, a operação de reprovisionamento não vai mudar a configuração do bucket de observabilidade.
  • Para estar de acordo com as configurações padrão, o sistema precisaria substituir a CMEK pela criptografia gerenciada pelo Google. Esta ação não é aceita.