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:
Verifique as cotas e os limites para confirmar se o novo local tem cotas suficientes para acomodar os dados do bucket.
Determine o tipo de realocação do bucket para entender se é necessário um tempo de inatividade de gravação.
Se você usa relatórios de inventário, salve suas configurações.
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 acessar 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 realocação de bucket 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 realocação de 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.
Para realocar um bucket, siga estas etapas:
Para mais informações sobre essas etapas, consulte Entender o processo de realocação de buckets.
Teste a realocação do bucket com uma simulação (opcional)
Para minimizar possíveis problemas durante o processo de realocação do bucket, recomendamos que você faça uma simulação para testar o processo de ponta a ponta. 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:
- Chaves de criptografia gerenciadas pelo cliente (CMEK) ou chaves de criptografia fornecidas pelo cliente (CSEK)
- Políticas de retenção bloqueadas
- Objetos com retenções temporárias
- Uploads de várias partes
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 a disponibilidade de recursos em tempo real, ele reduz o risco de enfrentar problemas demorados durante a realocação.
Console
- No console do Google Cloud , acesse a página Buckets do Cloud Storage.
- Na lista de buckets, clique no nome do bucket que você quer realocar.
- Na página Detalhes do bucket, clique na guia Configuração.
- Na seção Visão geral, clique em Editar ao lado do campo Localização.
- Na página Realocar bucket, insira o novo local do bucket. Após cada uma das etapas a seguir, clique em Continuar para prosseguir para a próxima etapa:
- Na seção Confirme o bucket que você planeja realocar, revise o bucket e o local dele.
- Na seção Antes de continuar, revise as configurações que bloqueiam a mudança. Se uma restrição se aplicar ao seu bucket, considere o Serviço de transferência do Cloud Storage como uma solução alternativa.
-
Na seção Escolha onde realocar seu bucket, faça o seguinte:
- Selecione um tipo de local.
-
Selecione um local onde os dados de objetos no bucket serão armazenados.
Com base nos locais de origem e destino, você vai saber se é necessário um tempo de inatividade de gravação. Para informações sobre os tipos de realocação e tempo de inatividade, consulte Tipos de realocação.
- Na seção Escolha como você quer continuar, clique em Comece com uma simulação (recomendado). Uma simulação simula a realocação para identificar possíveis problemas sem mover dados.
- Clique em Continuar.
- Clique em Iniciar.
- Na caixa de diálogo de confirmação Começar com uma simulação, revise a mensagem que aparece e clique em Iniciar simulação.
Depois de iniciar uma simulação, uma operação de longa duração é iniciada. É possível monitorar o progresso na guia Operações da página detalhes do bucket.
Linha de comando
Para iniciar uma simulação, execute o comando gcloud storage buckets relocate com a flag --dry-run:
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 da simulação acessando os detalhes da operação de longa duração.
Se a simulação revelar algum problema, resolva-o antes de prosseguir com a etapa de realocação.
API JSON
Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho
Authorization.Crie um arquivo JSON com as configurações do bucket, que precisa incluir os parâmetros
destinationLocationevalidateOnly. Consulte a documentaçãoBuckets: relocatepara 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 comotruepara realizar uma simulação.
Use
cURLpara 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_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
operationsretorna um valor de campodonedetrue.{ "kind": "storage#operation", "name": "projects/_/buckets/bucket/operations/operation_id", "metadata": { "@type": OperationMetadataType*, metadata OperationMetadata* }, "done": "true", "response": { "@type": ResponseResourceType*, response ResponseResource* } }Se a simulação revelar algum problema, resolva-o antes de prosseguir com a etapa Iniciar a realocação.
Iniciar a realocação do bucket
Console
- No console do Google Cloud , acesse a página Buckets do Cloud Storage.
- Na lista de buckets, clique no nome do bucket que você quer realocar.
- Na página Detalhes do bucket, clique na guia Configuração.
- Na seção Visão geral, clique em Editar ao lado do campo Localização.
- Na página Realocar bucket, insira o novo local do bucket. Após cada uma das etapas a seguir, clique em Continuar para prosseguir para a próxima etapa:
- Na seção Confirme o bucket que você planeja realocar, revise o bucket e o local dele.
- Na seção Antes de continuar, revise as configurações que bloqueiam a mudança. Se uma restrição se aplicar ao seu bucket, considere o Serviço de transferência do Cloud Storage como uma solução alternativa.
-
Na seção Escolha onde realocar seu bucket, faça o seguinte:
- Selecione um tipo de local.
-
Selecione um local onde os dados de objetos no bucket serão armazenados.
Com base nos locais de origem e destino, você vai saber se é necessário um tempo de inatividade de gravação. Para informações sobre os tipos de realocação e tempo de inatividade, consulte Tipos de realocação.
- Na seção Escolha como você quer continuar, clique em Mudar agora.
- Clique em Continuar.
- Para iniciar o processo de mudança, clique em Iniciar.
- Na caixa de diálogo de confirmação Realocar agora, revise a mensagem que aparece e clique em Iniciar realocação.
Depois de iniciar o processo de realocação, uma operação de longa duração será iniciada. É possível monitorar o progresso na guia Operações da página detalhes do bucket.
Linha de comando
Para iniciar a mudança de local do bucket, execute o comando gcloud storage buckets relocate:
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.
API JSON
Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho
Authorization.Crie um arquivo JSON com as configurações do bucket. Consulte a documentação
Buckets: relocatepara 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 comofalsepara iniciar a realocação do bucket.
Use
cURLpara 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_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 o processo de mudança
Console
Para monitorar o progresso do teste ou do processo de realocação, siga estas etapas:
- No console do Google Cloud , acesse a página Buckets do Cloud Storage.
Na lista de buckets, clique no nome do bucket que você está realocando.
Na página Detalhes do bucket, clique na guia Operações.
Na lista de operações de bucket que aparece, clique na simulação ou na operação de realocação para conferir os detalhes.
A página de detalhes da operação mostra o resumo da mudança, as principais métricas e um resumo de erros.
Linha de comando
Depois de iniciar uma realocação de bucket, 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 processo de realocação acessando os detalhes da operação de longa duração.
API JSON
A mudança de local do bucket é uma operação de longa duração que requer monitoramento. Para verificar o status do processo, revise regularmente os detalhes da operação de longa duração. Para informações sobre como verificar o status do processo de mudança, consulte Receber detalhes de uma operação de longa duração.
O exemplo a seguir mostra a saída gerada por uma operação de realocação:
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 realocação:
| 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 de 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. |
|
metadata.progress |
Detalhes do progresso da operação de realocação. | |
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 para 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. |
|
metadata.sourceLocation |
O local de origem do bucket. | |
metadata.validateOnly |
Indica se uma simulação da realocação do bucket foi iniciada. | true, false |
metadata.estimatedWriteDowntimeDuration |
A duração estimada do tempo de inatividade na gravação, preenchida quando finalizationState é READY. |
O valor mínimo é 7200s. |
metadata.writeDowntimeExpireTime |
O tempo em que o tempo de inatividade na 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
Para realocações que exigem um período de inatividade na gravação, inicie a 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 aplicativos.
Console
Para iniciar a etapa final de sincronização, siga estas etapas:
- No console do Google Cloud , acesse a página Buckets do Cloud Storage.
Na lista de buckets, clique no nome do bucket que você está realocando.
Na página Detalhes do bucket, clique na guia Operações.
Na lista de operações do bucket, clique na operação de realocação para ver a página de detalhes dela. Na página de detalhes da operação, quando a cópia de dados estiver pelo menos 99% concluída, uma barra de mensagens vai aparecer indicando que é o momento ideal para iniciar a sincronização final.
Opcional: para definir o tempo máximo de inatividade na gravação permitido, clique em Definir o tempo máximo de inatividade permitido (TTL) e especifique a duração máxima de inatividade.
Clique em Iniciar sincronização final.
Na caixa de diálogo de confirmação, clique em Iniciar para começar a sincronização final.
A página de detalhes da operação mostra o resumo da mudança, as principais métricas e um resumo de erros.
Linha de comando
Antes de continuar, confirme se o bucket está totalmente preparado verificando o valor finalizationState na saída da etapa Iniciar a realocação do bucket.
Quando o valor de finalizationState for READY, execute o comando gcloud storage buckets
relocate para iniciar a sincronização final:
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 de realocação do bucket, que é retornado na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamargcloud storage operations liste 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 na 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 realocação do bucket, 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).
API JSON
Antes de continuar, confirme se o bucket está totalmente preparado verificando o valor finalizationState na saída da etapa realocação de bucket. O valor de finalizationState precisa ser READY para continuar.
Se você iniciar a etapa de sincronização final 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.
Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho
Authorization.Crie um arquivo JSON que contenha as configurações para a realocação do bucket. Consulte a documentação
Buckets: advanceRelocateBucketpara 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 o tempo de inatividade na 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, como12hpara 12 horas. OTTL_DURATIONdetermina a duração máxima permitida para a fase de inatividade na 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 realocação do bucket, e as operações de gravação no bucket serão reativadas. O valor precisa estar no intervalo de6h(6 horas) a48h(48 horas). Se não for especificado, o valor padrão será12h(12 horas).
Use
cURLpara 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 iniciou a realocação do bucket. Para conferir a lista de IDs de operação de longa duração de um bucket, consulte Operações: list.
Depois que um bucket é realocado com sucesso, não é possível iniciar outra realocação para o mesmo bucket por um período de 14 dias.
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 idpara monitorar o progresso dela e confirmar a conclusão bem-sucedida verificando o estadosuccess. 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 do bucket
Depois de realocar o bucket, siga estas etapas:
- Opcional: restaure os controles de acesso baseados em tags no bucket.
- As configurações atuais do relatório de inventário não são preservadas durante o processo de realocação, 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.
- Atualize as configurações de infraestrutura como código, como Terraform e conector de configuração do Google Kubernetes Engine, para especificar o novo local do bucket.
- 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 lidar com 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. É necessário aguardar 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 um período de espera de até 14 dias antes de iniciar o processo de realocação novamente para manter a estabilidade e evitar conflitos de dados.
A seguir
- Saiba mais sobre a realocação de buckets.