Faça a gestão dos agentes de transferência

Os agentes do Serviço de transferência de armazenamento são aplicações executadas num contentor da Open Container Initiative (OCI) que coordenam com o Serviço de transferência de armazenamento para transferências que envolvem sistemas de ficheiros ou armazenamento compatível com S3.

Por predefinição, o serviço de transferência de armazenamento usa o Docker para criar e executar contentores OCI. O serviço de transferência de armazenamento também suporta o Podman para a gestão de contentores. Tem de instalar os agentes através do comando podman run para usar o Podman.

Se a sua transferência não envolver um sistema de ficheiros ou um armazenamento compatível com S3, não precisa de configurar agentes.

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

Vista geral

  • Os processos do agente são dinâmicos. Enquanto estiver a executar uma transferência, pode adicionar agentes para aumentar o desempenho. Os agentes iniciados recentemente juntam-se ao conjunto de agentes atribuído e realizam tarefas de transferências existentes. Pode usar esta opção para ajustar o número de agentes em execução ou para adaptar o desempenho das transferências à procura de transferências em constante mudança.

  • Os processos de agentes são um coletivo tolerante a falhas. Se um agente deixar de ser executado, os restantes agentes continuam a trabalhar. Se todos os agentes pararem, quando adicionar novos agentes, a transferência é retomada no ponto em que os agentes pararam. Isto permite-lhe evitar a monitorização de agentes, a repetição de transferências ou a implementação de lógica de recuperação. Pode aplicar patches, mover e dimensionar dinamicamente os seus conjuntos de agentes sem tempo de inatividade de transferência coordenando os agentes com o Google Kubernetes Engine.

    Por exemplo, envia duas transferências enquanto dois agentes estão em execução. Se um dos agentes parar devido a um reinício da máquina ou a um patch do sistema operativo, o agente restante continua a funcionar. As duas transferências continuam a ser executadas, mas mais lentamente, uma vez que um único agente está a mover dados. Se o agente restante também parar, todas as transferências param de progredir, uma vez que não existem agentes em execução. Quando reinicia os processos do agente, as transferências são retomadas no ponto em que foram interrompidas.

  • Os processos do agente pertencem a um conjunto. Movem os seus dados em paralelo. Por este motivo, todos os agentes num conjunto têm de ter o mesmo acesso a todas as origens de dados que quer transferir.

    Por exemplo, se estiver a transferir dados de um sistema de ficheiros específico, tem de montar o sistema de ficheiros em todas as máquinas que alojam agentes no seu conjunto de agentes. Se alguns agentes no seu conjunto conseguirem alcançar uma origem de dados e outros não, as transferências dessa origem de dados não vão ser bem-sucedidas.

Antes de começar

Antes de configurar as transferências, certifique-se de que configurou o acesso: para utilizadores e contas de serviço.

Se vai usar comandos gcloud, instale a CLI gcloud.

Instale e execute agentes de transferência

Recomendamos a instalação de, pelo menos, três agentes por conjunto de agentes, idealmente em máquinas separadas. Para mais informações sobre como determinar o número de agentes a executar, consulte o artigo Maximizar o desempenho dos agentes de transferência.

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

Para instalar e executar agentes de transferência:

Google Cloud consola

  1. Na Google Cloud consola, aceda à página Pools de agentes.

    Aceda a Conjuntos de agentes

  2. Selecione o conjunto de agentes ao qual quer adicionar o novo agente.

  3. Clique em Instalar agente.

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

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

CLI gcloud

Para instalar um ou mais agentes através da CLI gcloud, execute o seguinte comando gcloud transfer agents install:

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

A ferramenta apresenta-lhe todos os passos necessários para instalar os agentes. Este comando instala NUM_AGENTS agentes na sua máquina, mapeados para o nome do conjunto especificado como POOL_NAME, e autentica o agente através das suas credenciais gcloud. O nome do conjunto tem de existir ou é devolvido um erro.

A flag --mount-directories é opcional, mas vivamente recomendada. O valor é uma lista separada por vírgulas de diretórios no sistema de ficheiros aos quais conceder acesso ao agente. A omissão desta flag monta todo o sistema de ficheiros no contentor do agente. Consulte a gcloud referência para mais detalhes.

Fontes compatíveis com S3

Quando instala agentes para usar com uma origem compatível com S3, tem de fornecer 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 predefinidas nos ficheiros 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

Use uma chave de conta de serviço

Para executar agentes com 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 flags opcionais, execute o comando gcloud transfer agents install --help ou leia a referência gcloud transfer.

Docker

Antes de usar o Docker 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 seu conjunto, execute este comando as vezes que forem necessárias.

Quando instala agentes, pode optar por fazer a autenticação através das gcloud credenciais predefinidas ou com uma conta de serviço.

Credenciais predefinidas

Para permitir que o contentor Docker se autentique com as suas gcloudcredenciais predefinidas, crie um volume Docker que contenha um ficheiro com as suas credenciais predefinidas da aplicação executando o seguinte comando:

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

Em seguida, use o seguinte comando para instalar um agente, usando a flag --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 com credenciais da conta de serviço, especifique o caminho para a chave da conta de serviço no formato JSON com a flag --creds-file.

O caminho tem de ter o prefixo da string /transfer_root.

Consulte o artigo Crie e faça a gestão de chaves de contas de serviço para mais informações sobre as chaves de contas de serviço.

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

Opções e flags

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

  • HOST_DIRECTORY é o diretório na máquina anfitriã a partir do qual pretende copiar. Pode usar mais do que uma flag -v para especificar diretórios adicionais a partir dos quais copiar.
  • CONTAINER_DIRECTORY é o diretório mapeado no contentor do agente. Tem de ser igual a HOST_DIRECTORY.
  • PROJECT_ID é o ID do projeto que está a alojar a transferência.
  • POOL_NAME é o nome do conjunto de agentes no qual instalar este agente. Se omitir esta flag, o agente é instalado no conjunto transfer_service_default do seu projeto.

O comando docker run suporta flags adicionais.

  • --enable-mount-directory monta todo o sistema de ficheiros no diretório /transfer_root no contentor. Se --enable-mount-directory for especificado, as restrições de diretório que usam a flag -v não são aplicadas.

  • --creds-file=/etc/gcloud/key.json especifica o caminho para o ficheiro de credenciais da conta de serviço no formato JSON no contentor. Este ficheiro é montado pela flag -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro no comando.

  • --enable-s3 especifica que este agente se destina a transferências a partir de armazenamento compatível com S3. Não é possível usar agentes instalados com esta opção para transferências de sistemas de ficheiros POSIX.

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

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

  • --gcs-api-endpoint=storage.LOCATION.rep.googleapis.com especifica um ponto final regional do Cloud Storage. Quando é especificado um ponto final regional do Cloud Storage, todo o tráfego de transferência de dados através do agente permanece nessa Google Cloud região. Consulte o artigo Pontos finais regionais para ver detalhes.

  • --env HTTPS_PROXY=PROXY especifica um proxy de encaminhamento na sua rede. O valor de PROXY é o URL HTTP e a porta do servidor proxy. Certifique-se de que especifica o URL HTTP e não um URL HTTPS para evitar o encapsulamento duplo de pedidos na encriptação TLS. Os pedidos com encapsulamento duplo impedem que o servidor proxy envie pedidos de saída válidos.

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

  • --log-dir=LOGS_DIRECTORY modifica o diretório para o qual o agente escreve registos. O diretório predefinido é /tmp/.

    Se não tiver especificado --enable_mount_directory, tem de prefixar este caminho com /transfer_root. Por exemplo, /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: os agentes usam, por predefinição, um máximo de 8 GiB de memória do sistema. Se o valor predefinido não se adequar ao seu ambiente, pode especificar uma utilização máxima de memória relevante nos seguintes formatos:

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

  • --network=DOCKER_NETWORK: especifique a rede Docker para este contentor. A especificação de --network=host pode melhorar o desempenho ao reduzir a sobrecarga da rede, mas permite que o recipiente tenha acesso total à rede do anfitrião.

Podman

Antes de usar o Podman para instalar agentes, instale o Podman:

sudo apt-get update
sudo apt-get -y install podman

Quando instala agentes, pode optar por fazer a autenticação através das gcloud credenciais predefinidas ou com uma conta de serviço.

Credenciais predefinidas

Para permitir que o contentor do agente faça a autenticação com as credenciais predefinidas da CLI do Google Cloud, crie um volume que contenha um ficheiro com as credenciais predefinidas da aplicação executando o seguinte comando:

gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io
sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth application-default login

Em seguida, use o seguinte comando para instalar um agente, usando a flag --volumes-from para montar o volume de credenciais gcloud-config. O comando instala um agente. Para aumentar o número de agentes no seu conjunto, execute este comando novamente as vezes que forem necessárias.

sudo podman 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 através de credenciais da conta de serviço, tem de disponibilizar a chave da conta de serviço no formato JSON no contentor. Para isso:

  1. Monte a localização do anfitrião da chave em qualquer caminho no contentor. Por exemplo: -v $HOME/.config/gcloud/credentials.json:/key.json:ro. Isto especifica que a chave está localizada na máquina anfitriã em $HOME/.config/gcloud/credentials.json e deve ser montada como /key.json no contentor. O símbolo ro indica que o ficheiro é disponibilizado como só de leitura para o contentor.
  2. Especifique o caminho do contentor da chave como o valor de --creds-file. No exemplo do passo anterior, especifique --creds-file=/key.json.

Consulte o artigo Crie e faça a gestão de chaves de contas de serviço para mais informações sobre as chaves de contas de serviço.

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opções e flags

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

  • HOST_DIRECTORY é o diretório na máquina anfitriã a partir do qual pretende copiar. Pode usar mais do que uma flag -v para especificar diretórios adicionais a partir dos quais copiar.
  • CONTAINER_DIRECTORY é o diretório mapeado no contentor do agente. Tem de ser igual a HOST_DIRECTORY.
  • PROJECT_ID é o ID do projeto que está a alojar a transferência.
  • POOL_NAME é o nome do conjunto de agentes no qual instalar este agente. Se omitir esta flag, o agente é instalado no conjunto transfer_service_default do seu projeto.

O comando podman run suporta flags adicionais.

  • --enable-mount-directory monta todo o sistema de ficheiros no diretório /transfer_root no contentor. Se --enable-mount-directory for especificado, as restrições de diretório que usam a flag -v não são aplicadas.

  • --creds-file=/etc/gcloud/key.json especifica o caminho para o ficheiro de credenciais da conta de serviço no formato JSON no contentor. Este ficheiro é montado pela flag -v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro no comando.

  • --enable-s3 especifica que este agente se destina a transferências a partir de armazenamento compatível com S3. Não é possível usar agentes instalados com esta opção para transferências de sistemas de ficheiros POSIX.

  • Se a transferência for do AWS S3 ou de armazenamento compatível com o S3, transmita o ID da chave de acesso e a chave secreta através de 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 HTTP e a porta do servidor proxy. Certifique-se de que especifica o URL HTTP e não um URL HTTPS para evitar o encapsulamento duplo de pedidos na encriptação TLS. Os pedidos com encapsulamento duplo impedem que o servidor proxy envie pedidos de saída válidos.

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

  • --log-dir=LOGS_DIRECTORY modifica o diretório para o qual o agente escreve registos. O diretório predefinido é /tmp/.

    Se não tiver especificado --enable_mount_directory, tem de prefixar este caminho com /transfer_root. Por exemplo, /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: os agentes usam, por predefinição, um máximo de 8 GiB de memória do sistema. Se o valor predefinido não se adequar ao seu ambiente, pode especificar uma utilização máxima de memória relevante nos seguintes formatos:

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

  • --network=DOCKER_NETWORK: especifique a rede Docker para este contentor. A especificação de --network=host pode melhorar o desempenho ao reduzir a sobrecarga da rede, mas permite que o recipiente tenha acesso total à rede do anfitrião.

Resolução de problemas

Se a sua configuração do SELinux exigir que sejam colocadas etiquetas no conteúdo do volume montado num contentor, adicione a flag :Z ao volume:

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json:ro \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Sem uma etiqueta, o sistema de segurança pode impedir que os processos em execução no contentor usem o conteúdo. Por predefinição, o Podman não altera as etiquetas definidas pelo SO.

Confirme as associações de agentes

Para confirmar que os agentes estão ligados:

  1. Na Google Cloud consola, aceda à página Pools de agentes.

    Aceda a Conjuntos de agentes

    São apresentados os seus conjuntos de agentes, com o número de agentes ligados.

  2. Selecione um conjunto de agentes para ver detalhes sobre os agentes associados.

Se um novo agente não aparecer na página do conjunto de agentes no prazo de 10 minutos após a sua criação, consulte o artigo Os agentes não estão ligados.

Monitorize a atividade dos agentes

Pode usar o Cloud Monitoring para monitorizar a atividade do agente.

A monitorização está disponível nas dimensões project, agent_pool e agent_id.

Com estes dados de monitorização, pode configurar alertas para receber notificações sobre potenciais problemas com a sua transferência. Para o fazer, crie um alerta numa das seguintes métricas Google Cloud :

Nome da métrica O que descreve Usos sugeridos
storagetransfer.googleapis.com/agent/transferred_bytes_count Mede a rapidez com que um agente específico move os dados em todas as tarefas que serve num determinado momento. Alerta para quedas no desempenho.
storagetransfer.googleapis.com/agent/connected Um valor booleano que é Verdadeiro para cada agente que Google Cloud recebeu uma mensagem de sinal de vida recente.
  • Alerta para agentes com falhas
  • Não ter um número de agentes que considere necessário para um desempenho razoável
  • Comunique um problema com as máquinas dos agentes

Pare um agente

Para parar um agente, execute docker stop no ID do contentor Docker do agente. Para encontrar o ID e parar o agente:

  1. Na Google Cloud consola, aceda à página Pools de agentes.

    Aceda a Conjuntos de agentes

  2. Selecione o conjunto de agentes que contém o agente a parar.

  3. Selecione um agente na lista. Use o campo Filtrar para pesquisar por prefixos, estado do agente, idade do agente e muito mais.

  4. Clique em Parar agente. É apresentado o comando docker stop com o ID do contentor específico.

  5. Execute o comando na máquina na qual o agente está a ser executado. Um comando docker stop bem-sucedido devolve o ID do contentor.

Depois de parado, o agente é apresentado na lista de conjuntos de agentes como Desligado.

Reinicie um agente

Não é possível reiniciar os agentes parados. Em alternativa, instale novos agentes no conjunto de agentes.

Elimine um agente

Para eliminar agentes específicos, liste os agentes que estão a ser executados no seu computador:

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

Em seguida, transmita os IDs dos agentes para transfer agents delete:

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

Para eliminar todos os agentes em execução na máquina, use o comando --all ou o comando --uninstall. Ambas as flags eliminam todos os agentes na máquina; a flag --uninstall desinstala adicionalmente a imagem do Docker do agente.

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

Detalhes da transferência do sistema de ficheiros

Transferências incrementais

O Serviço de transferência de armazenamento inicia todas as transferências calculando os dados presentes na origem e no destino para determinar que ficheiros de origem são novos, foram atualizados ou foram eliminados desde a última transferência. Fazemos isto para reduzir a quantidade de dados que enviamos das suas máquinas, para usar a largura de banda de forma eficaz e para reduzir os tempos de transferência.

Para detetar se um ficheiro foi alterado, verificamos a hora da última modificação e o tamanho do ficheiro de origem, e comparamos esses dados com a hora da última modificação e o tamanho registados quando o ficheiro foi copiado pela última vez. Quando detetamos um ficheiro novo ou alterado, copiamos o ficheiro completo para o destino. Para mais informações sobre a atualidade dos ficheiros, consulte os Detalhes da consistência dos dados.

Por predefinição, detetamos, mas não tomamos medidas em relação aos ficheiros eliminados na origem. Se escolher a opção de sincronização Eliminar ficheiros de destino que também não estejam na origem quando criar ou editar, a transferência elimina o objeto correspondente no destino.

Se escolher a opção de sincronização Eliminar ficheiros de destino que também não estão na origem, os ficheiros eliminados acidentalmente na origem também são eliminados no destino. Para evitar a perda de dados devido a eliminações acidentais, recomendamos que ative a criação de versões de objetos no seu contentor de destino se optar por usar esta opção. Em seguida, se eliminar um ficheiro acidentalmente, pode restaurar os seus objetos no Cloud Storage para uma versão mais antiga.

Detalhes da consistência dos dados

Uma operação de transferência bem-sucedida transfere todos os ficheiros de origem que existiam e não foram modificados durante todo o tempo de execução da operação. Os ficheiros de origem que foram criados, atualizados ou eliminados 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 de armazenamento usa a hora e o tamanho da última modificação de um ficheiro para determinar se este foi alterado. Se um ficheiro for atualizado sem alterar a hora da última modificação nem o tamanho, e ativar a opção delete-objects-from-source, pode perder dados dessa alteração.

Quando usar a funcionalidade delete-objects-from-source, recomendamos vivamente que congele as gravações na origem durante a transferência para se proteger contra a perda de dados.

Para congelar as gravações na sua origem, faça uma das seguintes ações:

  • Clone o diretório que pretende transferir e, em seguida, use o diretório clonado como origem da transferência.
  • Interrompa as aplicações que escrevem no diretório de origem.

Se for importante captar as alterações ocorridas durante uma transferência, pode voltar a executar a transferência ou definir o sistema de ficheiros de origem como só de leitura enquanto a operação está em execução.

Uma vez que o Cloud Storage não tem a noção de diretórios, os diretórios de origem vazios não são transferidos.