Overview
ネットワーク Egress ポリシーは、エージェントのランタイム ポッドが到達できる外部ホストを制御します。 Egress ポリシーはエージェントファイル内で宣言され、エージェントを配置するときに適用されます。すべてのワークスペースは deny_allモードで起動します。つまり、ランタイムでは Atlas Agent Engine の基本ポリシーを超えるアウトバウンド接続は許可されません。このガイドでは、エージェントが必要とする宛先を宣言し、アウトバウンド アクセスポリシーを設定する方法を学習します。エージェントファイルの sandboxes ブロックで、各サンドボックスに両方を構成します。
各サンドボックスの Egress ポリシーには、network.egress で宣言する宛先と、network.egress_mode によって設定された Egressモードの2 つの部分があります。モードは、プラットフォームがそれらの宛先（allow_list、deny_all、または allow_all）を強制する方法を決定します。
基本ポリシーでは、次の宛先へのアウトバウンド トラフィックは常に許可されます。
DNS
同じ名前空間内のサービス
ワークスペースにリンクされた Atlas クラスター
基本ポリシーはこれらの宛先をカバーしているため、Egress の宛先としては追加しません。
Tip
Atlas クラスターをワークスペースにリンクする方法については、「 ネットワーク Egress 用の Atlas クラスターのリンク 」ガイドを参照してください。
Egress ポリシーは、次の方法で管理します。
最初の配置の前に、エージェントファイルはEgress ポリシーを宣言する必要があります。
agent.yamlファイル内のsandboxes.agent.networkとsandboxes.tool.networkの下に各サンドボックスのポリシーを宣言します。egressブロックには宛先が一覧表示され、egress_modeにはモードが設定されます。エージェントを配置して Egress ポリシーを適用します。配置には
Project Ownerロールが必要です。最初の配置後に Egress ポリシーを更新できます。
agentengine agent egress addとagentengine agent egress removeを使用して各サンドボックスのnetwork.egressブロックを編集し、agentengine agent egress modeを使用してそのnetwork.egress_modeを設定します。これらの変更を有効にするには、エージェントを再配置します。現在配置されているポリシーを検査するには、
agentengine egressまたはワークスペースのアウトバウンド アクセスUI を使用します。これらのビューでは、ポリシーは編集されません。
注意
Atlas Agent Engine は、Atlas 外の宛先に対して次の Egress IPアドレスを使用します。
34.196.57.8554.227.181.25
エージェントがSales force などの外部サービスを呼び出す場合、外部サービスの許可リストにはこれらのアドレスを含める必要があります。
前提条件
始める前に、次の前提条件を満たしていることを確認してください。
agentengine auth loginコマンドを使用してプラットフォームで認証できます。エージェントを配置し、Egress ポリシーの変更を適用するには、プロジェクト オーナーのロールが必要です。
Egress ポリシーの仕組み
次のセクションでは、Egress ポリシーを構成するサンドボックス、モード、および動作について説明します。
Sandboxes
Egress はサンドボックスごとにスコープ設定されています。エージェントサンドボックスと ツール サンドボックスは個別に制御します。
Sandbox | 説明 |
|---|---|
| エージェントサンドボックス。メインエージェントプロセス。 |
| ツール サンドボックス。ツール サンドボックスで実行するように構成したツールを実行します。デフォルトでは 、ツールはエージェントサンドボックスで実行されます。 |
agent.yaml では、sandboxes.agent.network または sandboxes.tool.network の下で各サンドボックスのポリシーを宣言します。 CLI コマンドの場合は、--component agent または --component tool を使用します。
同じサンドボックス内のツールは、そのサンドボックスに許可するすべての Egress 宛先にアクセスできます。サンドボックスがツール間でシークレットとネットワークアクセスを共有する方法については、 「 MongoDB Atlasエージェントエンジンの制限 」を参照してください。
モード
各サンドボックスは次のいずれかのモードで動作します。このモードは、エージェントファイルのサンドボックスの network.egress_modeフィールドで設定します。
モード | 動作 |
|---|---|
| ロックします。プラットフォームベース ポリシーのみがアクティブです。ユーザー定義の宛先にはアクセスできません。 |
| プラットフォーム 基本ポリシーは有効であり、 |
| 開きます。ランタイムは、基本ポリシーに加えて、任意のホストへのアウトバウンド トラフィックを許可します。 |
同じサンドボックスの宛先リストと allow_all を組み合わせることはできません。宛先も一覧表示するサンドボックスに allow_all を設定すると、エージェントファイルの検証は失敗します。
配置による Egress ポリシーの適用方法
agent.yamlファイルは、配置時に適用される Egress ポリシーの真実のソースです。最初に配置する前に、サンドボックスに network.egress_mode を設定して、ファイルで Egress ポリシーを宣言します。 allow_list の場合は、network.egress でも宛先を宣言します。ファイルにEgress ポリシーが宣言されていない場合、配置は拒否されます。
配置すると、プラットフォームはワークスペースにポリシーを適用します。ファイルで宣言されたモードは、サンドボックスの既存のモードよりも優先されます。
配置後、適用された設定を表示するには、agentengine egress またはワークスペースのアウトバウンド アクセスUIを使用します。
注意
エージェントでMCP サーバーを使用する場合は、各サーバーのホスト名が、サーバーを呼び出すサンドボックスの network.egress ブロックに表示されていることを確認します。 mcp.servers ブロックの下にサーバーを一覧表示しても、単独ではアウトバウンド アクセスは開かれません。
ロールベースのアクセス制御
アクセスを指定するには、RBAC（Role-Based Access Control、ロールベースのアクセス制御）を使用できます。 Egress 操作には次のロールが必要です。
操作 | 必要なロール |
|---|---|
配置された Egress ポリシー（ | プロジェクト メンバー（読み取り） |
ローカルエージェントファイルで Egress ポリシーを編集する（ | ローカルで必要なロールはありません |
エージェントを配置してファイルの Egress ポリシーを適用する | プロジェクトオーナー |
プロジェクト メンバー（読み取り）ロールを持つユーザーは、配置されたポリシーを検査できます。ローカルエージェントファイルを編集する場合はロールは必要ありませんが、これらの変更を適用するためにエージェントを配置するにはプロジェクト オーナーのロールが必要です。
エージェント ファイルでの Egress ポリシーの設定
エージェントファイルの sandboxes.agent と sandboxes.tool の下の network ブロック内の各サンドボックスの Egress ポリシーを構成します。エージェントファイルへの変更は、エージェントを配置した後にのみ有効になります。
サンドボックスの 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を含める必要があります。いずれかのサンドボックスが Egress を宣言している場合、Egress を宣言していないサンドボックスは
deny_allを使用します。サンドボックス内ではなく、最上位の
network.atlas_clustersブロックで Atlas クラスターを宣言します。
Tip
エージェントファイルが最上位の network ブロックで egress または egress_mode を宣言している場合は、エージェントのプロジェクトディレクトリから agentengine migrate sandboxes を実行して、ポリシーを sandboxes ブロックに移動します。
注意
新しいポリシーを有効にするには、エージェントファイルを変更した後にエージェントを再配置します。プラットフォームは、実行時ではなく配置時に Egress ポリシーを適用します。
完全修飾ドメイン名（FQDN）のルール
プラットフォームは次の宛先を受け入れています。
ホスト名（
api.openai.com、storage.googleapis.comなど）などの 1 つのサブドメイン レベルを持つリーディング ラベルのワイルドカード
*.example.com2 つのサブドメイン レベルを持つリージョン ラベルのワイルドカード（例:
*.*.example.comすべてのサブドメイン レベルに一致する再帰ワイルドカード（
**.example.comなど）。このプラットフォームは**.comなどのパターンも受け入れます。
プラットフォームは、次の宛先を拒否します。
IPリテラル（例:
1.2.3.4CIDR 範囲（例:
10.0.0.0/8localhost、*.localや*.svc.cluster.localクラウドメタデータエンドポイント（
*.metadata.google.internalや169.254.169.254など）ベア ワイルドカード（
*や**など）先頭にないワイルドカード（例:
api.*.com2 つ以上の単一ラベルのワイルドカードを持つパターン（例:
*.*.*.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 の宛先をサポートしています。
宛先のポートを省略すると、プラットフォームはその宛先へのすべてのポートを許可し、非ブロッキング警告を返します。
注意
プラットフォームは、*.mongodb.netなどの Atlas クラスターのホスト名を受け入れますが、保存すると警告が返されます。Egress 先では Atlas アクセスが構成されていないためです。エージェントに Atlas クラスターへのアクセスを許可するには、agentengine atlas コマンドまたは agent.yamlファイルの network.atlas_clusters ブロックを使用します。
CLI を使用した Egress の構成
エージェントのプロジェクトディレクトリから 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 ブロックを編集します。一度に 1 つの目的地を変更し、リストの残りの部分は変更されません。 1 つのサンドボックスをターゲットにするには、--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 コマンドまたはワークスペースのアウトバウンド アクセスUIを使用して新しい設定を表示します。
コマンドは、次のように動作します。
ターゲット サンドボックスが
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 と同じポートを追加しても効果はありません。
Egress モードを更新する
agentengine agent egress mode を使用して、ローカルエージェントファイルで各サンドボックスの network.egress_mode 値を設定します。 1 つのサンドボックスをターゲットにするには、--component フラグを使用します。これらの変更を有効にするには、エージェントを配置します。
次の例は、 Egressモードを更新する方法を示しています。
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 コマンドはローカルエージェントファイルのみを編集します。変更を有効にするには、エージェントを配置します。
次のステップ
ステップ付きチュートリアルでネットワーク Egress を構成する方法については、「 ネットワーク Egress を使い始める 」ガイドを参照してください。