管理网络出口策略

Overview

网络出口策略控制代理的运行时 Pod 可以访问哪些外部主机。出口策略在代理文件中声明，并在部署代理时应用。每个工作区都以 deny_all模式启动，这意味着运行时允许超出Atlas助手引擎基本策略的出站连接。在本指南中，您学习；了解如何声明代理所需的目标并设立出站访问状态。您可以在代理文件的 sandboxes区块中为每个沙箱配置这两个功能。

每个沙箱的出口策略都包含两部分：在 network.egress 中声明的目标，以及 network.egress_mode设立的出口模式。模式决定了平台如何执行这些目标（allow_list、deny_all 或 allow_all）。

基本策略始终允许出站流量流向以下目标：

DNS
同一命名空间中的服务
链接到工作区的Atlas 集群

由于基本策略涵盖这些目标，因此您不要将其中任何一个添加为出口目标。

提示

要学习；了解如何将Atlas 集群链接到工作区，请参阅链接Atlas集群以获取网络出口指南。

您可以通过以下方式管理出口策略：

在首次部署之前，您的代理文件必须声明出口策略。在 agent.yaml文件中的 sandboxes.agent.network 和 sandboxes.tool.network 下声明每个沙箱的策略。 egress区块会列出目标，egress_mode 则会设置模式。
部署代理以应用出口策略。部署需要 Project Owner角色。
您可以在初始部署后更新出口策略。使用 agentengine agent egress add 和 agentengine agent egress remove 编辑每个沙箱的 network.egress区块，并使用 agentengine agent egress mode设立其 network.egress_mode。重新部署代理以使这些更改生效。
使用 agentengine egress 或工作区出站访问用户界面检查当前部署的策略。这些视图不会编辑策略。

注意

Atlas助手引擎将以下出口IP地址用于Atlas之外的目的地：

34.196.57.85
54.227.181.25

如果您的代理调用外部服务，例如 Salesforce，则外部服务的允许列表必须包含这些地址。

先决条件

开始之前，请确保满足以下先决条件：

您已安装 agentengine CLI版本 0.1.54-alpha 或更高版本，并且可在 PATH 环境变量中使用。要学习；了解更多信息，请参阅《安装和身份验证指南》。
您可以使用 agentengine auth login 命令向平台进行身份验证。
您具有项目所有者角色，可以部署代理并应用出口策略更改。

出口策略的工作原理

以下部分描述了构成出口策略的沙箱、模式和行为。

Sandboxes

出口的范围按沙箱确定。您可以独立控制代理沙箱和工具沙箱：

Sandbox	说明
`agent`	代理沙箱。主代理进程。
`tool`	工具沙箱。运行您配置为在工具沙箱中运行的工具。默认下，工具在代理沙箱中运行。

在 agent.yaml 中，在 sandboxes.agent.network 或 sandboxes.tool.network 下声明每个沙箱的策略。对于CLI命令，请使用 --component agent 或 --component tool。

同一沙箱中的工具可以到达您为该沙箱允许的所有出口目的地。要学习；了解沙箱如何在工具之间股票密钥和网络访问权限，请参阅MongoDB Atlas助手引擎限制。

模式

每个沙箱都以以下模式之一运行，您可以使用代理文件中沙箱的 network.egress_mode字段设立：

模式	行为
`deny_all`	已锁定。仅平台基本策略处于活动状态。无法访问用户定义的目标。
`allow_list`	平台基本策略处于活动状态，可以访问 `network.egress` 中列出的目标。
`allow_all`	打开。除基本策略外，运行时还允许流向任何托管的出站流量。

您不能将 allow_all 与同一沙箱的目标列表组合使用。如果您为也列出目标的沙箱设立allow_all，则代理文件将无法通过验证。

Deploy 如何应用出口策略

您的 agent.yaml文件是部署时应用的出口策略的真实来源。在首次部署之前，通过为沙箱设置 network.egress_mode 来在文件中声明出口策略。对于 allow_list，还要在 network.egress 中声明目标。如果文件未声明出口策略，则部署被拒绝。

当您部署}时，平台会将策略应用于您的工作区。该文件中声明的模式优先于沙箱的现有模式。

部署后，使用 agentengine egress 或工作区出站访问用户用户界面查看已应用的设置。

注意

如果您的代理使用 MCP 服务器，请确保每个服务器的主机名都列在调用它的沙箱的 network.egress区块中。在 mcp.servers区块下列出服务器不会自行打开出站访问权限。

基于角色的访问控制

您可以使用基于角色的访问控制 (RBAC) 来指定访问权限。出口操作需要以下角色：

操作	所需角色
检查已部署的出口策略（`agentengine egress` 或工作区出站访问用户界面）	项目成员（已读）
编辑本地代理文件中的出口策略（`agentengine agent egress add`、`agentengine agent egress remove`、`agentengine agent egress mode`）	本地无需角色
部署代理以应用文件的出口策略	项目所有者

具有项目成员（读取）角色的用户可以检查已部署的策略。编辑本地代理文件不需要角色，但部署代理以应用这些更改需要“项目所有者”角色。

在代理文件中设置出口策略

您可以在代理文件中 sandboxes.agent 和 sandboxes.tool 下的 network区块中为每个沙箱配置出口策略。对代理文件的更改仅在部署代理后才会生效。

使用沙箱的 network.egress区块允许该沙箱使用外部主机名。以下示例仅允许工具沙箱访问多个主机：

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.

要允许一个托管用于两个沙箱，请在每个沙箱下列出该主机。

使用沙箱的 network.egress_mode字段设立其状态。有效值为 deny_all、allow_list 和 allow_all。如果省略 egress_mode，列出目标的沙箱会自动使用 allow_list。

以下规则应用于 sandboxes区块：

声明 sandboxes 时，必须包含 sandboxes.agent。
如果任一沙箱声明了出口，则声明无出口的沙箱将使用 deny_all。
在顶级 network.atlas_clusters区块中而不是在沙箱内声明Atlas集群。

提示

如果您的代理文件在顶级 network区块中声明了 egress 或 egress_mode，请从您的代理项目目录运行agentengine migrate sandboxes 以将该策略移动到 sandboxes区块中。

注意

更改任何代理文件后，请重新部署代理，以使新策略生效。平台在部署时而不是运行时应用出口策略。

完全限定域名 (FQDN) 规则

该平台接受以下目的地：

主机名，例如 api.openai.com 或 storage.googleapis.com
具有一个子域级别的前导标签通配符，例如 *.example.com
具有两个子域级别的前导标签通配符，例如 *.*.example.com
匹配所有子域级别的递归通配符，例如 **.example.com。该平台还接受 **.com 等模式。

平台拒绝以下目的地：

IP字面量，例如 1.2.3.4
CIDR 范围，例如 10.0.0.0/8
localhost、*.local 和 *.svc.cluster.local*.svc.cluster.local
Cloud元数据端点，例如 *.metadata.google.internal 和 169.254.169.254
裸通配符，例如 * 和 **
非前导通配符，例如 api.*.com
包含两个以上单标签通配符的模式，例如 *.*.*.example.com
保留的后缀，例如 .arpa、.test、.example 和 .invalid

如果目标违反任何这些规则，验证将失败，并且不会应用目标。您可以运行agentengine agent validate 在本地捕获错误。平台在构建路径中应用相同的验证。错误会标明原因，例如 fqdn_ip_literal 或 fqdn_wildcard_misuse，示例：

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

每个目标支持 1 到 65535 的端口范围、每个目标最多 10 个端口以及每个工作区最多 50 个目标。

如果省略目的地的端口，平台将允许通往该目的地的所有端口并返回非阻塞警告。

注意

该平台接受Atlas 集群主机名，例如 *.mongodb.net，但在保存主机名时会返回警告，因为出口目标不会配置Atlas访问权限。要授予代理访问权限Atlas 集群的权限，请使用 agentengine atlas 命令或 agent.yaml文件中的 network.atlas_clusters区块。

使用CLI配置出口

使用代理项目目录中的 agentengine egress 命令编辑代理文件并检查已部署的策略。这些命令从不直接更改运行策略。

查看已部署的策略

要查看两个沙箱的当前策略，可以使用 agentengine egress 命令。使用 --workspace 标志查看特定工作区的策略。以下示例展示了这些命令：

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

agentengine egress 命令仅供查看。要更改基于文件的策略，请编辑 agent.yaml，或使用 agentengine agent egress add 和 agentengine agent egress remove，然后重新部署代理。

添加或删除目标

agentengine agent egress add 和 agentengine agent egress remove 命令编辑本地代理文件中每个沙箱的 network.egress区块。他们一次更改一个目的地，而列表的其余部分保持不变。使用 --component 标志来定位一个沙箱。如果省略该标志，这些命令更新两个沙箱。在部署代理之前，这些本地编辑不会更改已部署的策略。使用这些命令更改单个目标：

# 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

将不带端口的裸 FQDN 传递给 agentengine agent egress remove。部署代理后，使用 agentengine egress 命令或工作区出站访问用户用户界面查看新设置。

命令的行为如下：

如果目标沙箱位于 deny_all 中，add 会将其切换到 allow_list 并打印 mode: deny_all → allow_list。
如果目标沙箱处于 allow_all 模式，则 add 会使文件保持不变，因为目标沙箱在 allow_all模式下不起作用。要添加目标，请首先使用 agentengine agent egress mode 命令将模式设立为 allow_list。
如果 remove 删除沙箱的最后一个目标，则沙箱将返回到 deny_all 并打印 no destinations remain; mode set to deny_all。
添加完全相同的副本（即相同的 FQDN 和相同的端口）不起作用。

更新出口模式

使用 agentengine agent egress mode 在本地代理文件中设立每个沙箱的 network.egress_mode 值。使用 --component 标志来定位一个沙箱。部署代理以使这些更改生效。

以下示例展示了如何更新出口模式：

# 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

agentengine agent egress mode 命令仅编辑本地代理文件。部署代理以使更改生效。

后续步骤

要通过分步教程学习；了解如何配置网络出口，请参阅网络出口入门指南。