Recolocar buckets

Nesta página, descrevemos o processo de realocação de 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 realocar buckets, siga estas etapas:

  1. Configurar o Storage Intelligence.

  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 de bucket para entender se é necessário um tempo de inatividade de gravação.

  5. Remova todas as tags de bucket atuais.

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

  7. Ter os papéis necessários, que são descritos na seção a seguir.

Acessar os papéis necessários

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

Esse papel predefinido contém as permissões necessárias para realocar buckets. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para realocar buckets:

  • Para realocar um bucket: storage.buckets.relocate
  • Para conferir o status de uma operação de realocação de bucket: storage.bucketOperations.get
  • Para conferir a lista de operações de movimentação de buckets de um projeto: storage.bucketOperations.list
  • Para cancelar uma operação de realocação de bucket: storage.bucketOperations.cancel
  • Para conferir os metadados de um bucket durante as fases de teste a seco e cópia incremental de dados da mudança de local do bucket: storage.buckets.get
  • Para receber um objeto em um bucket que você quer realocar: storage.objects.get
  • Para listar os objetos em um bucket que você quer realocar: storage.objects.list

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

Realocar buckets

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

Executar uma simulação

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

Embora um teste simulado não possa identificar todos os problemas possíveis, já que alguns só aparecem durante a migração ao vivo devido a fatores como disponibilidade de recursos em tempo real, ele reduz o risco de enfrentar problemas demorados durante a realocação.

Linha de comando

Simule a simulação da realocação do 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.

Depois de iniciar uma simulação, uma operação de longa duração é iniciada. Você vai receber um ID e uma descrição da operação. Acompanhe o progresso e a conclusão do teste simulado acessando os detalhes da operação de longa duração.

Se o teste simulado revelar algum problema, resolva-o antes de prosseguir com a Etapa de início da cópia incremental de dados.

APIs REST

API JSON

  1. Ter 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 ver 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 que você criou.
    • BUCKET_NAME é o nome do bucket que você quer realocar.

    Depois de iniciar uma simulação, uma operação de longa duração é iniciada. A simulação será bem-sucedida quando as seguintes condições forem atendidas:

    • A simulação não informa erros.

    • O recurso operations retorna um valor de campo done de true.

      {
"kind": "storage#operation",
"name": "projects/_/buckets/bucket/operations/operation_id",
"metadata": {
  "@type": OperationMetadataType*,
  metadata OperationMetadata*
},
"done": "true",
"response": {
  "@type": ResponseResourceType*,
  response ResponseResource*
}
}

    Se o teste simulado revelar algum problema, resolva-o antes de prosseguir com a Etapa de início da cópia incremental de dados.

Iniciar cópia incremental de dados

Linha de comando

Inicie a operação de realocação de 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 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 ver 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 incremental de dados da mudança de local 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 que você criou.
    • 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 acompanhar o progresso. É possível verificar regularmente a lista de operações de longa duração para conferir o status da etapa de cópia incremental de dados. Para informações sobre como acessar os detalhes de uma operação de longa duração, listar ou cancelar operações de longa duração, 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 incremental:

  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
  estimatedWriteDowntimeDuration: '7200s'
  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 incremental de dados:

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 este recurso representa uma operação de armazenamento.
metadata Fornece informações sobre a operação.
metadata.@type Indica o tipo de operação como realocação 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 terminou.
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 aplicável.
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 a prontidão para iniciar a etapa final de sincronização.
  • 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 de sincronização final.
  • 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ê precisa resolver os erros para continuar com 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 mudança.
metadata.progress.byteProgressPercent Progresso de bytes copiados em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não aplicável.
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 Progresso dos objetos copiados em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não aplicável.
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 sincronizadas.
metadata.progress.syncProgressPercent Progresso das atualizações de metadados de objetos a serem sincronizadas em porcentagem. Entre 0 e 100%. Um valor de -1 significa que o progresso é desconhecido ou não aplicável.
metadata.relocationState Estado geral da operação de realocação do bucket.
  • SYNCING: indica que a etapa de cópia incremental de dados está copiando objetos ativamente do bucket de origem para o bucket de destino.
  • FINALIZING: indica que a etapa de finalização foi iniciada.
  • FAILED: indica que a etapa de cópia incremental de dados encontrou um erro e não foi concluída com êxito.
  • SUCCEEDED: indica que a etapa de cópia incremental de dados foi concluída com êxito.
  • CANCELLED: indica que a etapa de cópia incremental de dados foi cancelada.
metadata.sourceLocation O local de origem do bucket.
metadata.validateOnly Indica se uma simulação da mudança de local do bucket foi iniciada. true, false
metadata.estimatedWriteDowntimeDuration A duração estimada do tempo de inatividade de gravação, preenchida quando finalizationState é READY. O valor mínimo é 7200s.
metadata.writeDowntimeExpireTime O horário em que a inatividade de gravação expira.
name O identificador exclusivo dessa operação de mudança.
Formato: projects/_/buckets/bucket-name/operations/operation-id
response A resposta da operação.
response.@type O tipo da resposta.
selfLink Um link para esta operação.

Se você encontrar problemas ao interagir com outros recursos do Cloud Storage, consulte Limitações.

Iniciar a etapa de sincronização final

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 final de sincronização em um horário 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 cópia incremental de dados. O valor de finalizationState precisa ser READY para continuar.

Se você iniciar a etapa final de sincronização antes da hora, 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 mudança 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 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 é retornado 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 time to live (TTL) da fase de inatividade de gravação durante um processo de realocação. Ela é expressa 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 será revertido automaticamente para a etapa de cópia incremental, e as operações de gravação no bucket serão reativadas. O valor precisa estar no intervalo de 6h (6 horas) a 48h (48 horas). Se não for especificado, o valor padrão será 12h (12 horas).

APIs REST

API JSON

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

  2. Crie um arquivo JSON que contenha as configurações para a realocação do bucket. Consulte a documentação Buckets: advanceRelocateBucket para ver 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 horário em que a inatividade de gravação expira.
    • TTL_DURATION é o time to live (TTL) da fase de inatividade de gravação durante um processo de realocação. Ela é expressa 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 será revertido automaticamente para a etapa de cópia incremental, e as operações de gravação no bucket serão reativadas. O valor precisa estar no intervalo de 6h (6 horas) a 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 que você criou.
    • BUCKET_NAME é o nome do bucket que você quer realocar.
    • OPERATION_ID é o ID da operação de longa duração, que é retornado 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 de buckets

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

Valide o sucesso do processo de mudança usando os seguintes métodos:

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

  • Analise 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 ambiente do Google Cloud . É possível analisar as entradas dos registros de auditoria do Cloud associadas à mudança para validar o sucesso dela. Analise os registros em busca de erros, avisos ou comportamentos inesperados que possam indicar problemas durante a transferência. Para informações sobre como visualizar registros de auditoria do Cloud, consulte Como visualizar registros de auditoria.

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

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

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

    Com as notificações do Pub/Sub, também é possível configurar alertas que avisam quando o evento específico de sucesso ou falha 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 pós-realocação de bucket

Depois de realocar o bucket, siga estas etapas:

  1. Opcional: restaure os controles de acesso baseados em tags no bucket.
  2. As configurações atuais do relatório de inventário não são preservadas durante o processo de mudança, e você precisa recriá-las manualmente. Para informações sobre 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 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ê precisará modificar o código do aplicativo para refletir o novo endpoint.

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

Considere os seguintes fatores antes de processar operações de realocação de bucket 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. Aguarde de 7 a 14 dias antes de iniciar outra realocação de bucket para o mesmo destino. Você pode iniciar uma mudança de local de bucket para um destino diferente imediatamente.

  • Se o local de destino não for o ideal para seus dados, talvez seja necessário reverter a mudança. No entanto, não é possível iniciar uma mudança imediatamente. É necessário aguardar até 14 dias antes de iniciar o processo de realocação novamente. Essa restrição existe para garantir a estabilidade e evitar conflitos de dados.

A seguir