Gerenciar pools de agentes

Um pool de agente é um conjunto de agentes que usam a mesma configuração, com acesso e visibilidade uniformes à origem e ao destino. Os pools de agentes também fornecem controle sobre os limites da largura de banda de transferência.

Todos os agentes precisam pertencer a um pool de agentes.

Neste guia, descrevemos como usar pools de agentes.

Antes de começar

Você precisa ter as permissões corretas no seu projeto para trabalhar com pools de agentes. Consulte Controle de acesso com o IAM para mais detalhes.

É possível ver suas permissões atuais.

Para usar comandos gcloud, instale a ferramenta de linha de comando gcloud.

Criar um pool de agentes

Não inclua informações sensíveis, como informações de identificação pessoal (PII, na sigla em inglês) ou dados de segurança no nome do pool de agentes ou 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 criar um pool de agentes:

Console do Google Cloud

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

    Acessar pools de agentes

    A página Pools de agente será exibida, listando os pools de agentes atuais.

  2. Clique em Criar outro pool.

  3. Dê um nome ao pool e, se quiser, descreva-o.

  4. É possível definir um limite de largura de banda que será aplicado ao pool como um todo. A largura de banda especificada em MB/s será dividida entre todos os agentes no pool. Consulte Gerenciar largura de banda da rede para mais informações.

  5. Clique em Criar.

API REST

Use projects.agentPools.create:

POST https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools?agent_pool_id=AGENT_POOL_ID

Em que:

  • PROJECT_ID: o ID do projeto em que você está criando o pool de agentes.
  • AGENT_POOL_ID: o ID do pool de agentes que você está criando.

Se um pool de agentes ficar preso no estado Creating por mais de 30 minutos, recomendamos excluir o pool de agentes e criá-lo novamente.

Revogar as permissões necessárias do Serviço de transferência do Cloud Storage de um projeto enquanto um pool de agentes está no estado Creating leva a um comportamento de serviço incorreto.

CLI gcloud

Para criar um pool de agentes com a ferramenta de linha de comando gcloud, execute gcloud transfer agent-pools create.

gcloud transfer agent-pools create AGENT_POOL

Quando as seguintes opções estiverem disponíveis:

  • AGENT_POOL é um identificador exclusivo e permanente desse pool.

  • --no-async bloqueia outras tarefas no seu terminal até que o pool seja criado. Se não for incluído, a criação do pool será executada de forma assíncrona.

  • --bandwidth-limit define a largura de banda em MB/s a ser disponibilizada aos agentes deste pool. Um limite de largura de banda se aplica a todos os agentes em um pool e impede que a carga de trabalho de transferência do pool interrompa outras operações que compartilham a largura de banda. Por exemplo, digite "50" para definir um limite de largura de banda de 50 MB/s. Se a sinalização não for especificada, os agentes desse pool usarão toda a largura de banda disponível para eles.

  • --display-name é um nome modificável para ajudar você a identificar esse pool. É possível incluir detalhes que não se encaixam no nome completo exclusivo do recurso do pool.

Atribuir agentes a um pool

Os novos pools de agentes estão vazios e precisam ter agentes atribuídos a eles. Só é possível atribuir um agente a um pool de agentes no momento da criação.

Se um pool de agentes não for especificado, o agente será atribuído ao pool transfer_service_default.

Para criar um agente e atribuí-lo a um pool:

Console do Google Cloud

  1. Na página Pools de agente, selecione o pool a que você quer atribuir os agentes.

  2. Clique em Instalar agente. O guia de instalação do agente é exibido.

  3. Siga as instruções para criar o agente neste pool de agentes.

CLI gcloud

Para usar a ferramenta de linha de comando gcloud para criar um agente e atribuí-lo a um pool, execute gcloud transfer agents install. O agente precisa ser instalado em uma máquina com acesso raiz ao sistema de arquivos.

gcloud transfer agents install --pool=AGENT_POOL

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

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=AGENT_POOL

Consulte Gerenciar agentes de transferência para mais detalhes.

Para mais opções, consulte Opção avançada do agente.

Para gerenciar agentes, consulte Gerenciar agentes de transferência.

Atribuir um pool de agentes a um job

Depois que o pool de agentes é criado, ele pode ser atribuído a um job durante a criação ou atualização dele.

Atualizar um pool de agentes

É possível atualizar o nome de exibição e o limite de largura de banda de um pool de agentes.

Para atualizar um pool de agentes:

Console do Google Cloud

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

Acessar pools de agentes

Você pode editar os seguintes itens:

  • Nome de exibição do pool de agentes: clique em Editar ao lado do nome atual do pool de agentes.

  • Limite de largura de banda do pool de agentes: clique em Definir limite de largura de banda e insira um novo limite na caixa de diálogo Definir limite de largura de banda. Clique em Definir limite para aplicar o novo limite de largura de banda. A largura de banda é compartilhada entre todos os agentes no pool.

API REST

Para atualizar um pool de agentes, use projects.agentPools.patch com uma máscara de campo dos campos a serem atualizados. Os campos do pool de agentes a seguir podem ser atualizados:

Por exemplo, para atualizar displayName para my-transfer, forneça a máscara de campo "displayName,my-transfer".

Veja a seguir um exemplo de solicitação de patch para atualizar o nome de exibição:

PATCH https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL:"displayName,NEW_DISPLAY_NAME"

Em que:

  • PROJECT_ID: o ID do projeto em que você está atualizando o pool de agentes.
  • AGENT_POOL: o nome do pool de agentes que você está atualizando.
  • NEW_DISPLAY_NAME: o novo nome de exibição deste pool de agentes.

Veja um exemplo de solicitação de patch para atualizar o limite de largura de banda:

PATCH https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL:"bandwidthLimit,NEW_LIMIT"

Em que:

  • PROJECT_ID: o ID do projeto em que você está atualizando o pool de agentes.
  • AGENT_POOL: o ID do pool de agentes que você está atualizando.
  • NEW_LIMIT: o novo limite de largura de banda para este pool de agentes.

CLI gcloud

Para usar a ferramenta de linha de comando gcloud para atualizar um pool de agentes, execute gcloud transfer agent-pools update.

gcloud transfer agent-pools update AGENT_POOL \
  [--bandwidth-limit=NEW_BANDWIDTH_LIMIT] [--clear-bandwidth-limit] \
  [--clear-display-name] [--display-name=NEW_DISPLAY_NAME]

O argumento a seguir é obrigatório:

  • AGENT_POOL é o identificador exclusivo e permanente desse pool. AGENT_POOL identifica o pool de agentes a ser atualizado e não pode ser atualizado.

As sinalizações a seguir podem ser especificadas com este comando:

  • --bandwidth-limit pode ser atualizado ou removido especificando --clear-bandwidth-limit. Consulte Criar um pool de agentes para mais detalhes sobre os limites de largura de banda.

  • --display-name pode ser atualizado ou excluído com a sinalização --clear-display-name.

Excluir um pool de agentes

É possível excluir um pool de agentes que não tenha agentes ativos nem execuções de jobs ativos.

Para excluir um pool de agentes:

Console do Google Cloud

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

    Acessar pools de agentes

  2. Clique em Excluir Leia o pop-up e clique em Excluir para confirmar.

    Se o botão de exclusão não estiver ativo, será necessário interromper todos os agentes e jobs associados a este pool.

API REST

Use projects.agentPools.delete:

DELETE https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

Em que:

  • PROJECT_ID: o ID do projeto do qual você está excluindo o pool de agentes.
  • AGENT_POOL: o nome do pool de agentes.

CLI da gcloud

Para usar a ferramenta de linha de comando gcloud para excluir um pool de agentes, execute gcloud transfer agent-pools delete.

gcloud transfer agent-pools delete AGENT_POOL

O argumento a seguir é obrigatório:

  • AGENT_POOL é o identificador exclusivo e permanente desse pool.

Antes de excluir um pool, todos os agentes nele precisam ser interrompidos, os jobs do pool precisam ser desativados e não pode haver operações de transferência em andamento para esse pool.

Para visualizar todos os jobs associados a um pool, selecione seu pool no Console do Google Cloud e clique na guia Transferir jobs.

Receber um pool de agentes

Para receber um pool de agentes:

Console do Google Cloud

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

Acessar pools de agentes

A página exibe uma lista de todos os pools de agentes associados ao seu projeto e as seguintes informações para cada pool de agentes:

  • Nome do pool de agentes
  • Status da conexão
  • Número de agentes conectados
  • Limite de largura de banda, se definido
  • Número de jobs de transferência associados
  • O nome de exibição do pool de agentes.

Para visualizar um pool de agentes específico, clique no Nome do pool de agentes.

As seguintes ações estão disponíveis na página de informações de um pool de agentes:

  • Instalar agente: exibe instruções para instalar agentes de transferência.
  • Interromper agente: selecione um agente na tabela e clique em Parar agente.
  • Listar jobs de transferência: clique em Jobs de transferência para exibir os agentes de jobs de transferência neste pool que estão conectados.

API REST

Use projects.agentPools.get:

GET https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

Em que:

  • PROJECT_ID: o ID do projeto que você está recebendo: um pool de agentes.
  • AGENT_POOL: o pool de agentes a ser recuperado.

CLI da gcloud

Para usar a ferramenta de linha de comando gcloud para recuperar um pool de agentes, execute gcloud transfer agent-pools describe.

gcloud transfer agent-pools describe AGENT_POOL

O argumento a seguir é obrigatório:

  • AGENT_POOL é o identificador exclusivo e permanente desse pool.

Listar pools de agentes

Para listar os pools de agentes:

Console do Google Cloud

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

Acessar pools de agentes

Todos os pools de agentes são exibidos.

API REST

Use projects.agentPools.list:

GET https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools

Em que:

  • PROJECT_ID: o ID do projeto para listar os pools de agentes.

CLI da gcloud

Para usar a ferramenta de linha de comando gcloud para listar os pools de agentes, execute gcloud transfer agent-pools list.

gcloud transfer agent-pools list \
  [--limit=LIMIT] \
  [--names=[NAMES,...]] \
  [--page-size=PAGE_SIZE]

As sinalizações a seguir podem ser especificadas com este comando:

  • --limit define o número máximo de pools de agentes que serão retornados.

  • --names especifica os nomes dos pools de agentes a serem listados. Separe vários nomes por vírgulas: por exemplo, --names=foo,bar. Se não for especificado, todos os pools de agentes do seu projeto atual serão listados.

  • --page-size define o comportamento de lotes para este comando. Por padrão, o comando list agrupa as respostas em 256 itens, buscando automaticamente o próximo lote até que todos os itens sejam listados ou limit seja atingido.

O comando retorna uma lista de pools de agentes correspondentes e os respectivos detalhes de configuração. O exemplo a seguir mostra uma resposta de amostra.

name: projects/my-project-123/agentPools/my-first-pool
state: CREATED
---
bandwidthLimit:
  limitMbps: '120'
displayName: Source A to destination Z.
name: projects/my-project-123/agentPools/a2z-pool
state: CREATED