Gerenciar agentes de transferência

Os agentes do Serviço de transferência do Cloud Storage são aplicativos executados em um contêiner do Docker, que são coordenados com o Serviço de transferência do Cloud Storage para transferências envolvendo sistemas de arquivos ou armazenamento compatível com S3.

Se a transferência não envolver um sistema de arquivos ou armazenamento compatível com S3, não será necessário configurar agentes.

As transferências do Amazon S3 não exigem agentes. O armazenamento compatível com S3 se refere a sistemas de armazenamento que usam a API S3, mas não são hospedados diretamente pela Amazon.

Este documento descreve como administrar agentes de transferência nos servidores.

Visão geral

• Os processos do agente são dinâmicos. Enquanto você está executando uma transferência, é possível adicionar agentes para aumentar o desempenho. Agentes recém-iniciados entram no pool de agentes atribuídos e realizam o trabalho de transferências existentes. É possível usar isso para ajustar quantos agentes estão em execução ou adaptar o desempenho para alterar a demanda de transferência.

• Os processos do agente são um coletivo tolerante a falhas. Se um agente parar de ser executado, os demais continuarão trabalhando. Se todos os agentes forem interrompidos, quando você reiniciar, a transferência será retomada de onde o agente parou. Isso permite evitar agentes de monitoramento, tentativas de novas transferências ou implementação da lógica de recuperação. É possível corrigir, mover e escalonar dinamicamente os pools de agentes sem inatividade de transferência ao coordenar agentes com o Google Kubernetes Engine.

  Por exemplo, você envia duas transferências enquanto dois agentes estão em execução. Se um dos agentes for interrompido devido a uma reinicialização da máquina ou a um patch do sistema operacional, o agente restante continuará funcionando. As duas transferências ainda estão em execução, porém, mais lentas, porque um único agente está movendo dados. Se o agente restante também for interrompido, todas as transferências deixarão de progredir, já que não há agentes em execução. Ao reiniciar os processos do agente, as transferências serão retomadas de onde pararam.

• Os processos do agente pertencem a um pool. Coletivamente, eles movem os dados em paralelo. Por isso, todos os agentes em um pool precisam ter o mesmo acesso a todas as fontes de dados que você quer transferir.

  Por exemplo, se você estiver transferindo dados de um sistema de arquivos específico, será necessário ativá-lo para cada máquina que hospeda agentes no conjunto de agentes. Se alguns agentes no seu pool atingirem uma fonte de dados e outros não, as transferências dessa fonte não serão bem-sucedidas.

Antes de começar

Antes de configurar as transferências, verifique se você configurou o acesso: para usuários e contas de serviço.

Para usar comandos gcloud, instale a CLI gcloud.

Instalar e executar agentes de transferência

Importante: os usuários que criam jobs de transferência podem recuperar e fazer o download de dados em qualquer diretório do sistema de arquivos que possa ser acessado pelo agente Se os agentes forem executados como raiz e tiverem acesso a todo o sistema de arquivos, uma pessoa mal-intencionada poderá assumir o controle do host. É altamente recomendável que você restrinja o acesso do agente apenas aos diretórios necessários.

Recomendamos a instalação de pelo menos três agentes por pool de agentes, de preferência em máquinas separadas. Para mais informações sobre como determinar quantos agentes precisam ser executados, consulte Como maximizar o desempenho do agente de transferência.

Não inclua informações sensíveis, como informações de identificação pessoal (PII) ou dados de segurança, no prefixo do ID do agente. Os nomes dos recursos podem ser propagados para os nomes de outros recursos do Google Cloud e podem ser expostos aos sistemas internos do Google fora do seu projeto.

Para instalar e executar agentes de transferência:

12 de abril de 2023: os agentes usados para transferências do armazenamento compatível com S3 precisam ser autenticados com uma chave de conta de serviço. Use a sinalização --creds-file para especificar o caminho para um arquivo de chave da conta de serviço. Deixar de usar uma conta de serviço resulta em transferências paralisadas; o job é exibido como em andamento, mas nenhum dado é transferido.

Este aviso será removido quando o problema for resolvido.

Console do Google Cloud

1. No Console do Google Cloud, acesse a página Pools de agentes.

   Acessar pools de agentes

2. Selecione o pool de agentes a que o novo agente será adicionado.

3. Clique em Instalar agente.

4. Siga as instruções exibidas para instalar e executar o agente.

   Para mais informações sobre as opções de linha de comando do agente, consulte Opções de linha de comando do agente.

CLI da gcloud

Para instalar um ou mais agentes usando a CLI gcloud, execute gcloud transfer agents install:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

A ferramenta mostrará as etapas necessárias para instalar os agentes. Esse comando instala o(s) agente(s) NUM_AGENTS na sua máquina, mapeado para o nome do pool especificado como POOL_NAME e autentica o agente usando as credenciais do gcloud. O nome do pool precisa existir ou um erro é retornado.

A sinalização --mount-directories é opcional, mas altamente recomendada. O valor dela é uma lista de diretórios separados por vírgulas no sistema de arquivos aos quais o agente concede acesso. A omissão dessa sinalização monta todo o sistema de arquivos no contêiner do agente. Consulte a referência gcloud para mais detalhes.

Origens compatíveis com S3

Ao instalar agentes para usar com uma fonte compatível com S3, forneça credenciais da AWS como variáveis de ambiente como os valores de AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY ou armazenadas como credenciais padrão em arquivos de configuração do seu sistema.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Usar uma chave de conta de serviço

Observação: as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura para as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

Para executar agentes usando uma chave de conta de serviço, use a opção --creds-file:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Mais informações

Para ver uma lista completa de sinalizações opcionais, execute gcloud transfer agents install --help ou leia a referência de gcloud transfer.

docker run

Antes de usar o docker run para instalar agentes, siga as instruções para instalar o Docker.

O comando docker run instala um agente. Para aumentar o número de agentes no pool, execute esse comando quantas vezes forem necessárias.

Ao instalar agentes, é possível autenticar usando suas credenciais padrão gcloud ou com uma conta de serviço.

Credenciais padrão

Para permitir que o contêiner do Docker autentique com suas credenciais padrão do gcloud, execute o comando a seguir para criar um volume do Docker contendo um arquivo com suas credenciais padrão do aplicativo.

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

Em seguida, use o comando a seguir para instalar um agente, usando a sinalização --volumes-from para montar o volume de credenciais gcloud-config:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Autenticação da conta de serviço

Para instalar e executar agentes de transferência docker run usando as credenciais da conta de serviço, especifique o caminho para a chave da conta de serviço formatada em JSON usando a sinalização --creds-file.

O caminho precisa ser prefixado com a string, /transfer_root.

Consulte Criar e gerenciar chaves de conta de serviço para mais informações sobre chaves de conta de serviço.

Observação: as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura para as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opções e sinalizadores

Substitua as variáveis nos exemplos acima pelas seguintes informações:

• HOST_DIRECTORY é o diretório na máquina host de onde você pretende copiar. É possível usar mais de uma sinalização -v para especificar diretórios adicionais a serem copiados.
• CONTAINER_DIRECTORY é o diretório mapeado no contêiner do agente. Ele precisa ser igual a HOST_DIRECTORY.
• PROJECT_ID é o ID do projeto que hospeda a transferência.
• POOL_NAME é o nome do pool de agentes em que o agente será instalado. Se você omitir essa sinalização, o agente será instalado no pool transfer_service_default do seu projeto.

O comando docker run é compatível com mais sinalizações.

• O --enable-mount-directory monta todo o sistema de arquivos no diretório /transfer_root do contêiner. Se --enable-mount-directory for especificado, as restrições de diretório usando a sinalização -v não serão aplicadas.

  Observação: se os agentes forem executados como raiz e tiverem acesso a todo o sistema de arquivos, uma pessoa mal-intencionada poderá assumir o controle do host. É altamente recomendável que você restrinja o acesso do agente apenas aos diretórios necessários.

• --creds-file=CREDENTIAL_FILE especifica o caminho para um arquivo de credencial da conta de serviço no formato JSON. A menos que você esteja usando --enable_mount_directory, será necessário:

  1. Monte o arquivo de credenciais usando a sinalização -v.
  2. Adicione o prefixo /transfer_root ao caminho --creds-file.

  Exemplo:

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3 especifica que esse agente é para transferências do armazenamento compatível com S3. Os agentes instalados com essa opção não podem ser usados para transferências de sistemas de arquivos POSIX.

• Se a transferência for de armazenamento compatível com S3 ou AWS S3, transmita o ID da chave de acesso e a chave secreta usando variáveis de ambiente:

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY especifica um proxy de encaminhamento na sua rede. O valor de PROXY é o URL e a porta HTTP do servidor proxy. Para evitar solicitações de encapsulamento duplo na criptografia TLS, especifique o URL HTTP e não um HTTPS. Essas solicitações impedem que o servidor proxy envie solicitações de saída válidas.

• --agent-id-prefix=ID_PREFIX especifica um prefixo opcional que é anexado ao ID do agente para ajudar a identificar o agente ou a máquina no Console do Google Cloud. Quando um prefixo é usado, o ID do agente é formatado como prefix + hostname + Docker container ID.

• --log-dir=LOGS_DIRECTORY modifica o diretório no qual o agente grava registros. O diretório padrão é /tmp/.

  Se você não tiver especificado --enable_mount_directory, será necessário prefixar esse caminho com /transfer_root. Por exemplo, /transfer_root/logs.

• --max-physical-mem=MAX_MEMORY: por padrão, os agentes usam no máximo 8 GiB de memória do sistema. Se isso não se encaixar no seu ambiente, será possível especificar um uso máximo de memória relevante nos seguintes formatos:

  Valor de max-physical-mem	Configuração máxima de memória
  6g	6 gigabytes
  6gb	6 gigabytes
  6GiB	6 gibibytes

Confirmar as conexões do agente

Para confirmar se os agentes estão conectados:

1. No Console do Google Cloud, acesse a página Pools de agentes.

   Acessar pools de agentes

   Os pools de agentes são exibidos com o número de agentes conectados.

2. Selecione um pool de agentes para ver os detalhes dos agentes conectados.

Se um novo agente não aparecer na página do pool de agentes dentro de dez minutos da criação, consulte Os agentes não estão conectados.

Monitorar a atividade do agente

Use os alertas do Cloud Monitoring para monitorar a atividade do agente.

O Monitoring está disponível nas dimensões project, agent_pool e agent_id.

Usando esses dados de monitoramento, é possível configurar alertas para receber notificações sobre possíveis problemas na transferência. Para isso, crie um alerta em uma das seguintes métricas do Google Cloud:

Nome da métrica	O que ela descreve	Sugestões de uso
storagetransfer.googleapis.com/agent/transferred_bytes_count	Mede a rapidez com que um agente específico está transferindo dados em todos os jobs que ele atende em um determinado momento.	Alerta para quedas no desempenho.
storagetransfer.googleapis.com/agent/connected	Um valor booleano True para cada agente que enviou ao Google Cloud uma mensagem recente com sinal de funcionamento.	Alerta para agentes com falha Ficar abaixo do número de agentes que você considera necessário para um desempenho razoável Sinalizar um problema com as máquinas do agente

Interromper um agente

Para interromper um agente, execute docker stop no ID do contêiner do Docker do agente. Para encontrar o ID e interromper o agente, faça o seguinte:

1. No Console do Google Cloud, acesse a página Pools de agentes.

   Acessar pools de agentes

2. Selecione o pool de agentes que contém o agente a ser interrompido.

3. Selecione um agente na lista. Use o campo Filtro para procurar prefixos, status do agente, idade do agente, entre outros.

4. Clique em Interromper agente. O comando docker stop com o ID do contêiner específico é exibido.

5. Execute o comando na máquina em que o agente está sendo executado. Um comando docker stop bem-sucedido retorna o ID do contêiner.

Depois de interrompido, o agente é mostrado na lista de pools de agentes como Desconectado.

Excluir um agente

Para excluir agentes específicos, liste os que estão em execução na sua máquina:

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Em seguida, transmita os IDs do agente para transfer agents delete:

gcloud transfer agents delete --ids=id1,id2,…

Para excluir todos os agentes em execução na máquina, use a sinalização --all ou --uninstall. Ambas as sinalizações excluem todos os agentes na máquina. A sinalização --uninstall também desinstala a imagem do Docker do agente.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Detalhes da transferência do sistema de arquivos

Transferências incrementais

O Storage Transfer Service começa todas as transferências calculando os dados presentes na origem e no destino para determinar quais arquivos de origem são novos, atualizados ou excluídos desde a última transferência. Fazemos isso para reduzir a quantidade de dados que enviamos de suas máquinas, para usar a largura de banda de forma eficaz e para reduzir o tempo de transferência.

Para detectar se um arquivo foi alterado, usamos um algoritmo semelhante a gsutil rsync: verificamos a hora da última modificação e o tamanho do arquivo de origem e comparamos com a hora da última modificação e o tamanho registrados quando o arquivo foi copiado pela última vez. Quando detectamos um arquivo novo ou alterado, copiamos o arquivo inteiro para o destino. Para mais informações sobre a atualização de arquivos, consulte Detalhes da consistência dos dados.

Por padrão, não agimos em arquivos excluídos na origem, apesar de detectá-los. Se você escolher a opção de sincronização Excluir arquivos de destino que também não estejam na origem ao criar ou editar, a transferência excluirá o objeto correspondente no destino.

Se você escolher a opção de sincronização Excluir arquivos de destino que também não estejam na origem, os arquivos excluídos acidentalmente na origem também serão excluídos no destino. Para evitar a perda de dados devido a exclusões acidentais, recomendamos que você ative o controle de versões de objetos no bucket de destino, se optar por usar essa opção. Em seguida, se você excluir um arquivo acidentalmente, poderá restaurar seus objetos no Cloud Storage para uma versão mais antiga.

Detalhes de consistência de dados

Uma operação de transferência bem-sucedida transfere todos os arquivos de origem que existiam e não foram modificados durante todo o tempo de execução da operação. Os arquivos de origem que foram criados, atualizados ou excluídos durante uma transferência podem ou não ter essas alterações refletidas no conjunto de dados de destino.

O Serviço de transferência do Cloud Storage usa o horário e o tamanho da última modificação de um arquivo para determinar se ele foi modificado. Se isso tiver acontecido sem uma mudança no horário ou no tamanho da última modificação e você ativar a opção delete-objects-from-source, os dados da alteração podem ser perdidos.

Ao usar o recurso delete-objects-from-source, é recomendamos que você congele as gravações na origem durante a transferência para evitar a perda de dados.

Para fazer isso, siga um destes procedimentos:

• Clone o diretório que você quer transferir e use o diretório clonado como origem do processo.
• Interrompa os aplicativos que fazem gravações no diretório de origem.

Caso seja importante capturar as alterações que ocorreram durante uma transferência, execute-a novamente ou defina o sistema de arquivos de origem como somente leitura enquanto a operação estiver em execução.

Como o Cloud Storage não compreende a noção de diretórios, os diretórios de origem vazios não são transferidos.

Importante: recomendamos que você verifique se uma transferência foi concluída corretamente antes de excluir os dados de origem. O serviço não permite restaurar dados no Cloud Storage.