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. 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
No Console do Google Cloud, acesse a página Pools de agentes.
A página Pools de agente será exibida, listando os pools de agentes atuais.
Clique em Criar outro pool.
Dê um nome ao pool e, se quiser, descreva-o.
É 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.
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 da 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 NAME \
[--no-async] \
[--bandwidth-limit=BANDWIDTH_LIMIT] \
[--display-name=DISPLAY_NAME]
Quando as seguintes opções estiverem disponíveis:
NAME é um identificador exclusivo e permanente desse pool.
--no-asyncbloqueia 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-limitdefine 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
Na página Pools de agente, selecione o pool a que você quer atribuir os agentes.
Clique em Instalar agente. O guia de instalação do agente é exibido.
Siga as instruções para criar o agente neste pool de agentes.
CLI da 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=POOL_NAME
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.
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_ID}:"displayName,NEW_NAME"
Em que:
PROJECT_ID: o ID do projeto em que você está atualizando o pool de agentes.AGENT_POOL_ID: o ID do pool de agentes que você está atualizando.NEW_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_ID}:"bandwidthLimit,NEW_LIMIT"
Em que:
PROJECT_ID: o ID do projeto em que você está atualizando o pool de agentes.AGENT_POOL_ID: 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 NAME \
[--bandwidth-limit=NEW_BANDWIDTH_LIMIT] [--clear-bandwidth-limit] \
[--clear-display-name] [--display-name=NEW_DISPLAY_NAME]
O argumento a seguir é obrigatório:
- NAME é o identificador exclusivo e permanente desse pool.
NAMEidentifica 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-limitpode 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-namepode 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
No Console do Google Cloud, acesse a página Pools de agentes.
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/{name=PROJECT_ID/*/agentPools/}
Em que:
PROJECT_ID: o ID do projeto do qual você está excluindo o 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 NAME
O argumento a seguir é obrigatório:
- NAME é 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.
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
GET https://storagetransfer.googleapis.com/v1/{name=PROJECT_ID/*/agentPools/}
Em que:
PROJECT_ID: o ID do projeto que você está recebendo: um pool de agentes.
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 NAME
O argumento a seguir é obrigatório:
- NAME é 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.
Todos os pools de agentes são exibidos.
API REST
GET https://storagetransfer.googleapis.com/v1/projects/{project_id=PROJECT_ID}/agentPools
Em que:
PROJECT_ID: o ID do projeto que você está recebendo: um pool 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:
--limitdefine o número máximo de pools de agentes que serão retornados.--namesespecifica 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-sizedefine o comportamento de lotes para este comando. Por padrão, o comandolistagrupa as respostas em 256 itens, buscando automaticamente o próximo lote até que todos os itens sejam listados oulimitseja 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