Recolocar buckets

Esta página descreve o processo de realocar buckets de um local para outro. Para informações sobre a realocação de buckets, consulte Realocação de buckets.

Antes de começar

Antes de iniciar o processo de realocação do bucket, siga estas etapas:

  1. Ativar o Hub de gerenciamento.

  2. Ative a exclusão reversível.

  3. Verifique as cotas e os limites para garantir que o novo local tenha cotas suficientes para acomodar os dados do bucket.

  4. Determine o tipo de realocação do bucket para entender se o tempo de inatividade de gravação é necessário.

  5. Remova todas as tags de bucket.

  6. Se você usa relatórios de inventário, salve suas configurações.

Funções exigidas

Para receber as permissões de realocar buckets de um local para outro, peça ao administrador para conceder a você o papel de Administrador do Storage (roles/storage.admin) no projeto.

Esse papel fornece um conjunto de permissões que permite realocar buckets de um local para outro. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

O usuário autenticado precisa ter as seguintes permissões do IAM no bucket para usar esse método:

  • storage.buckets.relocate
  • storage.bucketOperations.get
    Você precisa dessa permissão para conferir o status da operação de realocação do bucket.
  • storage.bucketOperations.list
    Você precisa dessa permissão para conferir a lista de operações de realocação de bucket.
  • storage.bucketOperations.cancel
    Você precisa dessa permissão para cancelar a operação de realocação do bucket.

O usuário autenticado também pode precisar das seguintes permissões no bucket para usar esse método:

  • storage.bucket.get
    Você precisa dessa permissão para acessar os metadados de um bucket durante o teste de execução e a cópia incremental de dados da operação de realocação do bucket.
  • storage.objects.list e storage.objects.get
    Você precisa dessas permissões para ver a lista de objetos em um bucket que você quer transferir para outro local.

Também é possível conseguir essas permissões com papéis personalizados ou outros papéis predefinidos. Para conferir quais papéis estão associados a quais permissões, consulte Papéis do IAM para o Cloud Storage.

Para instruções sobre como conceder papéis a projetos, consulte Gerenciar o acesso a projetos.

Recolocar buckets

Esta seção descreve o processo de realocar buckets do Cloud Storage de um local para outro com a realocação de bucket. Ao realocar um bucket, você inicia o processo de cópia de dados incrementais, o monitora e, em seguida, inicia a etapa final de sincronização. Para mais informações sobre essas etapas, consulte Entender o processo de realocação de bucket.

Executar uma simulação

Para minimizar possíveis problemas durante o processo de realocação de bucket, recomendamos que você faça um teste. Uma simulação simula o processo de realocação de bucket sem mover dados, ajudando você a detectar e resolver problemas desde o início. A simulação verifica as seguintes incompatibilidades:

Embora um teste de simulação não possa identificar todos os problemas possíveis, já que alguns podem surgir apenas durante a migração ativa devido a fatores como a disponibilidade de recursos em tempo real, ele reduz o risco de enfrentar problemas que consomem tempo durante a realocação real.

Linha de comando

Simule a simulação da mudança de bucket:

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

Em que:

  • BUCKET_NAME é o nome do bucket que você quer realocar.

  • LOCATION é o local de destino do bucket.

A iniciação de um teste simulado inicia uma operação de longa duração. Você vai receber um ID e uma descrição da operação. Para acompanhar a conclusão do teste, você precisa acompanhar o progresso dele. Para saber como monitorar o progresso do teste, consulte Acessar detalhes de uma operação de longa duração.

Se o teste de simulação revelar algum problema, resolva-o antes de prosseguir para a etapa Iniciar a etapa de cópia de dados incrementais.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um arquivo JSON com as configurações do bucket, que precisa incluir os parâmetros destinationLocation e validateOnly. Consulte a documentação Buckets: relocate para conferir uma lista completa de configurações. Veja a seguir configurações comuns a serem incluídas:

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "true"
}

    Em que:

    • DESTINATION_LOCATION é o local de destino do bucket.
    • LOCATIONS é uma lista de códigos de local a serem usados na birregião configurável.
    • validateOnly é definido como true para realizar uma simulação.

  3. Use cURL para chamar a API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo JSON criado.
    • BUCKET_NAME é o nome do bucket que você quer realocar.

Iniciar a cópia incremental de dados

Linha de comando

Inicie a operação de realocação do bucket:

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

Em que:

  • BUCKET_NAME é o nome do bucket que você quer realocar.

  • LOCATION é o local de destino do bucket.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um arquivo JSON com as configurações do bucket. Consulte a documentação Buckets: relocate para conferir uma lista completa de configurações. Veja a seguir configurações comuns a serem incluídas:

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "false"
}

    Em que:

    • DESTINATION_LOCATION é o local de destino do bucket.
    • LOCATIONS é uma lista de códigos de local a serem usados na birregião configurável.
    • validateOnly é definido como false para iniciar a etapa de cópia de dados incrementais da realocação do bucket.

  3. Use cURL para chamar a API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo JSON criado.
    • BUCKET_NAME é o nome do bucket que você quer realocar.

Monitorar a cópia incremental de dados

O processo de realocação de bucket é uma operação de longa duração que precisa ser monitorada para verificar o progresso. É possível verificar regularmente a lista de operações de longa duração para conferir o status da etapa de cópia de dados incrementais. Para saber como conferir os detalhes de uma operação de longa duração, listá-las ou cancelá-las, consulte Usar operações de longa duração no Cloud Storage.

O exemplo a seguir mostra a saída gerada por uma operação de cópia de dados incrementais:

done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
  createTime: '2024-10-21T04:26:59.666Z
  endTime: '2024-12-29T23:39:53.340Z'
  progressPercent: 99
  requestedCancellation: false
  type: relocate-bucket
  updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
  byteProgressPercent: 100
  discoveredBytes: 200
  remainingBytes: 0
  discoveredObjectCount: 10
  remainingObjectCount: 8
  objectProgressPercent: 100
  discoveredSyncCount: 8
  remainingSyncCount: 0
  syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
  '@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
  selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w

A tabela a seguir fornece informações sobre os campos principais na saída gerada pela operação de cópia de dados incrementais:

Nome do campo Descrição Valores possíveis
done Indica a conclusão da operação de realocação do bucket. true, false
kind Indica que esse recurso representa uma operação de armazenamento.
metadata Fornece informações sobre a operação.
metadata.@type Indica o tipo de operação como uma mudança de bucket.
metadata.commonMetadata Metadados comuns a todas as operações.
metadata.commonMetadata.createTime A hora em que a operação de longa duração foi criada.
metadata.commonMetadata.endTime O horário em que a operação de longa duração foi concluída.
metadata.commonMetadata.progressPercent O progresso estimado da operação de longa duração, em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não se aplica.
metadata.commonMetadata.requestedCancellation Indica se o usuário solicitou o cancelamento da operação de longa duração. true, false
metadata.commonMetadata.type Indica o tipo da operação de longa duração.
metadata.commonMetadata.updateTime A hora em que a operação de longa duração foi atualizada pela última vez.
metadata.destinationLocation O local de destino do bucket.
metadata.finalizationState Indica que a etapa final de sincronização está pronta para ser iniciada.
  • READY: indica que você pode iniciar a etapa final de sincronização. No entanto, recomendamos que você aguarde até que o valor do campo progressPercent atinja 99.
  • WAITING_ON_SYNC: indica que não é possível iniciar a etapa final de sincronização.
  • NOT_REQUIRED: indica que a etapa final de sincronização não é necessária para este bucket e pode ser ignorada.
  • BLOCKED_ON_ERRORS: indica que a etapa de finalização está temporariamente pausada devido a erros. Você vai precisar resolver os erros para continuar a etapa.
  • RUNNING: indica que a etapa de finalização está em andamento.
  • FINALIZED: indica que a etapa de finalização foi concluída.
metadata.progress Detalhes do progresso da operação de realocação.
metadata.progress.byteProgressPercent Progresso dos bytes copiados em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não se aplica.
metadata.progress.discoveredBytes Número de bytes descobertos no bucket de origem.
metadata.progress.discoveredObjectCount Número de objetos descobertos no bucket de origem.
metadata.progress.discoveredSyncCount Número de atualizações de metadados de objetos descobertas no bucket de origem.
metadata.progress.objectProgressPercent O progresso dos objetos copiados em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não se aplica.
metadata.progress.remainingBytes Número de bytes restantes a serem copiados do bucket de origem para o de destino.
metadata.progress.remainingObjectCount Número de objetos restantes a serem copiados do bucket de origem para o de destino.
metadata.progress.remainingSyncCount Número de atualizações de metadados de objetos restantes a serem sincronizados.
metadata.progress.syncProgressPercent Progresso das atualizações de metadados do objeto a serem sincronizadas em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não se aplica.
metadata.relocationState Estado geral da realocação do bucket
  • SYNCING: indica que a etapa de cópia de dados incrementais está copiando objetos ativamente do bucket de origem para o de destino.
  • FINALIZING: indica que a etapa de finalização foi iniciada.
  • FAILED: indica que a etapa de cópia de dados incrementais encontrou um erro e não foi concluída.
  • SUCCEEDED: indica que a etapa de cópia de dados incrementais foi concluída.
  • CANCELLED: indica que a etapa de cópia de dados incrementais foi cancelada.
metadata.sourceLocation O local de origem do bucket.
metadata.validateOnly Indica se um teste de simulação da mudança de local do bucket foi iniciado. true, false
metadata.writeDowntimeExpireTime O tempo em que o período de inatividade de gravação expira.
name O identificador exclusivo dessa operação de realocação.
Formato: projects/_/buckets/bucket-name/operations/operation-id
response A resposta da operação.
response.@type O tipo de resposta.
selfLink Um link para essa operação.

Você pode encontrar problemas devido às limitações ao interagir com outros recursos do Cloud Storage. Para mais informações sobre as limitações, consulte Limitações.

Iniciar a etapa final de sincronização

A etapa final de sincronização envolve um período em que não é possível realizar operações de gravação no bucket. Recomendamos que você programe a etapa de sincronização final em um momento que minimize a interrupção dos seus aplicativos.

Antes de continuar, confirme se o bucket está totalmente preparado verificando o valor finalizationState na saída da etapa monitorar o processo de cópia de dados incrementais. O valor finalizationState precisa ser READY para prosseguir com a etapa final de sincronização.

Se você iniciar a etapa final de sincronização prematuramente, o comando vai retornar uma mensagem de erro The relocate bucket operation is not ready to advance to finalization running state, mas o processo de realocação vai continuar.

Recomendamos que você aguarde até que o valor progressPercent seja 99 antes de iniciar a etapa final de sincronização.

Linha de comando

Inicie a etapa final de sincronização da operação de realocação de bucket quando o valor de finalizationState for READY:

gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Em que:

  • BUCKET_NAME é o nome do bucket que você quer realocar.
  • OPERATION_ID é o ID da operação de longa duração, que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar gcloud storage operations list e o ID da operação de longa duração é AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.
 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`

Defina a flag ttl para ter mais controle sobre o processo de realocação. Exemplo:

gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Em que:

TTL_DURATION é o tempo de vida útil (TTL) para a fase de inatividade de gravação durante um processo de realocação. Ele é expresso como uma string, como 12h para 12 horas. O TTL_DURATION determina a duração máxima permitida para a fase de inatividade de gravação. Se o tempo de inatividade de gravação exceder esse limite, o processo de realocação vai reverter automaticamente para a etapa de cópia incremental, e as operações de gravação no bucket serão reativadas. O valor precisa estar entre 6h (6 horas) e 48h (48 horas). Se não for especificado, o valor padrão será 12h (12 horas).

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um arquivo JSON com as configurações de realocação do bucket. Consulte a documentação Buckets: advanceRelocateBucket para conferir uma lista completa de configurações. Veja a seguir configurações comuns a serem incluídas:

    {
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
}

    Em que:

    • EXPIRE_TIME é o tempo de expiração do período de inatividade de gravação.
    • TTL_DURATION é o tempo de vida útil (TTL) para a fase de inatividade de gravação durante um processo de realocação. Ele é expresso como uma string, como 12h para 12 horas. O TTL_DURATION determina a duração máxima permitida para a fase de inatividade de gravação. Se o tempo de inatividade de gravação exceder esse limite, o processo de realocação vai reverter automaticamente para a etapa de cópia incremental, e as operações de gravação no bucket serão reativadas. O valor precisa estar entre 6h (6 horas) e 48h (48 horas). Se não for especificado, o valor padrão será 12h (12 horas).

  3. Use cURL para chamar a API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/bucket/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo JSON criado.
    • BUCKET_NAME é o nome do bucket que você quer realocar.
    • OPERATION_ID é o ID da operação de longa duração, que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar Operations: list e o ID da operação de longa duração é AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.

Validar o processo de realocação do bucket

Após iniciar uma realocação, verifique se ela foi concluída. Esta seção oferece orientações sobre como confirmar a transferência de dados.

Valide o sucesso do processo de realocação usando os seguintes métodos:

  • Pesquisar operações de longa duração: a mudança de bucket é uma operação de longa duração. É possível consultar a operação de longa duração usando o operation id para monitorar o progresso da operação e confirmar a conclusão dela verificando o estado success. Isso envolve consultar periodicamente o status da operação até que ela atinja um estado terminal. Para informações sobre como monitorar operações de longa duração, consulte Usar operações de longa duração no Cloud Storage.

  • Analisar as entradas dos Registros de auditoria do Cloud: os Registros de auditoria do Cloud fornecem um registro detalhado de eventos e operações no seu Google Cloud ambiente. É possível analisar as entradas dos Registros de auditoria do Cloud associadas à mudança de local para validar o sucesso dela. Analise os registros para encontrar erros, avisos ou comportamentos inesperados que possam indicar problemas durante a transferência. Para mais informações sobre como visualizar os registros de auditoria do Cloud, consulte Como visualizar registros de auditoria.

    As entradas de registro a seguir ajudam a determinar se a mudança foi bem-sucedida ou não:

    • Relocalização concluída: Relocate bucket succeeded. All existing objects are now in the new placement configuration.

    • Falha na mudança de local: Relocate bucket has failed. Bucket location remains unchanged.

    Usando as notificações do Pub/Sub, você também pode configurar alertas que notificam quando o evento de sucesso ou falha específico aparece nos registros. Para informações sobre como configurar notificações do Pub/Sub, consulte Configurar notificações do Pub/Sub para o Cloud Storage.

Concluir as tarefas de realocação de bucket pós-mudança

Depois de realocar o bucket, siga estas etapas:

  1. Opcional: restaure os controles de acesso com base em tags no bucket.
  2. As configurações do relatório de inventário atuais não são preservadas durante o processo de realocação e precisam ser recriadas manualmente. Para saber como criar uma configuração de relatório de inventário, consulte Criar uma configuração de relatório de inventário.
  3. Atualize as configurações de infraestrutura como código, como o Terraform e o conector de configuração do Google Kubernetes Engine, para especificar o novo local do bucket.
  4. Os endpoints regionais estão vinculados a locais específicos, e você vai precisar modificar o código do aplicativo para refletir o novo endpoint.

Como lidar com operações de realocação de bucket com falha

Considere os seguintes fatores antes de processar operações de realocação de baldes com falha:

  • Uma realocação de bucket com falha pode deixar recursos obsoletos, como arquivos temporários ou cópias de dados incompletas, no destino. É necessário esperar de 7 a 14 dias antes de iniciar outra relocalização de bucket para o mesmo destino. É possível iniciar uma realocação de bucket para um destino diferente imediatamente.

  • Se o local de destino não for o ideal para seus dados, restaure a mudança de local. No entanto, não é possível iniciar uma relocalização imediatamente. É necessário aguardar um período de até 14 dias antes de iniciar o processo de realocação novamente. Essa restrição está em vigor para garantir a estabilidade e evitar conflitos de dados.

A seguir