ack-agent-sandbox-manager

更新时间:
复制为 MD 格式

ack-agent-sandbox-manager 是兼容 E2B 协议的沙箱管理 API Server 及 Agent 沙箱代理组件。本文介绍 ack-agent-sandbox-manager 组件的基本信息、使用说明和变更记录。

组件介绍

ack-agent-sandbox-manager 是兼容 E2B 协议的沙箱管理 API Server 及 Agent 沙箱代理组件,提供沙箱的创建、管理、休眠唤醒等全生命周期管理能力。

使用说明

关于 ACS Agent Sandbox 的使用方式,请参见创建Agent Sandbox

变更记录

202606

版本号

变更时间

变更内容

变更影响

v0.6.1

20260601

  • 问题修复:

    • 修复一个极小概率出现的问题。在用户调用 create 接口并且极快地断开连接时,会导致进程 Panic。

    • 修复无法通过 connect 唤醒 auto-pause sandbox 的问题。

  • 功能特性:

    • 支持 7 层出口流量控制。新增 SecurityProfile API,通过 egress-control runtime 拦截请求至 egress gateway,支持按照 HTTP 请求属性(路径、方法等)拦截请求。

    • create、connect 和 get_info 接口均支持通过 metadata e2b.agents.kruise.io/return-sandbox-ip: "true" 主动获取 Pod 的 IP。此外,可通过 list、get_info 等查询接口获取到 sandbox 信息后,从 metadata e2b.agents.kruise.io/sandbox-ip 获取到 Pod 的 IP。

    • 支持 HTTP 接入(不强制 HTTPS)。

    • create 接口支持通过 e2b.agents.kruise.io/cpu-requeste2b.agents.kruise.io/cpu-limit metadata 在创建时为沙箱配置资源限制。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.3.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

202605

版本号

变更时间

变更内容

变更影响

v0.6.0

20260515

  • 架构重构:

    • 架构升级:通过 controller-runtime 完全重构 sandbox-manager。

    • 对大量原有实现进行了优化,并完善了不完备的测试,提高了正确性。

    • 修复大量用户无感知的非严重问题。

    • 删除内部不必要的 Template Cache 与 SandboxSet Reconcile,提高 Claim 性能,降低内存消耗。

    • 重写底层的 Wait 机制,支持在复杂的情况下对 K8s 资源状态进行并发监控。

  • 功能特性:

    • 多租能力强化:新增 Teams API,支持给 API Key 设置 Team;支持通过 Team 按照 namespace 给不同的用户(key)做资源隔离;保留对原来 key 的兼容性(cluster scope 权限)。

    • Pause / Resume 优化:支持 pause / connect 接口的高并发调用;不冲突的多个请求能够合并检查工作流状态、同时返回,不会发生错误;冲突的并发请求仍然会发生错误;Resume 操作(connect)总会正确地设置 timeout,即使唤醒失败。

    • 错误信息优化:Create 方法发生错误时,会返回详细的信息以排查错误,通常不需要查看日志即可定位问题。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.3.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

202604

版本号

变更时间

变更内容

变更影响

v0.5.2

20260429

  • 功能特性:

    • 支持使用 MySQL 作为 API-KEY 的后端存储。

    • 使用 BrowserUse API 时,支持自定义 CDP 端口。

    • 支持 template 的 list / get 接口。

    • sandbox gateway 支持优雅下线(openkruise 自定义 API)。

    • checkpoint clone / resume 场景支持恢复动态存储挂载。

    • sandbox manager 新增大量 Prometheus 指标(支持沙箱大盘)。

    • sandbox manager 支持 claim 沙箱时更新 Pod label。

  • 性能优化:

    • 优化动态存储挂载性能,支持并行挂载。

  • 问题修复:

    • 修复创建 snapshot 时缺失 runtime 字段导致克隆时不注入 runtime 的问题。

    • 修复 sandbox-gateway 不支持 websocket 的问题。

    • 修复 e2b file.watch_dir 方法不可用的问题。

    • 修复 browser-use 在新版鉴权架构下不可用的问题。

    • 新版 connect 接口不会缩短处于运行状态的 sandbox 的 timeout,和 E2B 官方行为保持一致。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.2.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.5.0

20260402

  • 功能特性:

    • 新增 sandbox-gateway。

    • 支持 snapshot(checkpoint)的 List 与 Delete。

    • 所有 list 接口支持 limit + nextToken 分页。

    • api-keys 系列接口限制 admin 访问。

    • sandbox-gateway 支持域名匹配。

    • 可以通过组件配置选择使用 sandbox-manager(默认)还是新的 sandbox-gateway 做流量转发。

    • 新增基于 E2B 休眠唤醒后 CSI 存储重新挂载。

  • 性能优化:

    • 使用 memberlist 替代原有的心跳机制做副本间互相发现。

  • 问题修复:

    • Claim 中,WaitSandboxReady 阶段可以降级最多一次从 API Server 获取 Sandbox 对象,以应对 informer 同步延迟极大的场景。

    • 通过组件中心升级或调整配置时,不再导致所有 Pod 滚动重启。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.2.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

202603

版本号

变更时间

变更内容

变更影响

v0.4.3

20260323

  • 功能特性:

    • 支持创建时从 checkpoint 恢复(restore / clone)。

    • 支持通过 snapshot 接口创建 checkpoint。

    • 支持在不保留内存场景中,重新对 runtime 进行初始化。

  • 问题修复:

    • 删除 Sandbox 时,将强制刷新所有副本的 proxy 以删除对应路由项。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.4.2

20260313

  • 功能特性:

    • 支持 NAS 挂载。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.4.1

20260312

  • 功能特性:

    • 将 create-on-no-stock 默认打开,SandboxSet 预热池中无可用实例时将自动进入创建流程,可通过设置 e2b.agents.kruise.io/create-on-no-stock = "false" 显式关闭。

    • 新增扩展协议 e2b.agents.kruise.io/never-timeout:设置为 "true" 则沙箱永不过期,并且无法通过任何设置 timeout 的手段进行修改。

  • 性能优化:

    • 相对并发数的时间复杂度从 O(n) 优化到 O(1),大幅提升 claim 的性能。

    • 新增了一些 Prometheus 指标。

    • 调整 DNS Policy 为 Default,解决超大规模集群中的网络访问问题。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.4.0

20260302

  • 功能特性:

    • 【Breaking Change】去除 SandboxSet 上 e2b.agents.kruise.io/should-init-envd 的 annotation,默认自动初始化 envd。对于不需要初始化 envd 的自定义镜像,需要手动通过 skip-init-runtime 参数显式跳过初始化流程。

    • 新增以下 E2B 扩展协议:

      • e2b.agents.kruise.io/create-on-no-stock:用于在预热池中无可用实例时不等待预热池补充,直接创建一个新的 Sandbox 实例,默认为 false。

      • e2b.agents.kruise.io/wait-ready-timeout-seconds:用于指定等待 Sandbox 就绪的时间,默认 30 秒。

      • e2b.agents.kruise.io/skip-init-runtime:用于跳过运行时(envd)初始化,默认为 false。

      • e2b.agents.kruise.io/reserve-failed-sandbox:用于保留 claim 时产生的失败 Sandbox 现场,默认为 false,不保留。

      • e2b.agents.kruise.io/claim-timeout-seconds:后端进行 Sandbox Claim 操作的最长重试时间,默认一分钟。

    • 多个 namespace 中的同名 SandboxSet 现在可以作为同一个模板使用。

  • 问题修复与优化:

    • 【Breaking Change】sandbox-manager 只索引带有 label agents.kruise.io/sandbox-claimed=true 的已分配 Sandbox。存量已分配沙箱若不带有此 label,调用 CRUD 接口、pause/resume 接口将返回 404 错误。

    • 现在服务端的 Sandbox Claim 重试会在客户端断开后正确停止。

    • 大幅提高了 K8s 事件处理与索引的效率以及正确性。

    • 新增兜底的定时路由表 GC 逻辑,避免 Sandbox Delete 事件丢失导致的内存泄漏。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此版本包含 Breaking Change,升级前请仔细阅读变更内容。

202601

版本号

变更时间

变更内容

变更影响

v0.3.1

20260120

  • 功能特性:

    • 支持通过 PV 动态挂盘。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.3.0

20260113

  • 功能特性:

    • 支持 E2B 2.8.1 SDK 版本:新增 connect 接口;支持 auto_pause 模式,对应客户端 beta_create 方法;对齐 E2B timeout 时间计算行为。

    • create 接口新增扩展功能:支持创建沙箱时触发镜像原地升级;支持创建沙箱时触发 CSI 动态挂载。

    • 优化超高并发交付场景:大幅降低无效 APIServer 请求量;支持大量请求排队,提升交付成功率。

    • 添加休眠唤醒操作后副本间的强一致性状态同步。

    • 支持自定义 E2B 协议,无需依赖泛域名解析与通配符证书。

    • 去除网关鉴权,下沉鉴权逻辑到 runtime。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

202512

版本号

变更时间

变更内容

变更影响

v0.2.0

20251216

  • 功能特性与优化:

    • 重写缓存索引逻辑,大幅提高性能。

    • 基于新版缓存重构沙箱的 CRUD 逻辑,大幅减少乐观锁冲突,提高接口响应速度。

    • 新增对若干 E2B 接口与参数的兼容。

    • 添加基于 expectation 的缓存脏数据过滤,减少 informer 更新不及时导致的异常重试(针对高并发场景效果显著)。

    • 支持 Sandbox 跨 namespace,可以全集群管理 Sandbox 资源。

    • 支持自定义 E2B timeout 参数的最大值,适用于 create、timeout、connect 等接口。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。

v0.1.0

20251204

  • 功能特性:

    • 兼容 E2B 协议的沙箱管理 API Server。

    • Agent 沙箱代理。

  • 兼容版本说明:

    • 社区 OpenKruise Agents 版本 v0.1.0。

    • E2B SDK 版本 2.7.0 ~ 2.24.0。

此次升级不会对业务造成影响。