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.
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
Recomendamos instalar no mínimo três agentes por pool de agentes, de preferência em um e 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:
Console do Google Cloud
No Console do Google Cloud, acesse a página Pools de agentes.
Selecione o pool de agentes a que o novo agente será adicionado.
Clique em Instalar agente.
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 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
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.
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 aHOST_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 pooltransfer_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.--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:- Monte o arquivo de credenciais usando a sinalização
-v
. - Adicione o prefixo
/transfer_root
ao caminho--creds-file
.
Exemplo:
-v /tmp/key.json:/tmp/key.json \ --creds-file=/transfer_root/tmp/key.json
- Monte o arquivo de credenciais usando a sinalização
--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 dePROXY
é 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 comoprefix + 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:
No Console do Google Cloud, acesse a página Pools de agentes.
Os pools de agentes são exibidos com o número de agentes conectados.
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. |
|
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:
No Console do Google Cloud, acesse a página Pools de agentes.
Selecione o pool de agentes que contém o agente a ser interrompido.
Selecione um agente na lista. Use o campo Filtro para procurar prefixos, status do agente, idade do agente, entre outros.
Clique em Interromper agente. O comando
docker stop
com o ID do contêiner específico é exibido.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, 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 uma mudança copiamos o arquivo inteiro para seu destino. Para mais informações sobre a atualização do arquivo, consulte Detalhes da consistência de 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.