已经使用 TKE 的团队，可以继续沿用 Kubernetes 的工作负载声明、镜像发布和日常排障方式。使用 Agent 集群时，主要变化在于如何准备 Agent 运行环境、选择沙箱运行时，以及保存和复用工作文件。
本文中的“普通 TKE 集群”指用于通用容器应用的 TKE 集群。TKE 本身也可以部署 Agent 应用；Agent 集群基于 TKE，进一步集成面向代码执行、工具调用和工作区使用的能力。选择时应结合业务需要，而不是仅看应用是否使用大模型。
使用方式对比
使用环节 | 普通 TKE 集群 | Agent 集群 |
创建入口 | 在 TKE 控制台创建集群并配置节点池。 | 从 Agent Runtime 控制台创建 Agent 集群，再准备节点池。内测期间仅支持新建，不能直接纳管已有 TKE 集群。 |
工作负载管理 | 使用 Pod、Deployment、Job 等 Kubernetes 资源部署应用。 | 继续使用 Kubernetes 资源和访问工具；使用沙箱能力时，需要匹配相应运行时和节点条件。 |
执行环境 | 根据应用和节点配置选择运行环境。 | 可使用 Cube 沙箱运行时执行 Agent 代码与工具任务；需要核对 RuntimeClass、镜像架构和节点是否就绪。 |
工作文件 | 根据需求选择 CBS、CFS 等存储，通过 PVC 挂载到应用。 | AgentWorkspaces 随集群创建默认安装；仍需为业务创建工作区并配置挂载，文件不会自动转入工作区。 |
镜像启动加速 | 根据集群和镜像条件配置相应加速方案。 | 可在创建 Agent 集群时开启镜像加速并关联 TCR；配置镜像转换规则后，业务继续使用源镜像地址。 |
资源优化 | 根据节点与业务条件配置容量、伸缩及其他优化能力。 | 可结合支持的原生节点使用内存压缩、节点放大等能力；需要单独配置并验证业务影响。 |
费用 | 按实际使用的 TKE 及相关云资源计费项目计算。 |
AgentWorkspaces 相比常用 Kubernetes 存储有什么优势
对于反复读取代码、安装依赖、生成文件的 Agent，存储不仅要“文件不丢”，还要减少每轮任务重新准备工作目录的时间。AgentWorkspaces 通过节点本地缓存承接活跃工作文件，再将变化的数据提交到 COS，使同一工作区的重复访问更多在节点本地完成。
技术原理：本地处理活跃数据，远端保存持久数据
AgentWorkspaces 将 Btrfs 文件系统、节点本地块缓存和 COS 持久层组合成工作区：
1. 读取文件：应用通过挂载目录访问 Btrfs 文件系统，底层通过 NBD 块设备访问工作区数据。命中节点本地块缓存时，从本地读取；未命中时再读取远端数据并进入缓存。收益主要来自减少重复读取时的远端访问。
2. 写入文件：修改进入本地脏块路径，再通过后台增量提交持久化到 COS。增量提交避免每次都重新上传整个工作区，但应用写调用返回和数据已可跨节点恢复是两个时刻。
3. 压缩数据：Btrfs 透明压缩可以减少可压缩文件实际占用和读取的块数。文本、代码等数据可能受益，压缩包、图片等已压缩数据的收益通常较小，并且压缩本身需要 CPU。
4. 重建实例：同节点重建优先复用本地工作区运行环境和缓存。跨节点恢复使用已安全提交到远端的数据，目标节点的冷缓存仍需重新建立。
因此，AgentWorkspaces 更适合“一个工作区反复使用、工作集具有局部性”的任务。节点本地缓存不是备份；停止或迁移前仍需确认数据完成远端持久化。
不同存储路径对业务的影响
维度 | CBS 云硬盘 | CFS 文件存储 | AgentWorkspaces |
访问路径 | 应用经文件系统访问云硬盘块设备，性能与云盘规格及缓存有关。 | 应用经网络文件系统访问共享文件，性能与服务规格、网络和缓存有关。 | 应用经文件系统访问工作区块设备；热数据优先命中节点本地块缓存，COS 承接远端持久化。 |
典型需求 | 持久块存储，按应用选择容量、IOPS 和吞吐规格。 | 多节点共享文件目录。 | 为用户或任务保留独立工作区，反复读写代码、资料和结果。 |
实例重建 | 可挂载原卷；跨节点需满足卷的挂载与拓扑条件。 | 可重新挂载原共享目录。 | 同节点可复用原工作区及本地缓存，减少重复准备工作文件。 |
节点切换 | 需考虑卷卸载、挂载和可用区等条件。 | 需考虑目标节点网络及挂载条件。 | 需等待旧写入方退出、数据安全提交，再在目标节点恢复；不能将同节点热缓存速度套用到跨节点恢复。 |
选择重点 | 云盘规格、持久写入要求和访问模式。 | 共享访问、并发读写及文件系统语义。 | 工作集缓存命中、文件复用和持久化交接；本文采用单写入方使用方式。 |
Cube 运行时相比普通容器运行时有什么优势
本文以普通 TKE 中常见的 containerd 配合 runc 为对照。containerd 负责容器生命周期管理，runc 执行容器；使用 Cube 后仍沿用 Kubernetes 和 containerd 接入，由 Cube 为 Pod 提供独立沙箱。Kubernetes 本身并不限定只能使用某一种运行时。
隔离原理：每个 Pod 使用独立 Guest 内核
普通 runc 容器通过 Linux namespace、cgroup 等机制隔离进程和限制资源，仍共享宿主机内核。Cube 为每个 Pod 创建独立虚拟机和 Guest 内核，Pod 内的初始化容器、业务容器和 sidecar 共用该沙箱，不同 Pod 使用不同沙箱。
对于执行模型生成代码、第三方脚本或用户工具的 Agent，这增加了虚拟化隔离边界：业务代码的系统调用在 Guest 内核中处理，减少直接依赖宿主机共享内核进行隔离的范围。同一 Pod 内的容器仍属于同一沙箱，不能把它们当作彼此独立的安全域；不同信任来源的任务应分配到不同 Pod。
启动原理：复用已初始化的沙箱模板
如果每次创建虚拟机都从头启动 Guest 系统和内部服务，会增加短任务的准备开销。Cube 的模板快路径复用已初始化的基础 Guest 状态：
1. 根据所需 CPU、内存及 Guest 版本查找节点上匹配的就绪模板。
2. 命中后从模板恢复独立虚拟机，减少重复启动 Guest 内核、内部 Agent 服务及部分网络设备初始化的工作。
3. 为本次 Pod 配置独立身份和网络，再创建业务容器、挂载工作区并执行应用命令。
4. 没有匹配模板时走冷启动，并异步准备后续可复用的模板。新节点、规格变化或 Guest 版本变化都可能首次未命中。
模板保存的是基础沙箱状态，不包含本次业务镜像、Secret、工作区和已初始化的 Python 或模型进程。镜像预热、镜像加速、工作区复用和应用初始化优化仍各自发挥作用。
客户可以获得什么收益
维度 | 普通容器运行时（runc） | Cube 沙箱运行时 |
执行不可信代码 | 主要依赖共享内核上的容器隔离与安全策略。 | 每 Pod 独立 Guest 内核，增加虚拟化隔离边界，适合需要隔离执行的 Agent 工具和代码任务。 |
短任务启动 | 无需为每个 Pod 启动独立 Guest 内核，普通容器启动路径较轻。 | 通过预初始化模板减少独立沙箱的重复启动开销，使隔离环境更适合频繁创建和回收。 |
批量任务 | 沿用 Kubernetes 调度和容器生命周期。 | 同样沿用 Kubernetes；模板命中可减少每个沙箱重复初始化，但仍受 API、调度、镜像、网络和节点容量影响。 |
应用接入 | 使用标准 Pod、Job、Deployment 及容器镜像。 | 沿用这些资源，通过 RuntimeClass 选择 Cube，同时核对宿主机依赖和运行时兼容性。 |
Cube 的启动优化主要解决“采用独立沙箱隔离后，如何减少环境准备开销”。接入时可先将需要执行不可信代码的任务放到 Cube，按相同镜像、节点规格、并发数和缓存条件分别测量 API 提交、沙箱创建、Pod Ready 和首次业务结果。
调用 Kubernetes API 有哪些差异
已有平台通过 Kubernetes API 创建和管理任务时，可以继续使用 kubectl、client-go 或 Kubernetes Python SDK。连接新 Agent 集群的 API Server，使用该集群的 kubeconfig 和访问权限；无需为了创建 Cube Pod 把请求改发到 Cube API 或 AgentWay API。
调用方式与请求内容
调用环节 | 可以沿用的方式 |
连接与认证 | 使用 Kubernetes 客户端、TLS 和集群身份认证。 |
创建任务 | Pod 仍使用 POST /api/v1/namespaces/{namespace}/pods；Job 仍使用 POST /apis/batch/v1/namespaces/{namespace}/jobs。 |
查询与等待 | 沿用 Get、List、Watch 和 Pod / Job 状态字段。 |
日志与命令执行 | 沿用 kubectl logs、kubectl exec 及 Kubernetes 客户端对应能力。 |
资源与调度 | 沿用 requests、limits、节点选择、亲和性和污点容忍配置。 |
文件持久化 | 沿用 PVC、volumes 和 volumeMounts。 |
删除任务 | 沿用删除 Pod、Deployment 或 Job 的 API。 |
运行时字段的位置示例如下。这是已有清单的局部修改，不是完整可提交的资源清单：
# Podspec:runtimeClassName: cube
# Deployment 或 Jobspec:template:spec:runtimeClassName: cube
Pod 配置不能直接照搬的情况
使用 Cube 时，容器运行在沙箱环境中。标准 API 接受字段，并不等于所选运行时支持该字段对应的所有行为。
宿主机命名空间：当前实现拒绝
hostNetwork: true、hostPID: true 和 hostIPC: true。需要这些能力的节点代理或运维组件应单独评估运行环境，不能直接把 RuntimeClass 改为 Cube。特权和宿主机依赖：
privileged 需要运行时配置允许，同时满足集群安全策略。沙箱内的特权不能视为物理宿主机权限；访问宿主机设备、内核或目录的程序需要专项验证。建议先使用原有任务完成“创建、等待、执行、读取结果、删除”的完整流程，再验证探针、重启、工作区接续和异常退出。服务端 dry-run 只能检查 API 校验和准入，不能代替实际启动测试。
已有 TKE 应用需要改哪些配置
工作负载与运行时
已有镜像、启动命令和资源声明可以作为接入起点。先选取一个典型任务，核对以下配置，再扩大部署范围：
集群访问配置：为新 Agent 集群取得对应的 kubeconfig，确认当前操作的集群和命名空间。
运行时选择：使用 Cube 时填写目标集群实际提供的 RuntimeClass，并确认任务能调度到具备该运行环境的节点。不要将“成功提交 Pod”视为已经使用沙箱运行时。
依赖与权限：核对镜像架构、设备依赖、宿主机访问、特权配置及挂载方式。依赖宿主机能力的应用不能仅修改 RuntimeClass 后就假定可以运行。
发布配置：重新检查节点标签、污点容忍、配额、Secret 和 ServiceAccount。原集群的配置与权限不会自动成为新集群的配置。
工作区与数据
普通 TKE 应用可以通过持久卷保留数据，Agent 集群的 AgentWorkspaces 也通过 PVC 与容器挂载路径供业务使用。对应用而言，关键是把需要保留的文件写入已挂载的目录，而不是容器临时目录。
使用 AgentWorkspaces 时：
1. 为用户、项目或任务创建独立工作区，并设置合适容量。
2. 将工作区挂载到应用实际读写的目录，例如
/workspace。3. 重建 Agent 时保留原 PVC，让新实例继续使用同一工作区。
4. 核对旧文件内容和新写入结果，确认可以继续工作。
已有 CBS、CFS 或容器目录中的数据不会自动迁移。需要切换存储时，应单独安排复制、停止写入、切换挂载和内容校验，完成验证前保留原数据。
默认提供与按需配置的区别
能力 | 使用前还需要做什么 |
AgentWorkspaces | 随创建集群默认安装；为业务创建 PVC、挂载目录并定义保留和清理方式。 |
Cube 沙箱运行环境 | 准备匹配的节点配置，核对实际 RuntimeClass，并运行任务验证。 |
镜像加速 | 创建集群时选择开启及 TCR 实例，配置转换规则，等待镜像转换完成并验证实际命中。 |
内存压缩、节点放大 | 在支持的原生节点环境中分别配置，小范围验证延迟、资源压力和失败率后再扩大范围。 |
上述能力各自解决不同问题。工作区复用不会省去模型初始化，镜像加速不会自动加速所有业务文件读取，节点放大也不会增加节点的物理 CPU 和内存。评估效果时应使用相同任务和资源条件，测量从提交到任务可执行、首次业务结果返回的完整时间。
建议的接入顺序
1. 在 Agent Runtime 控制台新建测试集群及节点池，保留原 TKE 业务正常运行。
2. 选择一个依赖明确、数据可复制的 Agent 任务，核对镜像、运行时、权限和网络。
3. 配置工作区，验证文件写入、实例重建和任务接续。
4. 按需启用镜像加速等能力，比较相同条件下的启动与任务完成时间。
5. 验证失败排查、任务重试、资源释放和数据保留，再逐步迁移更多任务。
集群状态正常或 Pod 就绪，只能证明相应资源状态满足条件。正式迁移前，还应让 Agent 完成真实工具调用并核对业务结果。
排障与清理有哪些不同
原有的 Pod 事件、容器日志和资源状态仍是排障起点。Agent 任务出现问题时，还需按现象区分运行时启动、工作区挂载、模型连接和工具权限，避免将它们都归因于“Agent 启动慢”。常见处理方式请参见 常见故障排查。
删除运行实例、删除工作区和删除整个集群是不同操作。需要后续接续任务时保留原工作区；退出使用前先导出结果、迁移所需数据，再核对节点、存储、网络和其他计费资源的释放情况。
