Como gerenciar jobs de transferência local

Antes de iniciar uma transferência, você precisa criar um job de transferência e ter um ou mais agentes instalados e conectados a ele. Neste documento, descrevemos a configuração inicial, como criar e gerenciar seus jobs de transferência e como instalar agentes de transferência.

Pré-requisitos

Para usar a transferência local, você precisa de:

  • Uma origem compatível com POSIX

  • Conexão de rede de 300 Mbps ou mais rápida

  • Um servidor Linux ou máquina virtual de 64 bits compatível com o Docker (em inglês) capaz de acessar os dados que você quer transferir.

    O Docker Community Edition (links em inglês) é compatível com sistemas operacionais CentOs, Debian, Fedora e Ubuntu.

    Para usar outros sistemas operacionais Linux, consulte Docker Enterprise (links em inglês).

  • Conclua a Configuração inicial para transferência local.

Antes de iniciar uma transferência, verifique se:

  • As portas TCP 80 (HTTP) e 443 (HTTPS) estão abertas para conexões de saída.
  • Todos os processos de agente em um único projeto do Google Cloud têm o mesmo sistema de arquivos ativado no mesmo ponto de montagem.

Restrições de escalonamento em jobs e agentes

A transferência local tem as seguintes restrições de escala em jobs e agentes de transferência:

  • Menos de um bilhão de arquivos por job
  • 100 agentes ou menos por projeto de transferência
  • O limite de largura de banda precisa ser maior que 1 MBps

Configuração inicial

Na primeira vez que você criar um job do Serviço de transferência de dados locais, será preciso ativar as APIs necessárias e garantir as permissões corretas.

Se você receber erros ao realizar a configuração inicial, confirme se o usuário que fez login tem permissão para executar as etapas de configuração. Em muitos casos, essas permissões não estão disponíveis para todos os usuários, e talvez seja necessário entrar em contato com um administrador do projeto para receber ajuda.

Para fazer a configuração inicial:

  1. Ative a API Pub/Sub

    1. Acesse a página Biblioteca de APIs no Console do Google Cloud.

    Acesse a página "Biblioteca de APIs"

    1. Na caixa de pesquisa, digite Pub/Sub API.

    2. Selecione API Pub/Sub

      A página da API Pub/Sub é exibida.

    3. Clique em Ativar.

      A visão geral da API Pub/Sub é exibida.

  2. Use o administrador de projetos do Google Cloud, um usuário com privilégios resourcemanager.projects.setIamPolicy, para conceder permissões ou papéis do gerenciamento de identidade e acesso a:
    • contas de administrador (admin) de transferência local: contas de superusuário compatíveis com colegas que realizam transferências. Os administradores gerenciam agentes de transferência local e definem limites de uso da largura de banda.
    • contas de usuário de transferência local: contas usadas para criar e executar transferências. Essas contas normalmente não têm acesso para excluir jobs de transferência.
    • conta de serviço de transferência local: a conta de serviço usada para realizar transferências locais.
    • identidade do agente de transferência local: a identidade usada para executar a transferência do agente local. Pode ser uma conta de serviço ou uma conta de usuário que configura os agentes locais.

    A conta de administrador do projeto do Google Cloud serve apenas para configurar usuários de transferência e conceder as permissões necessárias para a conta de serviço de transferência local. Não é necessário iniciar jobs de transferência.

    Para mais informações sobre como conceder permissões de gerenciamento de identidade e acesso, consulte Como conceder, alterar e revogar acesso a recursos.

    1. Para configurar uma conta de administrador de transferência local, atribua as seguintes permissões e papéis do IAM à conta:
      Papel / permissão Efeitos Observações
      resourcemanager.projects.getIamPolicy Usada para confirmar que a conta de serviço de transferência local tem as permissões necessárias para realizar uma transferência.
      roles/storagetransfer.admin Permite ações administrativas no projeto de transferência, como configuração do projeto e monitoramento do agente. Para ver uma lista detalhada das permissões concedidas, consulte Papéis predefinidos.
    2. Para configurar uma conta de usuário de transferência local, atribua as seguintes permissões e papéis à conta:
      Papel / permissão Efeitos Observações
      resourcemanager.projects.getIamPolicy Usada para confirmar que a conta de serviço de transferência local tem as permissões necessárias do Pub/Sub para realizar uma transferência.
      roles/storagetransfer.user Permite que o usuário crie, receba, atualize e liste transferências. Para ver uma lista detalhada das permissões concedidas, consulte Papéis predefinidos.
      roles/storage.objectAdmin Permite que o usuário crie, atualize e exclua objetos do Cloud Storage como parte de uma transferência. É preciso conceder todos os buckets do Cloud Storage que essa conta usará nas transferências.

      Para ver uma lista detalhada das permissões concedidas, consulte Papéis predefinidos.
    3. Para permitir que a conta de serviço de transferência local acesse os recursos necessários para concluir transferências, atribua os seguintes papéis ou permissões equivalentes a essa conta de serviço cloud-ingest-dcp@cloud-ingest.iam.gserviceaccount.com:
      Papel / permissão Efeitos Observações
      roles/storage.objectCreator Permite que a transferência local crie registros de transferência no bucket do Cloud Storage de destino. Conceda a todos os buckets do Cloud Storage usados em uma transferência. Se for indicado para seu caso, é possível conceder esse papel (no nível do projeto) ao projeto de onde a transferência local é executada.

      Para uma lista detalhada das permissões que esses papéis concedem, consulte Papéis predefinidos.
      roles/storage.objectViewer Permite que a transferência local determine se um arquivo já foi enviado para o Cloud Storage.
      roles/pubsub.editor Permite que a transferência local crie e modifique tópicos do Pub/Sub automaticamente para a comunicação entre o Google Cloud e os agentes locais de transferência. Aplique o papel no nível do projeto em que a transferência local está sendo executada.

      Para ver uma lista detalhada das permissões concedidas por esse papel, consulte Papéis.
      storage.buckets.get Essa permissão permite a leitura dos metadados do bucket do Cloud Storage.
    4. Para configurar uma conta de usuário ou de serviço de agente de transferência local que execute os agentes de transferência local, atribua as seguintes permissões e papéis:
      Papel / permissão Efeitos Observações
      roles/storage.objectAdmin Permite que agentes de transferência local criem, atualizem e excluam objetos do Cloud Storage como parte de uma transferência. Conceda a todos os buckets do Cloud Storage usados em uma transferência. Se for indicado para seu caso, é possível conceder esse papel (no nível do projeto) ao projeto de onde a transferência local é executada.

      Para ver uma lista detalhada de permissões que esse papel concede, consulte Papéis.
      roles/pubsub.publisher Permite que agentes de transferência local compartilhem informações com o Google Cloud usando tópicos do Pub/Sub. Para uma lista detalhada das permissões que este papel concede, consulte Papéis.
      roles/pubsub.subscriber Permite que o Google Cloud compartilhe informações com agentes de transferência local usando tópicos do Pub/Sub. Para uma lista detalhada das permissões que este papel concede, consulte Papéis.
      pubsub.subscriptions.create Essa permissão possibilita que os agentes de transferência local criem assinaturas do Pub/Sub para o tópico do Pub/Sub usado na comunicação entre o Google Cloud e os agentes de transferência local.
      pubsub.subscriptions.delete Essa permissão ativa os agentes de transferência local que normalmente limpam todas as assinaturas do Pub/Sub que eles criam.
  3. Instale e execute agentes locais em cada uma das suas máquinas.

Como criar um job de transferência

Antes de iniciar uma transferência, você precisa criar um job de transferência. O job de transferência coordena e controla os agentes locais à medida que eles transferem os dados.

Para criar um job de transferência:

  1. Acesse a página Console da Web do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página do serviço de transferência de dados locais

  2. Clique em Criar job de transferência.

    Será exibida a página Criar um job de transferência.

  3. Descreva o job de transferência Insira uma breve descrição da transferência que ajudará você a rastreá-la.

  4. Especifique uma origem inserindo o caminho totalmente qualificado do diretório do sistema de arquivos de origem.

  5. Especifique um bucket de destino do Cloud Storage. É possível inserir um nome de bucket do Cloud Storage ou criar um novo bucket.

    Para criar e selecionar um novo bucket:

    1. Clique em Procurar.

    2. Clique em Novo bucket.

      Será exibido o formulário Criar um bucket.

    3. Preencha o formulário, clique em Criar e, depois, em Selecionar.

  6. Opcional: insira o prefixo do objeto. Sem essa informação, os objetos são transferidos para o Cloud Storage com o caminho de origem, sem incluir o caminho raiz, antes do nome do arquivo no sistema. Por exemplo, se você tiver os seguintes arquivos:

    • /source_root_path/file1.txt
    • /source_root_path/dirA/file2.txt
    • /source_root_path/dirA/dirB/file3.txt
    Os nomes de objeto no Cloud Storage serão:
    • file1.txt
    • dirA/file2.txt
    • dirA/dirB/file3.txt
    O prefixo do objeto é adicionado ao nome de destino do objeto no Cloud Storage, depois do caractere / do nome do bucket de destino e antes dos nomes de caminhos de onde o objeto foi transferido, sem incluir o caminho raiz da origem. Isso pode ajudar você a distinguir entre objetos transferidos de outros jobs de transferência.

    A tabela a seguir demonstra vários exemplos de prefixos de objetos e os nomes de objetos resultantes no Cloud Storage, se o caminho do objeto de origem for /source_root_path/sub_folder_name/object_name:
    Prefixo Nome do objeto de destino
    Nenhum /destination_bucket/sub_folder_name/object_name
    prefix /destination_bucket/prefixsub_folder_name/object_name
    prefix- /destination_bucket/prefix-sub_folder_name/object_name
    prefix/ /destination_bucket/prefix/sub_folder_name/object_name

  7. Opcional: crie uma programação para seu job.

  8. Clique em Criar.

Instale e execute agentes de transferência local em cada uma das máquinas, caso ainda não tenha feito isso.

Como controlar o uso da largura de banda para o serviço de transferência de dados locais

Os limites de largura de banda são úteis se você precisa limitar a quantidade de dados que o serviço de transferência de dados locais usa para transferir dados para o Cloud Storage. Usar um limite de largura de banda ajuda a garantir que:

  • seus links de rede não fiquem saturados como resultado do uso do serviço de transferência de dados locais;

  • o comportamento do aplicativo existente da sua organização não seja afetado durante a transferência;

  • não haja um aumento repentino no preço, se você estiver em uma conexão de rede que cobra por pico de uso da largura de banda;

os limites de largura de banda sejam aplicados a um projeto inteiro.

Como definir um limite de largura de banda

Para definir um limite de largura de banda:

  1. Acesse a página Configurações de conexão do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de configurações de conexão do serviço de transferência de dados locais

  2. Clique em Configurar limite de largura de banda.

  3. Será exibido o painel Definir o limite da largura de banda deste projeto.

  4. Na caixa de texto Limite de largura de banda, insira em megabytes por segundo (MB/s) o limite de rede que você quer e clique em Configurar limite de largura de banda

    Será exibido o limite de largura de banda do projeto.

Como editar um limite de largura de banda

Para editar o limite atual de largura de banda:

  1. Acesse a página Configurações de conexão do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de configurações de conexão do serviço de transferência de dados locais

  2. No limite de largura de banda exibido, clique em Editar.

  3. Na caixa de texto Limite de largura de banda, insira em megabytes por segundo (MB/s) o limite de rede que você quer e clique em Configurar limite de largura de banda

    Será exibido o limite de largura de banda do projeto.

Como remover um limite de largura de banda

Para remover o limite atual de largura de banda:

  1. Acesse a página Configurações de conexão do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de configurações de conexão do serviço de transferência de dados locais

  2. No limite de largura de banda exibido, clique em Usar toda a largura de banda.

  3. Para confirmar que você quer remover o limite atual, clique em Confirmar.

Como monitorar jobs

É possível monitorar jobs do serviço de transferência de dados locais para garantir que eles funcionem conforme o esperado.

Para monitorar seus jobs de transferência:

  1. Acesse a página Jobs do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de jobs do serviço de transferência de dados locais

    Será exibida uma lista de jobs. Essa lista inclui jobs em execução e concluídos.

  2. Para exibir informações detalhadas sobre um job de transferência, clique na Descrição do job que lhe interessa.

    Será exibida a página Detalhes do job.

A página Detalhes do job exibe o seguinte:

  • a quantidade de dados transferidos

  • informações de configuração sobre o job de transferência

  • informações de jobs programados ou recorrentes

  • detalhes da execução de job mais recente

  • histórico de todas as execuções de jobs anteriores.

Como filtrar jobs

Se você tiver muitos jobs e quiser monitorar um subconjunto deles, considere usar filtros para classificar e exibir apenas os jobs que lhe interessam.

Para filtrar seus jobs de transferência:

  1. Clique em Filtrar lista .

  2. Selecione os filtros que você quer aplicar.

Como editar configurações de jobs

É possível editar os itens a seguir para um job de transferência existente:

  • a descrição do job
  • Opção de sincronização
  • Programar

Para editar uma configuração de job:

  1. Acesse a página Jobs do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de jobs do serviço de transferência de dados locais

  2. Clique na Descrição do job referente ao job que você está editando.

    Será exibida a página Detalhes do job.

  3. Clique em Configuração.

  4. Clique em ao lado do item de configuração que você quer editar.

Como executar jobs novamente

O serviço de transferência de dados locais permite executar novamente um job concluído uma única vez. Isso pode ser útil se você tiver alguns dados extras para mover e quiser reutilizar uma configuração de job atual.

Para executar um job novamente:

  1. Acesse a página Jobs do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de jobs do serviço de transferência de dados locais

  2. Clique na Descrição do job referente ao job que você está editando.

    Será exibida a página Detalhes do job.

  3. Clique em Executar novamente.

    O job será iniciado.

Como visualizar erros

Para visualizar uma amostra de erros encontrados durante a transferência:

  1. Acesse a página Jobs do serviço de transferência de dados locais no Console do Google Cloud.

    Acesse a página de jobs do serviço de transferência de dados locais

  2. Clique na Descrição do job referente ao job que você está editando.

    Será exibida a página Detalhes do job.

  3. Clique em Ver detalhes do erro.

    Será exibida a página Detalhes do erro com uma amostra de erros encontrados durante a transferência.

Como visualizar registros de transferência

O serviço de transferência de dados locais gera registros de transferência detalhados para verificar os resultados do job de transferência. Cada job gera uma coleção de registros de transferência que é armazenada no bucket de destino do Cloud Storage.

Os registros são gerados enquanto o trabalho de transferência está em execução. Os registros completos geralmente são disponibilizados até 15 minutos depois da conclusão do job.

Estas são as opções para ver os registros:

Como visualizar erros no Console do Google Cloud

Para exibir todos os erros encontrados durante a transferência no Console do Google Cloud:

  1. Clique em Visualizar registros de transferência.

    Será exibida a página Detalhes do bucket. Este é um destino no bucket do Cloud Storage.

  2. Clique no registro de transferência em que você tem interesse.

    Serão exibidos os registros de transferência. Para mais informações, consulte formato de registro de transferência.

Como visualizar registros no bucket de destino

Os registros de transferência são armazenados no bucket de destino no seguinte caminho:

destination-bucket-name/storage-transfer/logs/transferJobs/job-name/transferOperations/operation-name

em que:

  • destination-bucket-name é o nome do bucket de destino do Cloud Storage.
  • job-name é o nome do job, conforme exibido na lista de jobs.
  • operation-name é o nome da operação de transferência individual, composta pelo carimbo de data/hora IS08601 e pelo ID gerado.

Os registros são agregados e armazenados como objetos. Cada lote de registros é nomeado de acordo com a hora de criação. Por exemplo:

my bucket/storage-transfer/logs/transferOperations/job1/2019-10-19T10_52_56.519081644-07_00.log

Serão exibidos os registros de transferência. Para mais informações, consulte formato de registro de transferência.

Como executar consultas do BigQuery em registros de transferência

Para executar consultas do BigQuery nos seus registros de transferência:

  1. Carregue os dados do registro CSV no BigQuery.

  2. Execute sua consulta do BigQuery.

Exemplo de consultas

Exibir o número de tentativas de transferência de arquivos e o status de falha/êxito

select ActionStatus, count(*) as num_files
from big-query-table
where Action="TRANSFER"
group by 1;

Em que big-query-table é o nome da tabela do BigQuery com o registro de transferência.

Exibir todos os arquivos que falharam na transferência

select Src_File_Path  
from big-query-table
where Action="TRANSFER" and ActionStatus="FAILED";

Em que big-query-table é o nome da tabela do BigQuery com o registro de transferência.

Exibir a soma de verificação e o carimbo de data/hora de cada arquivo transferido com êxito

select Timestamp, Action, ActionStatus, Src_File_Path, Src_File_Size,
Src_File_Crc32C, Dst_Gcs_BucketName, Dst_Gcs_ObjectName, Dst_Gcs_Size,
Dst_Gcs_Crc32C, Dst_Gcs_Md5
from big-query-table
where Action="TRANSFER" and ActionStatus="SUCCEEDED";

Em que big-query-table é o nome da tabela do BigQuery com o registro de transferência.

Exibir todas as informações de erro dos diretórios que não foram transferidos

select FailureDetails_ErrorType, FailureDetails_GrpcCode, FailureDetails_Message
from big-query-table
where Action="FIND" and ActionStatus="FAILED";

Em que big-query-table é o nome da tabela do BigQuery com o registro de transferência.