Gerenciar políticas de saída da rede

Visão geral

As políticas de saída de rede controlam quais hosts externos os pods de tempo de execução do seu agente podem alcançar. A política de saída é declarada no arquivo do seu agente e aplicada quando você implementa o agente. Todo workspace começa no mododeny_all, o que significa que o tempo de execução não permite conexões de saída além da política base do Atlas Agent Engine. Neste guia, você aprenderá a declarar os destinos que seu agente precisa e definir a postura de acesso de saída. Você configura ambos para cada sandbox no bloco sandboxes do seu arquivo agente .

A política de saída de cada sandbox tem duas partes: os destinos que você declara em network.egress e o modo de saída definido por network.egress_mode. O modo determina como a plataforma força esses destinos (allow_list, deny_all ou allow_all).

A política base sempre permite o tráfego de saída para os seguintes destinos:

DNS
Serviços no mesmo namespace
O Atlas cluster vinculado ao seu workspace

Como a política base abrange esses destinos, você não adiciona nenhum deles como destino de saída.

Dica

Para saber como vincular um Atlas cluster ao seu workspace, consulte o guia Vincular seu Atlas cluster para saída de rede.

Você gerencia a política de saída das seguintes maneiras:

Antes da primeira implantação, seu arquivo de agente deve declarar uma política de saída. Declare a política para cada sandbox em sandboxes.agent.network e sandboxes.tool.network no seu arquivo agent.yaml. O bloco egress lista os destinos e egress_mode define o modo.
Implemente o agente para aplicar a política de saída. A implantação requer a função Project Owner.
Você pode atualizar a política de saída após a implantação inicial. Use agentengine agent egress add e agentengine agent egress remove para editar o bloco network.egress de cada sandbox e use agentengine agent egress mode para definir seu network.egress_mode. Redistribua o agente para que essas alterações entrem em vigor.
Use agentengine egress ou a interface do usuário de acesso de saída do espaço de trabalho para inspecionar a política atualmente implantada. Essas visualizações não editam a política.

Observação

O Atlas Agent Engine utiliza os seguintes endereços IP de saída para destinos fora do Atlas:

34.196.57.85
54.227.181.25

Se o seu agente chamar serviços externos, como o Salesforce, a lista de permissões do serviço externo deverá incluir esses endereços.

Pré-requisitos

Antes de começar, certifique-se de atender aos seguintes pré-requisitos:

Você tem a versão agentengine CLI 0.1.54-alfa ou posterior instalada e ela está disponível em sua variável de ambiente PATH. Para saber mais, consulte o guia Instalar e autenticar.
Você pode autenticar na plataforma usando o comando agentengine auth login.
Você tem a role de proprietário do projeto para distribuir o agente e aplicar as alterações na política de saída.

Como funcionam as políticas de saída

As seções a seguir descrevem os sandboxes, os modos e os comportamentos que compõem uma política de saída.

Sandboxes

A saída é definida por sandbox. Você controla a sandbox do agente e a sandbox da ferramenta de forma independente:

Sandbox	Descrição
`agent`	sandbox do agente . O principal processo do agente .
`tool`	sandbox de ferramentas. Executa as ferramentas que você configura para serem executadas na sandbox de ferramentas. Por padrão, as ferramentas são executadas na sandbox do agente .

Em agent.yaml, declare cada política do sandbox em sandboxes.agent.network ou sandboxes.tool.network. Para comandos CLI, utilize --component agent ou --component tool.

As ferramentas na mesma sandbox podem alcançar todos os destinos de saída permitidos para essa sandbox. Para saber como os sandboxes compartilham segredos e acesso à rede entre ferramentas, consulte Limitações do mecanismo do agente do MongoDB Atlas .

Modos

Cada sandbox opera em um dos seguintes modos, que você define com o campo network.egress_mode da sandbox em seu arquivo de agente :

Modo	Comportamento
`deny_all`	Bloqueado. Somente a política básica da plataforma está ativa. Nenhum destino definido pelo usuário está acessível.
`allow_list`	A política básica da plataforma está ativa e os destinos listados em `network.egress` são acessíveis.
`allow_all`	Abrir. O tempo de execução permite o tráfego de saída para qualquer host, além da política de base.

Você não pode combinar allow_all com uma lista de destino para a mesma sandbox. Se você definir allow_all para uma sandbox que também liste destinos, o arquivo do agente falhará na validação.

Como o sistema se aplica à política de saída

Seu arquivo agent.yaml é a fonte da verdade para a política de saída aplicada quando você implanta. Antes de sua primeira implantação, declare uma política de saída no arquivo definindo network.egress_mode para suas sandboxes. Para um allow_list, declare também os destinos em network.egress. A implantação será recusada se o arquivo não declarar uma política de saída.

Quando você implanta, a plataforma aplica a política ao seu espaço de trabalho. Um modo declarado no arquivo tem precedência sobre o modo existente no sandbox.

Após a implantação, use agentengine egress ou a interface do usuário de acesso de saída do espaço de trabalho para visualizar as configurações que foram aplicadas.

Observação

Se o seu agente usar servidores MCP, certifique-se de que o nome de host de cada servidor esteja listado no bloco network.egress da sandbox que o chama. A listagem de um servidor no bloco mcp.servers não abre o acesso de saída por si só.

Controle de acesso com base em função

Você pode usar o RBAC (controle de acesso baseado em roles) para especificar o acesso. As operações de saída exigem os seguintes papéis:

(operação)	Função necessária
Inspecione a política de saída implantada (`agentengine egress` ou a UI de acesso de saída do espaço de trabalho)	Membro do Projeto (leia)
Edite a política de saída no arquivo do agente local (`agentengine agent egress add`, `agentengine agent egress remove`, `agentengine agent egress mode`)	Nenhuma função necessária localmente
Implemente o agente para aplicar a política de saída do arquivo	Proprietário do projeto

Os usuários com a função de membro do projeto (leitura) podem inspecionar a política implementada. A edição do arquivo de agente local não exige uma role, mas distribuir o agente para aplicar essas alterações requer a role de Proprietário do projeto.

Definir a Política de Saída no Arquivo do Agente

Você configura a política de saída para cada sandbox no bloco network em sandboxes.agent e sandboxes.tool no seu arquivo de agente . As alterações no arquivo do agente entram em vigor somente depois que você implementa o agente.

Use o bloco network.egress de uma sandbox para permitir um nome de host externo para essa sandbox. O exemplo a seguir permite que apenas a sandbox da ferramenta alcance vários hosts:

sandboxes:
  agent:
    network:
      egress_mode: deny_all
  tool:
    network:
      egress:
        - fqdn: api.openai.com
          ports: [443]
        - fqdn: "*.googleapis.com"
          ports: [443]
        - fqdn: db.example.com
          # Omit ports, or use an empty list, to allow all ports to
          # this destination.

Para permitir um host para ambas as sandboxes, liste-o em cada sandbox.

Use o campo network.egress_mode de uma sandbox para definir sua postura. Os valores válidos são deny_all, allow_list e allow_all. Se você omitir egress_mode, uma sandbox que lista destinos utilizará automaticamente allow_list.

As seguintes regras se aplicam ao bloco sandboxes:

Ao declarar sandboxes, você deve incluir sandboxes.agent.
Se qualquer uma das sandboxes declarar saída, uma sandbox que declara nenhuma saída usará deny_all.
Declare os Atlas clusters no bloco network.atlas_clusters de nível superior, não dentro de uma sandbox.

Dica

Se o arquivo do agente declarar egress ou egress_mode em um bloco network de nível superior, execute agentengine migrate sandboxes a partir do diretório de projeto do agente para mover a política para o bloco sandboxes.

Observação

Redistribua seu agente após qualquer alteração no arquivo do agente para que a nova política entre em vigor. A plataforma aplica a política de saída no momento da implantação, não no tempo de execução.

Regras de nome de domínio totalmente qualificado (FQDN)

A plataforma aceita os seguintes destinos:

Nomes de host, como api.openai.com ou storage.googleapis.com
Curingas de rótulo principal com um nível de subdomínio, como *.example.com
Curingas de rótulo principal com dois níveis de subdomínio, como *.*.example.com
Curingas recursivos que correspondem a todos os níveis de subdomínio, como **.example.com. A plataforma também aceita padrões como **.com.

A plataforma rejeita os seguintes destinos:

Literais de IP, como 1.2.3.4
Intervalos CIDR, como 10.0.0.0/8
localhost, *.local e *.svc.cluster.local
Endpoints de metadados da nuvem, como *.metadata.google.internal e 169.254.169.254
Curingas simples, como * e **
Curingas não principais, como api.*.com
Padrões com mais de dois curingas de rótulo único, como *.*.*.example.com
Sufixos reservados, como .arpa, .test, .example e .invalid

Se um destino violar qualquer uma dessas regras, a validação falhará e o destino não será aplicado. Você pode executar agentengine agent validate para detectar o erro localmente. A plataforma aplica a mesma validação durante o caminho de construção. O erro identifica a razão, como fqdn_ip_literal ou fqdn_wildcard_misuse, por exemplo:

IP addresses are not allowed; declare a hostname such as api.example.com

Cada destino permite um intervalo de portas de 1 a 65535, um máximo de 10 portas por destino e um máximo de 50 destinos por espaço de trabalho.

Se você omitir as portas para um destino, a plataforma permitirá todas as portas para esse destino e retornará um aviso não bloqueante.

Observação

A plataforma aceita nomes de host de Atlas cluster, como *.mongodb.net, mas retorna um aviso quando você salva um, porque um destino de saída não configura o acesso ao Atlas . Para conceder ao seu agente acesso a um Atlas cluster, use os comandos agentengine atlas ou o bloco network.atlas_clusters no arquivo agent.yaml.

Configurar saída com a CLI

Use os comandos agentengine egress do diretório de projeto do agente para editar o arquivo do agente e inspecionar a política implementada. Os comandos nunca alteram diretamente a política de execução.

Visualizar a política implementada

Para visualizar a política atual para ambos os sandboxes, você pode utilizar o comando agentengine egress. Use o sinalizador --workspace para visualizar a política de um workspace específico. O exemplo a seguir mostra estes comandos:

# View the deployed policy for both sandboxes
agentengine egress
# View the policy for a specific workspace
agentengine egress --workspace my-workspace

O comando agentengine egress é somente visualização. Para alterar a política baseada em arquivo, edite agent.yaml ou use agentengine agent egress add e agentengine agent egress remove e, em seguida, redistribua o agente.

Adicionar ou remover um destino

Os comandos agentengine agent egress add e agentengine agent egress remove editam o bloco network.egress de cada sandbox no arquivo de agente local. Eles mudam um destino de cada vez e deixam o restante da lista inalterado. Use o sinalizador --component para definir uma sandbox. Se você omitir o sinalizador, os comandos atualizarão ambas as sandboxes. Essas edições locais não alteram a política implantada até que você implemente o agente. Use estes comandos para alterar um único destino:

# Add a destination for both sandboxes
agentengine agent egress add api.openai.com:443
# Add a destination with multiple ports for the tool sandbox only
agentengine agent egress add --component tool '*.mongodb.net:443,27017'
# Stop allowing a destination
agentengine agent egress remove api.openai.com

Passe um FQDN simples sem porta para agentengine agent egress remove. Depois de distribuir o agente, use o comando agentengine egress ou a interface de usuário de acesso de saída ao workspace para visualizar as novas configurações.

Os comandos se comportam da seguinte maneira:

Se a sandbox de destino estiver em deny_all, add a mudará para allow_list e imprimirá mode: deny_all → allow_list.
Se a sandbox de destino estiver em allow_all, add deixará o arquivo inalterado, pois os destinos não têm efeito no modoallow_all. Para adicionar destinos, primeiro defina o modo como allow_list usando o comando agentengine agent egress mode.
Se remove remover o último destino de uma sandbox, a sandbox retornará para deny_all e imprimirá no destinations remain; mode set to deny_all.
Adicionar uma duplicata exata, ou seja, o mesmo FQDN e as mesmas portas, não tem efeito.

Atualizar o modo de saída

Use agentengine agent egress mode para definir o valor network.egress_mode de cada sandbox em seu arquivo de agente local. Use o sinalizador --component para definir uma sandbox. Implemente o agente para que essas alterações entrem em vigor.

Os exemplos a seguir mostram como atualizar o modo de saída:

# Set allow-list mode
agentengine agent egress mode allow_list
# Set deny-all mode
agentengine agent egress mode deny_all
# Set allow-all mode
agentengine agent egress mode allow_all --confirm-allow-all

O comando agentengine agent egress mode edita somente o arquivo do agente local. Implemente o agente para que a alteração entre em vigor.

Próximos passos

Para saber como configurar a saída de rede em um tutorial passo a passo, consulte o guia Introdução à saída de rede.

Voltar

Conceder acesso ao suporte

Primeiros passos com a saída de rede