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.

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.

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 Pub/Sub para receber notificações de mudanças no bucket de origem e o Serviço de transferência do Cloud Storage para replicar objetos do bucket de origem para o de destino. Para usar a replicação entre buckets, também é necessário conceder as permissões necessárias ao agente de serviço usado pelo Serviço de transferência do Cloud Storage para replicar dados e ao agente de serviço usado pelo Pub/Sub para gravar notificações.

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

O Serviço de transferência do Cloud Storage usa um agente de serviço gerenciado pelo Google para replicar dados. O endereço de e-mail desse agente de serviço segue o formato de nomenclatura 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.

O agente de serviço do Serviço de transferência do Cloud Storage 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

  • storage.buckets.get nos buckets de origem e de destino
  • storage.buckets.update no bucket de origem
  • storage.objects.list no bucket de origem
  • storage.objects.get no bucket de origem
  • storage.objects.rewrite no bucket de destino
  • pubsub.topics.create no projeto

Essas permissões podem ser concedidas pelo papel de editor do Pub/Sub (roles/pubsub.editor) e pelo papel de administrador do Storage (roles/storage.admin). Para uma função menos permissiva do que a de administrador do Storage, você também pode usar uma função personalizada.

Conceder os papéis necessários ao agente de serviço do Cloud Storage

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 Google Cloud instruções do console 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 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 Google Cloud instruções do console 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 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 Google Cloud instruções do console sobre como visualizar um job de replicação, 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 Google Cloud instruções do console sobre como atualizar um job de replicação, consulte Atualizar um job de replicação usando o Google Cloud console.

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 Google Cloud instruções do console 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:

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: