全部文档
当前文档
最近更新时间：2026-09-15 11:40:07
OpenKruise-Agents 面向 Kubernetes 上的 AI 智能体工作负载，提供沙箱创建、预热、申领、快照、克隆和销毁等全生命周期管理能力。通过在金山云 KCE 2.0 中部署 OpenKruise-Agents，您可以统一沙箱交付方式，并结合预热池和节点弹性伸缩，兼顾启动效率、资源利用率与运维一致性。
OpenKruise-Agents 旨在支持以下 AI 智能体工作负载：
为 AI Agent使用多样化工具提供隔离环境
为笔记研究和开发工作区提供可通过网络访问的持久化云环境
支持人类参与和开放世界训练的强化学习任务
需要快速启动和强大容错能力的大数据训练任务
产品架构如下：
Sandbox Controller、Sandbox Manager 与 Sandbox Gateway 是 OpenKruise 生态中的三大核心组件，三者共同构成完整的沙箱运行时环境：
Sandbox Controller（沙箱控制器）：管理沙箱相关的 CRD 资源，负责 SandboxSet、Sandbox、SandboxClaim、SandboxTemplate 的全生命周期管理。
Sandbox Manager（沙箱管理服务）：提供沙箱的 API 服务与控制平面，承担沙箱实例的调度、创建、回收工作，支持 E2B 协议访问。
Sandbox Gateway（0.2.0 版本新增，沙箱网关）：基于 Envoy + Golang Filter 构建的独立数据面网关服务，负责流量路由、负载均衡与熔断防护，支持独立扩缩容。
检查项 | 要求 |
KCE 集群 | 已创建 KCE 2.0 Kubernetes 集群，集群版本为 v1.34 |
Ingress | 已部署 ingress-nginx组件，并存在可用的 IngressClass |
CA证书 | 需提前将CA证书在 |
网络隔离 | 如需开启沙箱间网络隔离，集群需预先安装 NetworkPolicy 组件 |
KCE 2.0 提供两个部署入口，两者的配置项一致：
推荐入口：在【Helm3 应用】>【应用市场】中找到 openkruise-agents，单击【部署】。
备用入口：在【Helm3 应用】>【应用管理】中单击【新建】，将 Chart 来源设置为【应用市场】，再选择 openkruise-agents 及对应 Chart 版本。
所在地域：只读，展示当前操作地域。
应用名称：输入 Helm 应用名称，仅支持小写字母、数字、‑；必须小写字母开头，小写字母或数字结尾。
部署集群：下拉选择目标 KCE 集群。
所在命名空间：openkruise-agents 固定部署到 sandbox-system命名空间下，安装时系统会自动检测并按需创建。
Chart来源：选择应用来源，即应用市场。
Chart名称：选择openkruise-agents。
Chart版本：选择Chart版本，即0.3.0。
副本数：默认 2。
资源限制：
CPU：request值默认0.5核，limit值默认1核。
内存：request和limit值均默认4Gi。
sandboxWorkers：默认2000，指sandbox 工作协程数量，用于控制 sandbox 控制器的处理并发度。
sandboxsetWorkers：默认10，指sandboxSet 工作协程数量，用于控制 sandboxSet 控制器的处理并发度。
sandboxclaimWorkers：默认200，指sandboxClaim 工作协程数量，用于控制 sandboxClaim 控制器的处理并发度。
副本数：默认2。
CPU资源：默认2核。
内存资源：默认4Gi。
maxClaimWorkers：默认100，指SandboxClaim 申领任务最大并发数。
maxCreateQPS：默认200，指直接创建沙箱的最大 QPS 阈值。
extProcMaxConcurrency：默认3000，指Agent Proxy 代理连接最大并发数。
E2B 配置
域名：指对外访问的 E2B 服务域名。
E2B_API_KEY 鉴权：默认关闭。关闭后任意密钥都可通过校验，所有请求视为同一个用户。
adminApiKey：开启E2B_API_KEY 鉴权后，需填写adminApiKey管理员密钥。
Ingress 配置
IngressClass：下拉选择集群内已创建的 ingress-nginx，选中后会展示对应 LB IP。
CA 证书：下拉选择集群内已创建的 Secret。
1. 请将 E2B 域名的 DNS 解析指向选择项中展示的 LB IP，解析生效后才可正常访问。
2. 请预先将 CA 证书在sandbox-system命名空间下创建为TLS类型的 Secret 后再选择，可参考 https://docs.ksyun.com/documents/45792?type=3
sandboxGateway 配置
副本数：默认 2。
CPU资源：默认2核。
内存资源：默认4Gi。
默认关闭。如业务需要限制沙箱之间的横向访问，可开启沙箱间网络隔离，集群需预先安装 NetworkPolicy 组件，然后配套配置网络管控规则，配置示例如下：
a. 默认策略
系统默认部署的网络策略为 GlobalNetworkPolicy，这是 Calico 提供的扩展自定义资源（CRD），其核心优势是支持全局命名空间维度的管控，单条策略即可统一管理所有命名空间下携带 agents.kruise.io/created-by: "sandbox" 标签的沙箱 Pod。
apiVersion: projectcalico.org/v3
kind: GlobalNetworkPolicy
metadata:
name: sandbox-network-policy
spec:
# 通过label选中沙箱pod
selector: agents.kruise.io/created-by == "sandbox"
ingress:
# 入向放行沙箱控制面
- action: Allow
source:
selector: app.kubernetes.io/name == "agents-sandbox-controller"
- action: Allow
source:
selector: app.kubernetes.io/name == "agents-sandbox-manager"
- action: Allow
source:
selector: app.kubernetes.io/name == "sandbox-gateway"
# 出向放行coredns 53端口UDP协议与TCP协议
egress:
- action: Allow
protocol: UDP
destination:
ports: [ 53 ]
namespaceSelector: kubernetes.io/metadata.name == "kube-system"
selector: k8s-app == "kube-dns"
- action: Allow
protocol: TCP
destination:
ports: [ 53 ]
namespaceSelector: kubernetes.io/metadata.name == "kube-system"
selector: k8s-app == "kube-dns"
# 允许访问公网，限制访问保留网段
- action: Allow
destination:
nets:
- 0.0.0.0/0
notNets:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16上述默认策略实现的核心管控能力如下：
沙箱 Pod 之间默认禁止互访，实现沙箱实例的网络隔离；
沙箱 Pod 禁止访问集群内其他普通 Pod、Service 以及集群节点；
沙箱 Pod 允许访问 kube-system 命名空间下的 CoreDNS 服务的 53 端口，满足域名解析需求，但禁止访问 CoreDNS 的指标采集接口；
沙箱 Pod 默认允许访问公网地址；
沙箱 Pod 的入向访问仅对 agents-sandbox-manager 和 sandbox-gateway 组件放行。
策略匹配规则：Allow / Deny 规则按配置顺序依次匹配，命中规则后立即终止后续校验。
b. 自定义保留网段放行
由于 GlobalNetworkPolicy CRD 需通过 calicoctl 工具执行创建、更新等操作，系统已预先部署 agents-calico-gnp-apply Pod，内置 calicoctl 命令行工具，可直接用于策略配置操作。calicoctl 命令行工具与kubectl操作方式基本一致。
通过exec命令进入到agents-calico-gnp-apply Pod内
kubectl exec -n sandbox-system <pod-name> -- ash将需要更新的网络策略保存为文件
vi sandbox-network-policy.yaml若业务场景需要开放特定的内网保留网段访问权限，可在原有策略基础上新增放行规则：
apiVersion: projectcalico.org/v3
kind: GlobalNetworkPolicy
metadata:
name: sandbox-network-policy
spec:
# 通过label选中沙箱pod
selector: agents.kruise.io/created-by == "sandbox"
ingress:
# 入向放行沙箱控制面
- action: Allow
source:
selector: app.kubernetes.io/name == "agents-sandbox-controller"
- action: Allow
source:
selector: app.kubernetes.io/name == "agents-sandbox-manager"
- action: Allow
source:
selector: app.kubernetes.io/name == "sandbox-gateway"
# 出向放行coredns 53端口
egress:
- action: Allow
protocol: UDP
destination:
ports: [ 53 ]
namespaceSelector: kubernetes.io/metadata.name == "kube-system"
selector: k8s-app == "kube-dns"
- action: Allow
protocol: TCP
destination:
ports: [ 53 ]
namespaceSelector: kubernetes.io/metadata.name == "kube-system"
selector: k8s-app == "kube-dns"
# 放行部分保留网段
- action: Allow
destination:
nets:
- 10.0.10.0/24
# 允许访问公网，限制访问保留网段
- action: Allow
destination:
nets:
- 0.0.0.0/0
notNets:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16保存完成后，通过calicoctl命令应用新的网络策略
calicoctl apply -f sandbox-network-policy.yaml应用成功后，您还可以通过calicoctl查看网络策略的应用情况
calicoctl get GlobalNetworkPolicy选择 Chart 名称和版本后，可以通过编辑 values.yaml 配置完整的 Helm Values。
注：控制台提供推荐默认值，您可直接使用默认值部署，也可根据集群规模手动调参。
确认全部参数无误，点击页面底部【部署】,系统开始安装 openkruise‑agents 全套组件。
进入【应用管理】列表，点击应用右侧“更新”按钮，除应用名称、集群、命名空间、Chart 名称不可修改外，Chart 版本、组件配置参数均可修改。
进入【应用管理】列表，点击应用右侧“删除”按钮，二次弹窗确认后卸载全部组件资源。
预热池是一组预先创建完成的 Sandbox 副本，通过 SandboxSet CRD 创建管理。SandboxSet 用于批量管控多份规格一致的沙箱实例，能力类似于 Kubernetes 中管理多个 Pod 的 ReplicaSet。当业务 Agent 需要获取沙箱实例时，可直接从预热池申领就绪实例，实现沙箱秒级交付，大幅降低沙箱启动耗时。
以下是一个创建demo沙箱预热池的示例：
动态存储挂载要求容器镜像内置 envd 服务，且监听默认端口 49983；sandbox‑manager 通过 http://<PodIP>:49983 调用 envd 执行挂载，端口修改会造成挂载异常。
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
name: demo
namespace: default
spec:
# 预热池的大小，建议比预估的请求突发量略大
replicas: 10
# 创建的沙箱在休眠、唤醒过程中需要保留的内容
persistentContents:
- ip
# Sandbox 模板，与 Sandbox CRD 一致
template:
# 为最终创建的 Pod 添加元数据
metadata:
annotations:
foo: bar
# 最终创建的 Pod Spec
spec:
containers:
- name: <CONTAINER-NAME>
image: <YOUR-IMAGE-NAME>您可通过kubectl命令查询预热池运行状态，SandboxSet资源简写为sbs；其中AVAILABLE字段代表已经就绪、可对外申领使用的沙箱实例数量。
$ kubectl get sbs -n default
NAME REPLICAS AVAILABLE UPDATEREVISION AGE
demo 10 10 78dd8599cf 19m方式一：通过E2B SDK 创建沙箱
E2B 为开源沙箱 SDK，提供 Python、JavaScript 客户端，方便开发者以编程方式操作沙箱。OpenKruise‑Agents 的sandbox‑manager组件兼容 E2B 原生协议，可直接对接 E2B SDK 实现沙箱的获取、执行命令、文件读写等全量操作。
以下是一个Python SDK 示例，从名称为demo的预热池申领沙箱：
from e2b_code_interpreter import Sandbox
with Sandbox.create(template="demo") as sbx:
print(sbx.get_info())方式二：通过 SandboxClaim 创建沙箱
SandboxClaim 采用声明式方式申领沙箱资源，会从同一命名空间下指定的SandboxSet预热池中分配可用沙箱实例。申领示例如下：
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
name: demo-sandbox-claim
namespace: default
spec:
templateName: demo # SandboxSet nameSandboxClaim资源简写为sbc，可执行如下命令查看申领进度：
$ kubectl get sbc
NAME PHASE TEMPLATE DESIRED CLAIMED AGE
demo-sandbox-claim Completed demo 1 1 41s当PHASE状态变更为Completed，代表沙箱申领完成。可通过标签筛选出本次申领分配到的 Sandbox 资源进行后续业务调用：
$ kubectl get sandbox -l agents.kruise.io/claim-name=demo-sandbox-claim # short name of Sandbox
NAME STATUS AGE SHUTDOWN_TIME PAUSE_TIME MESSAGE
demo Running 20m 方式三：通过 SandboxClaim 批量创建沙箱
您可配置replicas参数，支持一次性批量申领多份沙箱实例，同时支持申领超时、资源自动清理配置：
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
name: demo-sandbox-claim
namespace: default
spec:
templateName: demo
# Number of sandboxes to claim (default: 1)
replicas: 10
# Optional: Claim timeout (default: 1m)
claimTimeout: 1m
# Optional: TTL after completion (auto-delete SandboxClaim resource)
# The claimed sandboxes will NOT be deleted
ttlAfterCompleted: 5m方式四：以预热池为模版直接创建沙箱
默认场景下，如果预热池没有空闲就绪沙箱，申领请求会阻塞等待预热池补齐实例。若业务不希望等待预热池补全，可开启createOnNoStock，当预热池库存耗尽时直接新建沙箱实例，跳过等待逻辑。
1）使用 SandboxClaim 方式：
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
name: demo-sandbox-claim
namespace: default
spec:
templateName: demo
createOnNoStock: true2）使用 E2B SDK 方式：
from e2b_code_interpreter import Sandbox
Sandbox.create(template="demo", metadata={
"e2b.agents.kruise.io/create-on-no-stock": "true"
})OpenKruise‑Agents 支持对运行态沙箱执行休眠操作，休眠后沙箱将停止消耗 CPU、内存计算资源；后续可重新唤醒恢复业务运行，沙箱 ID 保持不变，底层 Pod 实例不变。
休眠（Pause）：冻结沙箱 Pod 运行，已建立的 WebSocket、PTY、命令流连接会断开，客户端唤醒沙箱后需要重新建立连接。
唤醒（Resume）：将休眠的 Pod 恢复至运行状态，复用原有沙箱 ID 继续业务操作。
1）手动休眠沙箱
K8s 原生操作方式：修改 Sandbox CR spec.paused: true，控制器驱动沙箱进入休眠。
kubectl patch sandbox my-sandbox -n default --type=merge -p '{"spec":{"paused":true}}'E2B SDK 方式：底层调用POST /sandboxes/{sandboxID}/pause接口
from e2b_code_interpreter import Sandbox
with Sandbox.create(template="code-interpreter", timeout=300) as sbx:
sbx.run_code("a = 1")
sbx.pause() # 沙箱进入 paused 状态；sandboxID 保持不变2）定时自动休眠/清除
除手动休眠外，支持设置定时自动休眠，到期沙箱自动转为休眠状态，不会直接销毁，保留实例等待唤醒。
v0.3.0 版本存在已知缺陷，仅配置 pauseTime 不生效，需要同时配置 pauseTime 与 shutdownTime 两个参数，社区修复已合并 master 分支，待新版本发布。
K8s 原生操作方式：
# Sandbox示例
apiVersion: agents.kruise.io/v1alpha1
kind: Sandbox
metadata:
name: my-sandbox
namespace: default
spec:
pauseTime: "2026-05-13T10:00:00Z" # RFC3339；到期后自动进入 paused
shutdownTime: "2026-05-13T12:00:00Z"E2B SDK 方式：
from e2b_code_interpreter import Sandbox
sbx = Sandbox.create(
template="demo",
timeout=600, # 10 分钟；到期后进入 paused，而不是被删除
lifecycle={
"on_timeout": "pause",
"auto_resume": False,
},
)3）唤醒沙箱
K8s 原生操作：将spec.paused设置为false即可唤醒；支持唤醒同时修改pauseTime、shutdownTime刷新定时时间。
kubectl patch sbx my-sandbox -n default --type=merge -p '{"spec":{"paused":false}}'
# 唤醒的同时把下次自动停机时间延后 1 小时（示例）
kubectl patch sbx my-sandbox -n default --type=merge \
-p '{"spec":{"paused":false,"shutdownTime":"2026-05-13T11:00:00Z"}}'E2B SDK 方式：调用Sandbox.connect会自动唤醒处于休眠状态的沙箱。
from e2b_code_interpreter import Sandbox
sbx = Sandbox.connect(sandbox_id, timeout=300) # 如果休眠则唤醒，并刷新 timeout
sbx.run_code("print(a)")前置准备：
请务必为 kubelet 配置参数 --volume‑stats‑agg-period=-1s，以避免周期性目录扫描带来的 IO 性能抖动。
请提前在金山云控制台完成 KS3 Bucket实例创建。
沙箱主容器镜像需要以 root 用户运行，或增加如下配置：
securityContext:
runAsUser: 0
runAsGroup: 01）部署 SandboxSet，开启 CSI 存储、agent‑runtime 运行时能力：
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
name: code-interpreter
namespace: default
spec:
replicas: 2
runtimes:
- name: agent-runtime # 注入envd等环境管理工具
- name: csi # 启用CSI挂载能力
template:
metadata: {}
spec:
automountServiceAccountToken: false
terminationGracePeriodSeconds: 1
containers:
- name: sandbox
image: hub.kce.ksyun.com/ksyun/code-interpreter:latest
imagePullPolicy: Always
securityContext:
runAsUser: 0
runAsGroup: 02）创建 KS3 访问密钥 Secret，保存为secret.yaml，AK、SK 需要做 base64 编码，命名空间固定为sandbox-system，与 OpenKruise‑Agents 部署命名空间保持一致。
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: ks3-secret
namespace: sandbox-system # 需要与 openkruise-agent 安装的命名空间一致
data:
#替换为您的AKSK。
#注意：值必须使用base64编码。
akId: ********
akSecret: *******3）创建 KS3 对象存储 PV 资源，保存为ks3-pv.yaml，替换 bucket、endpoint 信息后部署。
apiVersion: v1
kind: PersistentVolume
metadata:
name: "pv-ks3"
spec:
accessModes:
- ReadWriteMany
capacity:
storage: 1Gi
csi:
driver: com.ksc.csi.ks3plugin # 驱动名称，固定为com.ksc.csi.ks3plugin
volumeHandle: pv-ks3 # 必须与PV的名称一致
volumeAttributes:
url: "http://<YOUR-Endpoint-URL>" # 替换为实际Endpoint
bucket: <YOUR-BUCKET-NAME> # 替换为实际Bucket名称
path: / # 替换为挂载点相对于Bucket根目录的路径
additional_args: "-osigv4 -oallow_other" # ks3fs挂载选项。使用签名版本4时须包含-o sigv4，建议添加-oallow_other，其他参数请参考https://docs.ksyun.com/documents/44995?type=3
nodePublishSecretRef:
name: ks3-secret
namespace: sandbox-system调用 E2B 接口申领沙箱，通过 metadata 传入 CSI 挂载配置，挂载 KS3 存储，执行查看目录测试：
import json
from e2b_code_interpreter import Sandbox
csi_config = json.dumps([
{"pvName": "pv-ks3", "mountPath": "/volumes"}, # KS3 对象存储
])
with Sandbox.create(template="code-interpreter", timeout=300, metadata={
"e2b.agents.kruise.io/csi-volume-config": csi_config,
}) as sbx:
print("sandbox:", sbx.sandbox_id)
print("=== KS3 /volumes ===")
print(sbx.commands.run("ls -la /volumes").stdout)
print(sbx.commands.run("ls /volumes").stdout)
PY沙箱实例底层为 Kubernetes Pod，K8s 调度器依据 Pod 的resources.requests完成节点调度，而不是limits。当 Pod 配置limit > request时，调度器只保障节点上所有 Pod 的requests总和不超过节点可分配资源；全部 Pod 的limits总和可以大于节点物理资源上限，即节点资源超卖。
业务并发流量冲高，大量 Pod 同时达到 limit 上限时，节点物理资源耗尽，会触发 CPU 节流、内存 OOM、kubelet 驱逐 Pod 等异常现象。
示例：节点分配规格为 4 核 CPU / 8GiB 内存；预热池 SandboxSet 配置如下：
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxSet
metadata:
name: demo
namespace: default
spec:
replicas: 8
template:
spec:
containers:
- name: nginx
image: nginx:alpine
resources:
requests: # 调度依据
cpu: 500m # 0.5 核
memory: 1Gi
limits: # 运行上限
cpu: 2000m # 2 核
memory: 4Gi可调度实例数：CPU 4 / 0.5 =8；内存 8 /1 =8，节点最多调度 8 个沙箱实例。
峰值 limit 累加：CPU 总和 8*2=16核（超卖 4 倍）；内存总和8*4=32GiB（超卖 4 倍）。
纯净模式