使用云原生 API 网关管理和访问 ACS Agent Sandbox-API 网关(API Gateway)-阿里云帮助中心

本文介绍如何在 ACS 集群中使用云原生 API 网关 Ingress 作为流量入口，对 ACS Agent Sandbox（沙箱）进行管理和访问。

Agent Sandbox 是 ACS 提供的面向 AI Agent 的隔离运行环境，更多介绍请参见 Agent Sandbox。用户可以通过 SandboxSet 创建预热池，通过 SandboxClaim 或 E2B SDK 获取 Sandbox，再通过 ack-sandbox-manager 暴露的入口访问 Sandbox 内的运行时服务。

方案说明

ACS Agent Sandbox 通过 ack-sandbox-manager 自动创建的 Ingress 对外暴露两类入口：

Sandbox 管理入口：通过 Ingress 暴露 E2B API 和管理 API，支持创建、连接、领取、释放 Sandbox 等生命周期管理操作。
Sandbox 访问入口：通过 Ingress 暴露 Sandbox 数据面 API，将用户请求路由到指定 Sandbox 实例，用于执行代码、访问运行时服务等沙箱操作。

本文通过将该 Ingress 的 className 配置为 apig，由云原生 API 网关 Ingress 承接上述 Sandbox 管理和访问流量。

关于 Agent Sandbox 组件安装、SandboxSet 预热池、E2B SDK 接入和生产环境域名证书配置的完整说明，请参见创建Agent Sandbox。

组件与网关安装

安装 APIG Controller。进入 ACS 控制台，选择目标集群，单击组件管理，搜索 apig controller 并单击安装。安装完成后，系统会自动创建云原生 API 网关监听该集群中的 Ingress 资源。
安装 ack-agent-sandbox-controller 组件。在 ACS 集群控制台进入目标集群的组件管理页面，搜索 ack-agent-sandbox-controller，单击安装。

首次安装需要先授权 AliyunCSManagedAgentSandboxRole 角色访问您的云资源。参数可先按照默认设置；如有额外并发需求，可再提升对应资源规格。

关于该组件功能的详细说明，请参见 ack-agent-sandbox-controller。

安装 ack-sandbox-manager 组件。在 ACS 集群控制台进入目标集群的组件管理页面，搜索 ack-sandbox-manager，单击安装。该组件会在 sandbox-system 命名空间中创建 sandbox-manager Ingress，用于对外暴露 Sandbox 管理入口和 Sandbox 访问入口。

安装时根据访问方式选择 HTTP 模式或 HTTPS 模式，未提到的资源规格、并发、日志等参数保持默认即可。

HTTP 模式适合快速联调入口链路，不需要准备证书。

参数	建议值	说明
`e2b.domain`	用户访问云原生 API 网关的域名	访问 ACS Sandbox 的实际域名，例如 `your.domain.com`。Demo 可使用临时域名；生产环境请替换为真实域名。
`ingress.className`	`apig`	指定由云原生 API 网关 Ingress 处理组件自动创建的 Ingress。
`ingress.tls`	`false`	关闭 Ingress TLS。
Enable E2B_API_KEY authentication	Demo 可关闭，生产按需开启	关闭后任意 API Key 都会被接受，仅建议在临时 Demo 环境使用。
`e2b.adminApiKey`	自定义 API Key	开启鉴权时使用的初始 API Key，例如 `1234567890987654321`。

HTTPS 模式适合验证 TLS 入口能力，需要在安装组件后创建 TLS Secret。

参数	建议值	说明
`e2b.domain`	用户访问云原生 API 网关的域名	访问 ACS Sandbox 的实际域名，例如 `your.domain.com`。Demo 可使用临时域名；生产环境请替换为真实域名。
`ingress.className`	`apig`	指定由云原生 API 网关 Ingress 处理组件自动创建的 Ingress。
`ingress.tls`	`true`	开启 Ingress TLS。
TLS Secret	`sandbox-system/sandbox-manager-tls`	安装页通常不需要填写该字段。开启 TLS 后，按该名称创建证书 Secret。
Enable E2B_API_KEY authentication	Demo 可关闭，生产按需开启	关闭后任意 API Key 都会被接受，仅建议在临时 Demo 环境使用。
`e2b.adminApiKey`	自定义 API Key	开启鉴权时使用的初始 API Key，例如 `1234567890987654321`。

连通性验证

完成上述组件安装和配置后，可以通过云原生 API 网关作为沙箱流量入口，验证 Sandbox 管理入口是否可用。

前往 APIG 控制台，在网关实例的概览 > 接入点 > 访问域名及 IP 中获取 APIG 接入端点：

APIG_ENDPOINT=<APIG 接入端点>

测试环境可通过 APIG 接入端点和 Host Header 访问：

curl -sS -i \
  -H "Host: your.domain.com" \
  "http://${APIG_ENDPOINT}/kruise/api/templates"

返回 200 OK 表示可以通过云原生 API 网关访问 ACS Sandbox 管理入口。本文示例使用 your.domain.com 作为安装 ack-sandbox-manager 时填写的 e2b.domain，实际使用时请替换为自己的域名。如果已经配置好域名解析，也可以直接通过对应域名访问。

实操指南

准备 Sandbox 模板

Sandbox 模板由集群内的 SandboxSet 提供。创建 SandboxSet 后，ack-sandbox-manager 会监听该资源，并将其同步为管理 API 中可查询和使用的模板。以下示例创建名为 code-interpreter 的 Sandbox 模板和预热池，可通过 kubectl、控制台 YAML 等方式部署。

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
  name: code-interpreter
  namespace: default
spec:
  runtimes:
    - name: csi
    - name: agent-runtime
  replicas: 1
  template:
    metadata:
      labels:
        alibabacloud.com/acs: "true"
        alibabacloud.com/compute-class: agent-sandbox
        alibabacloud.com/compute-qos: default
    spec:
      automountServiceAccountToken: false
      containers:
        - name: sandbox
          image: registry-cn-hangzhou-vpc.ack.aliyuncs.com/acs/code-interpreter:v1.6
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: "1"
              memory: 1Gi
              ephemeral-storage: 30Gi
      terminationGracePeriodSeconds: 30

创建 Sandbox

通过云原生 API 网关调用 ack-sandbox-manager 管理 API 创建 Sandbox。以下示例使用上一步创建并同步到 ack-sandbox-manager 的 code-interpreter 模板。

执行以下命令，查看当前可用的 Sandbox 模板：

curl -sS \
  -H "Host: your.domain.com" \
  "http://${APIG_ENDPOINT}/kruise/api/templates"

返回内容中包含 code-interpreter 后，执行以下命令创建 Sandbox：

curl -sS \
  -H "Host: your.domain.com" \
  -H "content-type: application/json" \
  -d '{"templateID":"code-interpreter"}' \
  "http://${APIG_ENDPOINT}/kruise/api/sandboxes"

从返回结果中记录 sandboxID，后续访问和删除 Sandbox 时会用到该 ID。如果安装 ack-sandbox-manager 时开启了 API Key 鉴权，请在上述请求中增加 X-API-Key: <adminApiKey> Header。

访问 Sandbox

使用创建 Sandbox 时返回的 SANDBOX_ID 访问 Sandbox。

SANDBOX_ID=<创建 Sandbox 时返回的 sandboxID>

执行以下命令，访问 Sandbox 内的健康检查接口：

curl -sS -i \
  -H "Host: your.domain.com" \
  -H "e2b-sandbox-id: ${SANDBOX_ID}" \
  -H "e2b-sandbox-port: 49999" \
  "http://${APIG_ENDPOINT}/health"

执行以下命令，在 Sandbox 中执行代码：

curl -sS -i \
  -H "Host: your.domain.com" \
  -H "e2b-sandbox-id: ${SANDBOX_ID}" \
  -H "e2b-sandbox-port: 49999" \
  -H "content-type: application/json" \
  -d '{"code":"print(\"hello from apig\")"}' \
  "http://${APIG_ENDPOINT}/execute"

返回 200 OK，且响应中包含 hello from apig，表示代码执行成功。

删除 Sandbox

如果不再使用 Sandbox，可通过云原生 API 网关调用管理 API 删除 Sandbox。

SANDBOX_ID=<创建 Sandbox 时返回的 sandboxID>

curl -sS -i -X DELETE \
  -H "Host: your.domain.com" \
  "http://${APIG_ENDPOINT}/kruise/api/sandboxes/${SANDBOX_ID}"

返回 204 No Content 表示删除请求已被管理 API 接受。删除后再次访问该 Sandbox 通常会返回 502 和 API Error: healthy sandbox ... not found，表示网关已无法继续路由到该 Sandbox。

删除是异步清理，短时间内 Sandbox 资源可能仍在后台释放；这不影响网关侧已经停止转发到该 Sandbox。

证书绑定

如果安装 ack-sandbox-manager 时选择 HTTPS 访问方式，即设置 ingress.tls=true，需要为访问 ACS Sandbox 的域名创建证书，并在 sandbox-system 命名空间中创建 TLS Secret。

本节仅提供 Demo 环境的自签名证书创建方式。生产环境中域名解析、证书申请、证书更新等更完整的配置方式，请参见应用于生产环境中的“应用于生产环境”。

以下示例为 your.domain.com 创建自签名证书：

DEMO_DOMAIN=your.domain.com
TMP_DIR=$(mktemp -d)

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \
  -subj "/CN=${DEMO_DOMAIN}" \
  -addext "subjectAltName=DNS:${DEMO_DOMAIN},DNS:*.${DEMO_DOMAIN}" \
  -keyout "${TMP_DIR}/privkey.pem" \
  -out "${TMP_DIR}/fullchain.pem"

kubectl -n sandbox-system create secret tls sandbox-manager-tls \
  --cert="${TMP_DIR}/fullchain.pem" \
  --key="${TMP_DIR}/privkey.pem" \
  --dry-run=client -o yaml | kubectl apply -f -

生产环境请将自签名证书替换为真实证书，并将正式域名和通配符子域解析到云原生 API 网关入口地址。

测试环境可以使用 APIG 接入端点临时验证 HTTPS 入口：

curl -k -sS -i \
  --connect-to "your.domain.com:443:${APIG_ENDPOINT}:443" \
  "https://your.domain.com/kruise/api/templates"

如果已经完成域名解析配置，可以直接访问域名：

curl -k -sS -i "https://your.domain.com/kruise/api/templates"