Usar a replicação entre buckets

Nesta página, você encontra 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 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

  • A replicação entre buckets não é compatível com 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, conceda 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 Serviço de transferência do Cloud Storage podem ser concedidas a uma das duas 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 nomenclatura project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com. É 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 gerenciado 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 gerenciado 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 por papéis personalizados ou por todos os papéis predefinidos a seguir:

  • Papel 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 Gravador de bucket legado do Storage (roles/storage.legacyBucketWriter) e Leitor de objetos do Storage (roles/storage.objectViewer) 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 gerenciado pelo usuário. Não é necessário para o agente de serviço do Serviço de transferência do Cloud 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.iam.gserviceaccount.com.

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 instruções do console do Google Cloud sobre como criar um job de replicação, 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 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 do console do Google Cloud sobre como listar jobs de replicação, 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 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.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 instruções do console do Google Cloud sobre como conferir um job de replicação, consulte Conferir 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:

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

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. 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 do console do Google Cloud sobre como atualizar um job de replicação, 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 trabalho 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 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 do console do Google Cloud sobre como excluir um job de replicação, 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:

  • JOB_NAME com o ID exclusivo do trabalho de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de replicação, listar seus jobs de replicação.

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. Use cURL para chamar a API REST do Serviço de transferência do Cloud 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: