API 网关支持对接 VCI Agent Sandbox，将容器集群 VCI 实例下的 Agent Sandbox Pod 抽象为一个 Upstream，作为网关的路由后端。适用于业务采用 Agent Sandbox 部署，希望通过网关按 Sandbox ID 动态发布业务的场景。本文为您介绍如何通过 API 网关访问 VCI Agent Sandbox 。

说明

本文提供 Agent Sandbox 数据面转发（比如转发请求到 Sandbox 内执行），如果 Agent Sandbox 的控制面转发（比如创建 Sandbox 等）也需要接入 API 网关，请参见创建容器服务类型 Upstream。

## 前提条件 * 已创建 VCI 业务所需的集群且已安装 VCI Agent Sandbox。详细操作，请参见 [在 VPC-CNI 网络模型集群中使用 VCI](https://www.volcengine.com/docs/6460/76916)、[在 Flannel 网络模型集群中使用 VCI](https://www.volcengine.com/docs/6460/1248912) 和 [安装指南](https://docs.volcengine.com/docs/6460/2277052?lang=zh#pZGIXGfo)。 * 已创建 API 网关实例，具体操作可参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。因 API 网关实例 IP 在实例升级或者重启时会发生变化，暂时无法固定，当 VCI Agent Sandbox 启用 Network Policy 对出入向网络限制时，建议您创建 API 网关实例选择较小的子网地址空间（避免 IP 浪费和过渡放权），同时在 Network Policy 网络配置中放行 API 网关实例的子网。参考配置如下，关于 Network Policy 更多说明，请参见 [使用 NetworkPolicy 实现网络访问控制](https://docs.volcengine.com/docs/6460/1111493?lang=zh)。 ```YAML apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-ingress-from-cidr namespace: default spec: podSelector: matchLabels: app: web # 匹配标签 app = web 的 Pod（被访问对象） policyTypes: - Ingress # 管控入站流量 ingress: - from: - ipBlock: cidr: 192.**.**.**/** # 允许来源网段，尽可能小，配置为 APIG 实例子网 # 如需排除段可以加 except: # except: # - 192.**.**.**/** ports: - protocol: TCP port: 49983 # envd 端口 - protocol: TCP port: 49999 # code interpreter 端口 ``` ## 使用限制 API 网关实例与容器服务集群必须处于同一 VPC 下。 ## 操作步骤 ### 步骤一：导入 Agent Sandbox 所在容器集群 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 2. 在顶部导航栏，选择目标地域。 3. 在 **实例管理** 下拉框选择目标实例后，单击 **容器集群导入**。 4. 在集群列表页面，单击 **导入集群**。 5. 在导入集群页面，按要求配置信息。详情请参见 [导入容器集群](https://www.volcengine.com/docs/6569/133830)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_eccb0c4edd7f96c90f3397ef4b4e3b4b.png) |配置项 |说明 | |---|---| |K8S 集群 |选择具体要对接的集群。本示例选择已有集群 **smart\-llm\-router**。

说明

仅支持选择与网关实例处于同一 VPC 下的集群。

仅支持选择状态为运行中的集群。

对于 Flannel 集群，所选集群的 Pod CIDR 必须与创建网关实例时选择的 Pod CIDR 网段一致。

| |路由同步 |配置是否开启路由同步功能。

开启路由同步后，API 网关会自动监听容器的路由规则 Ingress 资源的变化，并生效 Ingress 资源中的相关配置，将 Ingress 资源转义为服务、自定义域名、路由、Upstream 等资源合并至当前网关。详细介绍请参见 [Ingress 路由同步](https://www.volcengine.com/docs/6569/1121950)。 | 6. 单击 **确定**，完成集群导入。 ### 步骤二：创建 VCI Agent Sandbox 类型 Upstream 1. 在左侧导航栏单击 **Upstream 列表**。 2. 在 Upstream 列表页面，单击 **创建 Upstream**。 3. 在创建 Upstream 页面，按要求填写参数信息。 * **基本信息** |配置项 |说明 | |---|---| |Upstream 名称 |自定义 Upstream 名称，同一实例下的 Upstream 名称唯一。本示例配置为 **agent\-sandbox**。 | ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_31832a1fa55b09e6d3801dc589659ba4.png) * **后端配置** |配置项 |说明 | |---|---| |后端服务 |选择 Upstream 对接的后端服务类型。本示例选择 **VCI Agent Sandbox**。 | |监听范围 |配置监听范围。

* **全部 Sandbox**：覆盖所选集群内全部 Sandbox。

* **按 Label 选择**：需输入 Sandbox Label 的 Key 与 Value，支持 **使用表格编辑** 和 **使用 JSON 格式编辑**。 | 4. 单击 **确定**，完成配置。 ### 步骤三：创建服务 1. 在左侧导航栏单击 ** 服务列表（域名）** 。在服务列表页面，单击 **创建服务**。 2. 在创建服务对话框，设置服务参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_94cf2e1feee9760cab8939ebd5383d36.png) |配置项 |说明 | |---|---| |所属实例 |服务属于实例级别的资源。 | |服务名称 |自定义服务名称。同一实例下服务名称唯一。本示例配置为 **agent\-sandbox\-service**。 | |备注 |输入备注信息。 | 3. 单击 **确定**，完成创建服务。 ### 步骤四：创建路由 1. 在左侧导航栏选择 **服务列表（域名）** ，在服务列表页面，单击目标服务 **操作** 列下的 **创建路由**。 2. 在 **创建路由 ** 页面，配置路由信息。此处仅列出 Upsteam 流量分发配置，详情请参见 [创建路由](https://docs.volcengine.com/docs/6569/179038?lang=zh)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c94ed87bd282e744fb2b03e0a74a127b.png) |配置项 |说明 | |---|---| |后端类型 |选择接入的 Upstream 类型。本示例选择 **VCI Agent Sandbox**。 | |选择 Upstream |选择具体要对接的 Upstream。选择创建的 ** ** VCI Agent Sandbox 类型的 Upstream。 | |权重 |配置当前 Upstream 的流量权重。整数形式，取值范围为 1～1000。

说明

系统会根据 Upstream 配置的权重总值和各 Upstream 的权重占比，按比例显示流量划分，百分比数字精确到两位小数。

| 3. 单击 **确定**，完成路由创建。 ### 步骤五：获取服务默认域名进行 SDK 引用 1. 在左侧导航栏单击 ** 服务列表（域名）** 。 3. 单击目标服务名称，在 **服务概述** 页签获取访问域名。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c4bb8ac621b7eadb939c94df01fe95d5.png) 4. 在客户端引用 SDK 时增加以下环境变量，其中的域名替换为获取的服务默认域名。详情请参见 [SDK 开发指南](https://docs.volcengine.com/docs/6460/2479109?lang=zh#4oWPWiWQ)。 ```Python os.environ["E2B_SANDBOX_URL"] = "s****.apigateway-cn-beijing.volceapi.com" ``` ## 结果验证结果验证前您需要创建模版，具体操作请参见 [创建模版](https://docs.volcengine.com/docs/6460/2479108?lang=zh#ONuXBkTU)。 1. 创建`sandbox_demo.py`文件，内容如下。本示例`run_sandbox_demo`函数的入参值为`default--code-interpreter-template`，其中`default`为容器服务集群中的命名空间，`code-interpreter-template`为模版名称。 ```Python import os from e2b_code_interpreter import Sandbox # 火山引擎API网关环境变量配置 os.environ["E2B_API_KEY"] = "c03****" os.environ["E2B_API_URL"] = "http://suq****.apigateway-cn-beijing.volceapi.com"# 控制面 API 网关根据实际情况配置，不强依赖 APIG os.environ["E2B_SANDBOX_URL"] = "http://sih8****.apigateway-cn-beijing.volceapi.com" def run_sandbox_demo(template_name: str): sandbox = None try: print("开始创建沙盒实例") sandbox = Sandbox.create( template=template_name, ) print(f"沙盒信息：{sandbox.get_info()}") print("执行shell命令：echo hello from sandbox") result = sandbox.commands.run("echo hello from sandbox") print("标准输出：", result.stdout.strip()) except Exception as e: print(f"沙盒运行异常：{e}") finally: if sandbox is not None: print("销毁沙盒资源") sandbox.kill() if __name__ == "__main__": run_sandbox_demo("default--code-interpreter-template")# 此处入参格式为 {容器服务集群中的命名空间}--{模板名称} ``` 2. 进入文件所在路径执行如下命令。 ```Bash python sandbox_demo.py ``` 预期返回结果如下： ```Bash 开始创建沙盒实例沙盒信息:SandboxInfo(sandbox_id='default--sbx-19****', template_id='default--code-interpreter-template', name='', 'metadata={'agents.xk8s.io/controller-first-observed-at'} 执行shell命令:echo hellofrom sandbox 标准输出:hello from sandbox 销毁沙盒资源 ```