[官网](https://agent-sandbox.sigs.k8s.io) · [文档](https://agent-sandbox.sigs.k8s.io/docs/) · [DeepWiki](https://deepwiki.com/kubernetes-sigs/agent-sandbox) · [入门指南](https://agent-sandbox.sigs.k8s.io/docs/getting_started/) · [示例](examples/) · [路线图](roadmap.md) **agent-sandbox 能够轻松管理隔离的、有状态的、单例的工作负载，非常适合 AI agent 运行时等使用场景。** 本项目正在 [SIG Apps](https://github.com/kubernetes/community/tree/master/sig-apps) 的框架下开发用于 Kubernetes 的 `Sandbox` Custom Resource Definition (CRD) 和控制器。其目标是提供一种声明式、标准化的 API，用于管理那些需要长期运行、有状态、具有稳定身份的单例容器特性的工作负载，这非常类似于建立在 Kubernetes 原语之上的轻量级单容器虚拟机体验。 ## 概述 ### 核心：Sandbox `Sandbox` CRD 是 agent-sandbox 的核心。它提供了一种声明式 API，用于管理具有稳定身份和持久存储的单个有状态 Pod。对于那些不适合 Deployment 的无状态副本模型或 StatefulSet 的编号稳定模型的工作负载，这非常有用。 `Sandbox` CRD 的主要特性包括： * **稳定的身份：** 每个 Sandbox 都拥有稳定的主机名和网络身份。 * **持久存储：** 可以配置在重启后依然保留的持久存储。 * **生命周期管理：** Sandbox 控制器管理 Pod 的生命周期，包括创建、定时删除、暂停和恢复。 ### 扩展功能 `extensions` 模块提供了额外的 CRD 和控制器，它们构建在核心 `Sandbox` API 之上，以提供更高级的功能。 * `SandboxTemplate`：提供一种定义可复用模板的方法来创建 Sandbox，从而更容易管理大量相似的 Sandbox。 * `SandboxClaim`：允许用户通过模板创建 Sandbox，从而屏蔽底层 Sandbox 配置的细节。 * `SandboxWarmPool`：管理一个预热过的 Sandbox Pod 池，可以快速分配给用户，从而缩短启动新 Sandbox 所需的时间。 ## 架构 agent-sandbox 遵循 Kubernetes 控制器模式。用户创建一个 Sandbox 自定义资源，控制器负责管理底层的运行时资源。 ### 架构图 ``` flowchart TB User[User] Claim[SandboxClaim] Template[SandboxTemplate] Sandbox[Sandbox] ClaimController[Claim Controller] Controller[Sandbox Controller] Pod[Sandbox Pod] Runtime[Sandbox Runtime Environment] WarmPool[SandboxWarmPool] %% User paths User -->|creates| Sandbox User -->|creates| Claim %% Claim workflow Claim -->|references| Template Claim -->|reconciled by| ClaimController ClaimController -->|creates| Sandbox %% Pod handling ClaimController -->|adopts pod from| WarmPool Sandbox -->|reconciled by| Controller Controller -->|creates Pod if needed| Pod %% Runtime Pod --> Runtime %% Warm pool WarmPool -->|pre-warmed pods| Pod ``` ## 安装 ### 核心组件与扩展 您可以使用以下命令安装 agent-sandbox 控制器及其 CRD。 ``` # 将 "vX.Y.Z" 替换为来自 # https://github.com/kubernetes-sigs/agent-sandbox/releases export VERSION="vX.Y.Z" # 的特定版本标签（例如，"v0.1.0"） kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml # 仅安装核心组件： kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml ``` ### 安装扩展组件： 若要以编程方式与 agent-sandbox 交互，您可以使用 Python SDK。该客户端库提供了用于创建和管理沙箱的高级接口。 有关详细的安装和使用说明，请参阅 [Python SDK README](clients/python/agentic-sandbox-client/README.md)。 ## 配置 有关高级规模和并发调优（例如 API QPS 和工作线程数），请参阅 [配置指南](docs/configuration.md)。 ## 入门指南 安装控制器后，您可以通过将以下 YAML 应用到集群来创建一个简单的 Sandbox： ``` apiVersion: agents.x-k8s.io/v1alpha1 kind: Sandbox metadata: name: my-sandbox spec: podTemplate: spec: containers: - name: my-container image: ``` 这将创建一个名为 `my-sandbox` 的新 Sandbox，运行您指定的镜像。然后，您可以使用其稳定的主机名 `my-sandbox` 访问该 Sandbox。 有关更复杂的示例，包括如何使用扩展功能，请参阅 [examples/](examples/) 和 [extensions/examples/](extensions/examples/) 目录。 ## 动机 Kubernetes 擅长管理无状态的副本应用（Deployment）和稳定的、有序的有状态 Pod 集（StatefulSet）。然而，越来越需要一种抽象来处理以下用例： * **开发环境：** 为开发人员提供隔离的、持久的、可网络访问的云端环境。 * **AI Agent 运行时：** 用于执行不可信的、LLM 生成的代码的隔离环境。 * **Notebook 和研究工具：** 用于 Jupyter Notebooks 等工具的持久单容器会话。 * **有状态单 Pod 服务：** 托管需要稳定身份但无需 StatefulSet 开销的单实例应用（例如构建代理、小型数据库）。 虽然可以通过组合 StatefulSet（大小为 1）、Service 和 PersistentVolumeClaim 来近似实现这些功能，但这种方法比较繁琐，并且缺乏诸如休眠之类的专门生命周期管理。 ## 期望的 Sandbox 特性 我们的目标是让 Sandbox 保持供应商中立，支持各种运行时。主要特性包括： * **强隔离：** 支持 gVisor 或 Kata Containers 等不同运行时，以在沙箱和主机之间提供增强的安全性和隔离性，包括内核和网络隔离。这对于运行不可信代码或多租户场景至关重要。 * **深度休眠：** 将状态保存到持久存储，并可能归档 Sandbox 对象。 * **自动恢复：** 在网络连接时恢复沙箱。 * **高效持久化：** 弹性且快速配置的存储。 * **跨沙箱内存共享：** 探索在同一主机上的 Sandbox 之间共享内存的可能性，即使它们主要是非同构的。此功能取决于特定运行时，用户应选择符合其安全和性能要求的运行时。 * **丰富的身份与连接性：** 探索双重用户/沙箱身份以及无需每个沙箱对应 Service 的高效流量路由。 * **可编程：** 鼓励应用程序和 Agent 以编程方式使用 Sandbox API。 ## 路线图 当前的路线图可以在 [roadmap.md](roadmap.md) 中找到。 ## 社区、讨论、贡献与支持 这是一个社区驱动的项目，我们欢迎协作！ 了解如何在 [社区页面](http://kubernetes.io/community/) 上与 Kubernetes 社区互动。 您可以通过以下方式联系本项目的维护者： - [Slack](https://kubernetes.slack.com/messages/sig-apps) - [邮件列表](https://groups.google.com/a/kubernetes.io/g/sig-apps) 请随时开启 issue、建议功能并贡献代码！ ### 行为准则 Kubernetes 社区的参与受 [Kubernetes 行为准则](code-of-conduct.md) 约束。

标签：3D图, EVTX分析, Operator, Sandbox, SIG Apps, Singleton, Stateful, 人工智能代理, 单例模式, 子域名突变, 容器编排, 工作负载管理, 应用生命周期, 持久化存储, 控制器, 日志审计, 有状态应用, 沙箱, 稳定身份, 虚拟机体验, 轻量级VM, 逆向工具