Administrar políticas de salida de red

Overview

Las políticas de salida de red controlan a qué hosts externos pueden acceder los pods de ejecución de su agente. La política de salida se declara en el archivo del agente y se aplica al implementarlo. Cada espacio de trabajo se inicia en modo deny_all, lo que significa que el entorno de ejecución no permite conexiones salientes más allá de la política base de Atlas Agent Engine. En esta guía, aprenderá a declarar los destinos que necesita su agente y a establecer la postura de acceso saliente. Ambos se configuran para cada entorno aislado en el bloque sandboxes del archivo del agente.

La política de salida de cada entorno aislado consta de dos partes: los destinos que se declaran en network.egress y el modo de salida establecido por network.egress_mode. El modo determina cómo la plataforma aplica esos destinos (allow_list, deny_all o allow_all).

La política básica siempre permite el tráfico saliente hacia los siguientes destinos:

DNS
Servicios en el mismo espacio de nombres
El clúster Atlas vinculado a su espacio de trabajo

Dado que la política base cubre estos destinos, no es necesario agregarlos como destinos de salida.

Tip

Para aprender a vincular un clúster de Atlas a su espacio de trabajo, consulte la guía "Vincular su clúster de Atlas para la salida de red".

La política de salida se gestiona de las siguientes maneras:

Antes del primer despliegue, el archivo del agente debe declarar una política de salida. Declare la política para cada entorno aislado en sandboxes.agent.network y sandboxes.tool.network en el archivo agent.yaml. El bloque egress enumera los destinos y egress_mode establece el modo.
Implemente el agente para aplicar la política de salida. La implementación requiere el rol Project Owner.
Puedes actualizar la política de salida después del despliegue inicial. Usa agentengine agent egress add y agentengine agent egress remove para editar el bloque network.egress de cada entorno aislado y agentengine agent egress mode para configurar su network.egress_mode. Vuelve a desplegar el agente para que los cambios surtan efecto.
Utilice agentengine egress o la interfaz de usuario de acceso saliente del espacio de trabajo para inspeccionar la política implementada actualmente. Estas vistas no editan la política.

Nota

El motor de agentes de Atlas utiliza las siguientes direcciones IP de salida para destinos fuera de Atlas:

34.196.57.85
54.227.181.25

Si su agente llama a servicios externos, como Salesforce, la lista de direcciones permitidas del servicio externo debe incluir estas direcciones.

Requisitos previos

Antes de comenzar, asegúrese de cumplir con los siguientes requisitos previos:

Tienes instalada la versión 0.1.54-alpha o posterior de la interfaz de línea de comandos (CLI) agentengine, y está disponible en tu variable de entorno PATH. Para obtener más información, consulta la guía de instalación y autenticación.
Puedes autenticarte en la plataforma utilizando el comando agentengine auth login.
Usted tiene el rol de Propietario del Proyecto para implementar el agente y aplicar los cambios en la política de salida.

Cómo funcionan las políticas de salida

Las siguientes secciones describen los entornos aislados, los modos y los comportamientos que conforman una política de salida.

Sandboxes

El alcance de la salida está definido por entorno aislado (sandbox). Usted controla el entorno aislado del agente y el entorno aislado de la herramienta de forma independiente:

Sandbox	Descripción
`agent`	Entorno aislado del agente. El proceso principal del agente.
`tool`	Entorno aislado de herramientas. Ejecuta las herramientas que configure para que se ejecuten en el entorno aislado de herramientas. Por defecto, las herramientas se ejecutan en el entorno aislado del agente.

En agent.yaml, declare la política de cada entorno aislado en sandboxes.agent.network o sandboxes.tool.network. Para los comandos de la CLI, utilice --component agent o --component tool.

Las herramientas en el mismo entorno aislado pueden acceder a todos los destinos de salida que usted permita para dicho entorno. Para obtener información sobre cómo los entornos aislados comparten secretos y acceso a la red entre herramientas, consulte Limitaciones del motor del agente de MongoDB Atlas.

Modos

Cada entorno aislado (sandbox) funciona en uno de los siguientes modos, que se configura con el campo network.egress_mode del entorno aislado en el archivo del agente:

Modo	Comportamiento
`deny_all`	Bloqueado. Solo está activa la política base de la plataforma. No se puede acceder a ningún destino definido por el usuario.
`allow_list`	La política base de la plataforma está activa y se puede acceder a los destinos que aparecen en `network.egress`.
`allow_all`	Abierto. El entorno de ejecución permite el tráfico saliente a cualquier host, además de la política base.

No se puede combinar allow_all con una lista de destinos para el mismo entorno aislado. Si se configura allow_all para un entorno aislado que también incluye una lista de destinos, el archivo del agente no superará la validación.

Cómo se aplica la política de salida de Deploy

El archivo agent.yaml es la fuente de información principal para la política de salida que se aplica durante el despliegue. Antes del primer despliegue, defina una política de salida en el archivo configurando network.egress_mode para sus entornos aislados (sandboxes). Para allow_list, defina también los destinos en network.egress. El despliegue se rechazará si el archivo no define una política de salida.

Al realizar la implementación, la plataforma aplica la política a su espacio de trabajo. El modo declarado en el archivo tiene prioridad sobre el modo existente en el entorno aislado.

Tras la implementación, utilice agentengine egress o la interfaz de usuario de acceso saliente del espacio de trabajo para ver la configuración aplicada.

Nota

Si su agente utiliza servidores MCP, asegúrese de que el nombre de host de cada servidor esté incluido en el bloque network.egress del entorno aislado que lo llama. Incluir un servidor en el bloque mcp.servers no habilita automáticamente el acceso saliente.

Control de acceso basado en roles

Puede utilizar el control de acceso basado en roles (RBAC) para especificar el acceso. Las operaciones de salida requieren los siguientes roles:

Operación	Rol Requerido
Inspeccione la política de salida implementada (`agentengine egress` o la interfaz de usuario de acceso saliente del espacio de trabajo).	Miembro del proyecto (leer)
Edite la política de salida en el archivo del agente local (`agentengine agent egress add`, `agentengine agent egress remove`, `agentengine agent egress mode`)	No se requiere ningún puesto a nivel local.
Implemente el agente para aplicar la política de salida del archivo.	Propietario del proyecto

Los usuarios con el rol de Miembro del proyecto (lectura) pueden inspeccionar la política implementada. Editar el archivo del agente local no requiere un rol, pero implementar el agente para aplicar esos cambios requiere el rol de Propietario del proyecto.

Configure la política de salida en el archivo del agente.

En el archivo de agente, configure la política de salida para cada entorno aislado en el bloque network, dentro de sandboxes.agent y sandboxes.tool. Los cambios en el archivo de agente solo surtirán efecto después de implementar el agente.

Utilice el bloque network.egress de un entorno aislado para permitir un nombre de host externo para dicho entorno. El siguiente ejemplo permite que solo el entorno aislado de herramientas acceda a varios 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 que un host funcione en ambos entornos aislados, inclúyalo en la lista de cada entorno aislado.

Utilice el campo network.egress_mode de un entorno aislado para definir su postura. Los valores válidos son deny_all, allow_list y allow_all. Si omite egress_mode, un entorno aislado que enumera destinos utilizará automáticamente allow_list.

Las siguientes reglas se aplican al bloque sandboxes:

Cuando declaras sandboxes, debes incluir sandboxes.agent.
Si alguno de los entornos aislados declara salida, un entorno aislado que no declara salida utiliza deny_all.
Declara los clústeres de Atlas en el bloque network.atlas_clusters de nivel superior, no dentro de un entorno aislado (sandbox).

Tip

Si su archivo de agente declara egress o egress_mode en un bloque network de nivel superior, ejecute agentengine migrate sandboxes desde el directorio de su proyecto de agente para mover la política al bloque sandboxes.

Nota

Vuelva a implementar su agente después de cualquier cambio en el archivo del agente para que la nueva política surta efecto. La plataforma aplica la política de salida en el momento de la implementación, no en tiempo de ejecución.

Reglas para nombres de dominio completamente calificados (FQDN)

La plataforma acepta los siguientes destinos:

Nombres de host, como api.openai.com o storage.googleapis.com
Comodines de etiqueta principal con un nivel de subdominio, como *.example.com
Comodines de etiqueta principal con dos niveles de subdominio, como *.*.example.com
Comodines recursivos que coinciden con todos los niveles de subdominio, como **.example.com. La plataforma también acepta patrones como **.com.

La plataforma rechaza los siguientes destinos:

Literales IP, como 1.2.3.4
Rangos CIDR, como 10.0.0.0/8
localhost, *.local, y *.svc.cluster.local
Puntos finales de metadatos en la nube, como *.metadata.google.internal y 169.254.169.254.
Comodines sin cifrar, como * y **
Comodines no principales, como api.*.com
Patrones con más de dos comodines de una sola etiqueta, como *.*.*.example.com
Sufijos reservados, como .arpa, .test, .example y .invalid.

Si un destino infringe alguna de estas reglas, la validación falla y el destino no se aplica. Puede ejecutar agentengine agent validate para capturar el error localmente. La plataforma aplica la misma validación durante la ruta de compilación. El error identifica el motivo, como fqdn_ip_literal o fqdn_wildcard_misuse, por ejemplo:

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

Cada destino admite un rango de puertos de 1 a 65535, un máximo de 10 puertos por destino y un máximo de 50 destinos por espacio de trabajo.

Si omite los puertos para un destino, la plataforma permite todos los puertos a ese destino y devuelve una advertencia de no bloqueo.

Nota

La plataforma acepta nombres de host de clústeres de Atlas, como *.mongodb.net, pero muestra una advertencia al guardar uno, ya que un destino de salida no configura el acceso a Atlas. Para otorgar acceso a su agente a un clúster de Atlas, utilice los comandos agentengine atlas o el bloque network.atlas_clusters en su archivo agent.yaml.

Configure la salida con la CLI.

Utilice los comandos agentengine egress del directorio de su proyecto de agente para editar el archivo del agente e inspeccionar la política desplegada. Estos comandos nunca modifican directamente la política en ejecución.

Ver la política implementada

Para ver la política actual de ambos entornos aislados, puede usar el comando agentengine egress. Use el indicador --workspace para ver la política de un espacio de trabajo específico. El siguiente ejemplo muestra estos comandos:

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

El comando agentengine egress es de solo lectura. Para cambiar la política basada en archivos, edite agent.yaml o utilice agentengine agent egress add y agentengine agent egress remove, y luego vuelva a implementar el agente.

Agregar o eliminar un destino

Los comandos agentengine agent egress add y agentengine agent egress remove editan el bloque network.egress de cada entorno aislado en el archivo del agente local. Modifican un destino a la vez y dejan el resto de la lista sin cambios. Utilice la bandera --component para seleccionar un entorno aislado. Si omite la bandera, los comandos actualizan ambos entornos aislados. Estas ediciones locales no modifican la política implementada hasta que implemente el agente. Utilice estos comandos para cambiar un ú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

Pase un FQDN sin puerto a agentengine agent egress remove. Después de implementar el agente, use el comando agentengine egress o la interfaz de usuario de acceso saliente del espacio de trabajo para ver la nueva configuración.

Los comandos se comportan de la siguiente manera:

Si el entorno aislado de destino está en deny_all, add lo cambia a allow_list e imprime mode: deny_all → allow_list.
Si el entorno aislado de destino está en allow_all, add deja el archivo sin cambios, ya que los destinos no tienen efecto en el modo allow_all. Para agregar destinos, primero cambie el modo a allow_list usando el comando agentengine agent egress mode.
Si remove elimina el último destino de un sandbox, el sandbox regresa a deny_all e imprime no destinations remain; mode set to deny_all.
Agregar una copia exacta, es decir, con el mismo FQDN y los mismos puertos, no tiene ningún efecto.

Actualizar el modo de salida

Utilice agentengine agent egress mode para establecer el valor network.egress_mode de cada entorno aislado en su archivo de agente local. Utilice el indicador --component para seleccionar un entorno aislado. Implemente el agente para que estos cambios surtan efecto.

Los siguientes ejemplos muestran cómo actualizar el modo de salida:

# 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

El comando agentengine agent egress mode edita únicamente el archivo del agente local. Implemente el agente para que el cambio surta efecto.

Próximos pasos

Para aprender a configurar la salida de red paso a paso, consulte la guía "Primeros pasos con la salida de red".

Volver

Acceso al apoyo de subvenciones

Comience a usar la salida de red