Usar a replicação entre buckets

Esta página fornece uma visão geral da replicação entre buckets e instruções sobre como usar o recurso.

Visão geral da replicação entre buckets

Em alguns casos, talvez você queira copiar dados de um bucket do Cloud Storage para outro. A replicação entre buckets copia objetos novos e atualizados de forma assíncrona de um bucket de origem para um bucket de destino.

A replicação entre buckets é diferente da replicação padrão e turbo porque os dados existem em dois buckets, cada um com suas configurações, como local de armazenamento, criptografia, acesso e classe de armazenamento. Como resultado, ele oferece recuperação e disponibilidade de dados, mas também é adequado para:

  • Soberania de dados: mantenha dados em regiões geograficamente distantes.
  • Manter versões de desenvolvimento e produção separadas: crie buckets e namespaces distintos para que o desenvolvimento não afete a carga de trabalho de produção.
  • Compartilhar dados: replicar dados para um bucket de um fornecedor ou parceiro.
  • Agregação de dados: combinar dados dos buckets diferentes em um único bucket para executar cargas de trabalho de análise.
  • Gerenciar custos, segurança e conformidade: manter os dados em diferentes propriedades, classes de armazenamento e períodos de retenção.

A replicação entre buckets usa o Serviço de transferência do Cloud Storage para replicar objetos e o Pub/Sub para receber alertas sobre mudanças nos buckets de origem e destino. A replicação entre buckets pode ser ativada em novos buckets criados e em buckets existentes. A maioria dos objetos pode ser replicada em minutos, enquanto objetos maiores que um GiB podem levar várias horas.

Limitações

  • Não há suporte para a replicação entre buckets de namespace hierárquico.

Antes de começar

Antes de começar, conclua as etapas a seguir.

Ativar a API Storage Transfer Service

Ative a API Storage Transfer Service, se ainda não tiver feito isso.

Acessar os papéis necessários

Para receber as permissões necessárias para usar a replicação entre buckets, peça ao administrador para conceder a você o papel do IAM de Usuário de transferência do Storage (roles/storagetransfer.user) no bucket ou no projeto de origem.

Esse papel predefinido contém as permissões necessárias para usar a replicação entre 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 usar a replicação entre buckets:

  • storagetransfer.jobs.create
  • storagetransfer.jobs.delete
  • storagetransfer.jobs.get
  • storagetransfer.jobs.list
  • storagetransfer.jobs.run
  • storagetransfer.jobs.update

Para instruções sobre como conceder papéis nos buckets, consulte Usar o IAM com buckets. Para instruções sobre como conceder papéis a projetos, consulte Gerenciar o acesso aos projetos.

Conceder os papéis necessários

A replicação entre buckets usa o Serviço de transferência do Cloud Storage para replicar objetos do bucket de origem para o de destino e o Pub/Sub para receber notificações de mudanças no bucket de origem.

Para que a replicação entre buckets possa usar esses serviços, é necessário conceder as permissões necessárias à conta de serviço usada pelo Serviço de transferência do Cloud Storage para replicar dados, bem como ao agente de serviço usado pelo Pub/Sub para gravar notificações.

Conceder os papéis necessários para o Serviço de transferência do Cloud Storage

As permissões necessárias para replicar dados usando o Storage Transfer Service podem ser concedidas a uma destas contas de serviço:

  • O agente de serviço do Serviço de transferência do Cloud Storage, que é criado e gerenciado automaticamente pelo Google. O endereço de e-mail desse agente de serviço segue o formato de nomeação project-PROJECT_NUMBER@storage-transfer-service. É possível acessar o endereço de e-mail do agente de serviço do Serviço de transferência do Cloud Storage usando a API googleServiceAccounts.get do Serviço de transferência do Cloud Storage.

  • Uma conta de serviço gerenciada pelo usuário. O endereço de e-mail dessa conta de serviço segue o formato de nomenclatura SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com. Você pode criar sua própria conta de serviço e conceder as permissões necessárias para replicar os dados.

O agente de serviço do Serviço de transferência do Cloud Storage ou a conta de serviço do usuário precisa das seguintes permissões para replicar seus objetos e configurar notificações do Pub/Sub para o bucket de origem:

Permissões necessárias

As seguintes permissões precisam ser concedidas no projeto de origem:

  • pubsub.topics.create
  • pubsub.subscriptions.create
  • pubsub.subscriptions.consume
  • iam.serviceAccounts.actAs se você estiver usando uma conta de serviço gerenciada pelo usuário. Não é necessário para o agente de serviço do Serviço de transferência do Cloud Storage.

As seguintes permissões precisam ser concedidas no bucket de origem:

  • storage.buckets.get
  • storage.buckets.update
  • storage.objects.get

As seguintes permissões precisam ser concedidas no bucket de destino:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.get

Essas permissões podem ser concedidas com funções personalizadas ou concedendo todos os seguintes papéis predefinidos:

  • Função de editor do Pub/Sub (roles/pubsub.editor) no projeto de origem
  • Papéis de proprietário de bucket legado do Storage (roles/storage.legacyBucketOwner) e leitor de objetos do Storage (roles/storage.objectViewer) no bucket de origem
  • Papéis de leitor de objetos do Storage (roles/storage.objectViewer) e de gravador de bucket legado do Storage (roles/storage.legacyBucketWriter) no bucket de destino
  • Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) no projeto de origem, se você estiver usando uma conta de serviço gerenciada pelo usuário. Não é necessário para o agente de serviço do Serviço de transferência do Storage.

Conceder os papéis necessários para o Pub/Sub

O Cloud Storage usa um agente de serviço gerenciado pelo Google para gerenciar notificações do Pub/Sub. O endereço de e-mail desse agente de serviço segue o formato de nomenclatura service-PROJECT_NUMBER@gs-project-accounts..

O agente de serviço do Cloud Storage precisa das seguintes permissões para configurar o Pub/Sub e publicar mensagens em um tópico:

Permissões necessárias

  • pubsub.topics.publish no tópico do Pub/Sub
  • pubsub.subscriptions.consume no tópico do Pub/Sub
  • pubsub.subscriptions.create no projeto

Essa permissão pode ser concedida pelo papel de editor do Pub/Sub (roles/pubsub.publisher).

Criar um job de replicação

Console

Para ver instruções sobre como criar um job de replicação no console do Google Cloud, consulte Criar um job de replicação usando o console do Google Cloud.

Linha de comando

Ao usar a CLI do Google Cloud, é possível criar um job de replicação para buckets existentes.

Para criar um job de replicação, use o comando gcloud alpha transfer jobs create com a flag --replication:

gcloud alpha transfer jobs create gs://SOURCE_BUCKET_NAME gs://DESTINATION_BUCKET_NAME --replication

Substitua:

  • SOURCE_BUCKET_NAME pelo nome do bucket de origem que você quer replicar. Por exemplo, my-source-bucket.

  • DESTINATION_BUCKET_NAME pelo nome do bucket de destino. Por exemplo, my-destination-bucket.

APIs REST

API JSON

Ao usar a API JSON, é possível criar um job de replicação para buckets existentes.

  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 que contenha um objeto TransferJob com um recurso ReplicationSpec inicializado:

    TransferJob {
 "name": "TRANSFER_JOB_NAME",
 ...
 ReplicationSpec: {
   "gcsDataSource": {
     "bucketName": "SOURCE_BUCKET_NAME"
   },
   "gcsDataSink" {
     "bucketName": "DESTINATION_BUCKET_NAME"
   },
   "objectConditions": {
   },
   "transferOptions": {
     "overwriteWhen": "OVERWRITE_OPTION"
   }
 }
 ...
}

    Substitua:

    • TRANSFER_JOB_NAME pelo nome que você quer atribuir ao job de replicação. Consulte a documentação de referência de transferJobs para saber mais sobre os requisitos de nomenclatura.

    • SOURCE_BUCKET_NAME com o nome do bucket de origem que contém os objetos que você quer replicar. Por exemplo, example-source-bucket.

    • DESTINATION_BUCKET_NAME com o nome do bucket de destino em que os objetos serão replicados. Por exemplo, example-destination-bucket.

    • OVERWRITE_OPTION com uma opção de como os objetos existentes no bucket de destino podem ser substituídos como resultado de um job de replicação, o que pode acontecer quando o objeto de destino e o de origem têm o mesmo nome. O valor precisa ser um dos indicados abaixo:

      • ALWAYS: sempre substituir objetos no bucket de destino

      • DIFFERENT: só substituir objetos no bucket de destino se os dados do objeto de destino forem diferentes dos dados do objeto de origem

      • NEVER: nunca substituir objetos no bucket de destino

  3. Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.create:

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

    Em que:

    • JSON_FILE_NAME é o nome do arquivo JSON criado na Etapa 2.

Para verificar o status do job de replicação, consulte os registros do Cloud Logging para o Serviço de transferência do Cloud Storage.

Listar jobs de replicação

Console

Para instruções sobre como listar jobs de replicação no console do Google Cloud, consulte Listar jobs de replicação usando o console do Google Cloud.

Linha de comando

Use o comando gcloud alpha transfer jobs list com a flag --job-type:

gcloud alpha transfer jobs list --job-type=replication

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. Use o cURL para chamar a API REST do serviço de transferência do Storage com uma solicitação transferJobs.list:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs"

Visualizar um job de replicação

Console

Para conferir instruções sobre como visualizar um job de replicação no console do Google Cloud, consulte Visualizar um job de replicação usando o console do Google Cloud.

Linha de comando

Use o comando gcloud alpha transfer jobs describe:

gcloud alpha transfer jobs describe JOB_NAME

Substitua:

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. Use cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.get:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"

    Substitua:

Atualizar um job de replicação

É possível atualizar os seguintes campos de um job de replicação:

  • A descrição do job de replicação

  • A configuração para executar um job de replicação

  • A configuração de notificações publicadas no Pub/Sub

  • O comportamento de geração de registros para operações de jobs de replicação

  • O status do job de replicação (ativado, desativado ou excluído)

Console

Para instruções sobre como atualizar um job de replicação no console do Google Cloud, consulte Atualizar um job de replicação usando o console do Google Cloud.

Linha de comando

Use o comando gcloud alpha transfer jobs update com as flags que controlam as propriedades do job de replicação que você quer atualizar. Para uma lista de flags possíveis, consulte a documentação gcloud alpha transfer jobs update.

Por exemplo, para atualizar o comportamento de substituição de objeto do job de replicação, execute o comando gcloud alpha transfer jobs update com a flag --overwrite-when:

gcloud alpha transfer jobs update JOB_NAME --overwrite-when=OVERWRITE_OPTION

Substitua:

  • JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de transferência, listar ou visualizar o job de transferência.

  • OVERWRITE_OPTION com uma opção para definir como os objetos existentes no bucket de destino podem ser substituídos como resultado de um job de replicação, o que pode acontecer quando o objeto de destino e o de origem têm o mesmo nome. O valor precisa ser um dos indicados abaixo:

    • always: sempre substitui os objetos de destino.

    • different: só substitua objetos no bucket de destino se os dados do objeto de destino forem diferentes dos dados do objeto de origem.

    • never: nunca substitua objetos de destino.

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 que contenha a estrutura a seguir, que inclui os campos do objeto TransferJob que você quer atualizar:

    {
 "projectId": string,
 "transferJob": {
   object (TransferJob)
 },
   "updateTransferJobFieldMask": UPDATE_MASK
}

    Em que:

    • object (TransferJob) é substituído pelos campos do job de replicação que você quer atualizar. Consulte a representação de recursos TransferJob para mais informações.

    • UPDATE_MASK é uma lista separada por vírgulas dos nomes dos campos que você quer atualizar. Os valores podem ser um ou mais dos seguintes: description, transferSpec, notificationConfig, loggingConfig, status.

    Para mais informações sobre os nomes de campos que podem ser incluídos, consulte o corpo da solicitação transferJobs.patch.

  3. Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.patch:

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"

    Substitua:

Excluir um job de replicação

Console

Para instruções sobre como excluir um job de replicação no console do Google Cloud, consulte Excluir um job de replicação usando o console do Google Cloud.

Linha de comando

Use o comando gcloud alpha transfer jobs delete:

gcloud alpha transfer jobs delete JOB_NAME

Substitua:

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. Use o cURL para chamar a API REST do serviço de transferência do Storage com uma solicitação transferJobs.delete:

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"

    Substitua: