云原生容器运行时【免费下载链接】kata-containersKata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. https://katacontainers.io/项目地址https://gitcode.com/gh_mirrors/ka/kata-containers点击查看免费下载Kata Containers 运行时库virtcontainers在设计上抽象出了一整套面向 Sandbox 的顶层 API将虚拟机生命周期管理、容器操作、设备网络热插拔、进程信号中继与指标监控统一收敛为可编程接口同时通过插件框架为外部私有扩展提供挂载点。本文基于仓库中的 API 设计文档逐层拆解这套 API 的划分逻辑并结合 interfaces.go、api.go 与 factory 子包源码说明每个 API 背后的真实实现路径读完本文你将能够理解 Kata Containers 的运行时接口全貌并掌握 Sandbox 创建、热插拔、VM 工厂三类扩展点的编程方式。一、设计背景与 API 总体划分Kata API 设计文档开篇即点明其目标为了满足 设计需求文档含 OCI 兼容、runcCLI 兼容、CRI/Kubernetes 支持、多架构、多 hypervisor、网络与 I/O 等硬性要求并基于 Virtcontainers API 扩展讨论运行时库最终确立了三层 API 结构Sandbox 顶层 API以 Sandbox沙箱即一个 VM 及其内运行的一组容器为核心对象的全部管理、操作、热插拔、中继与监控接口存储与网络热插拔 API支撑在 VM 运行期动态添加/移除设备与网络接口的能力插件框架为外部私有 Kata 运行时扩展hypervisor、元数据存储、VM 工厂预留的标准接口。在源码层面这套设计落地为virtcontainers包中的两大核心接口VC运行时入口与VCSandboxSandbox 抽象。由于Sandbox结构体的字段均为私有外部包只能通过公开接口访问interfaces.go中的注释明确说明了这一点VCSandbox is the Sandbox interface (required since virtcontainers.Sandbox only contains private fields)这种结构体私有 接口公开的设计保证了沙箱内部状态hypervisor 连接、agent 会话、持久化元数据不会被外部随意篡改所有操作都必须经由接口方法完成。二、Sandbox 管理 API创建入口与生命周期起点CreateSandbox一切 Sandbox 操作的入口文档定义的 Sandbox 管理 API 仅有一个方法也是整套 API 的起点名称描述CreateSandbox(SandboxConfig, Factory)基于SandboxConfig与Factory创建沙箱及其容器返回Sandbox结构体但不启动它们对应源码位于 api.gofunc CreateSandbox(ctx context.Context, sandboxConfig SandboxConfig, factory Factory, prestartHookFunc func(context.Context) error) (VCSandbox, error)文档中「创建但不启动」的语义在实现中被细化为一连串有序步骤见createSandboxFromConfigcreateSandbox(ctx, sandboxConfig, factory)——实例化 Sandbox 对象s.createNetwork(ctx)——创建沙箱网络s.setupResourceController()——设置宿主机 cgroupss.startVM(ctx, prestartHookFunc)——启动 VM注意此时 VM 已启动但容器尚未启动与 OCI 的create/start两阶段语义对齐s.getAndStoreGuestDetails(ctx)——采集并存储 guest 细节s.createContainers(ctx)——创建容器。同时实现内置了完善的失败回滚机制任一步骤出错时依次执行s.Delete(ctx)、s.removeNetwork(ctx)、s.stopVM(ctx)清理已创建的资源避免创建失败留下孤儿 VM 或残留网络。这正对应了文档中「do not start them」的设计意图——创建与启动解耦使上层如 containerd shim可以精确控制启动时机。顶层入口的另一个方法CleanupContainerVC接口还定义了CleanupContainer供 shimv2 在无容器残留时独占地停止并删除沙箱见 api.go它先对 sandboxID 加写锁取回沙箱后依次执行StopContainer、DeleteContainer若沙箱中已无容器则继续Stop与Delete整个沙箱。若 hypervisor 进程已消失还会先将 agent 标记为 dead 以避免对失效 vsock 连接的阻塞等待使清理快速失败。三、Sandbox 操作 API容器与沙箱的完整生命周期文档以表格形式给出了 18 个 Sandbox 操作 API这些方法在 interfaces.go 的VCSandbox接口中一一对应文档 API接口签名节选说明sandbox.Delete()Delete(ctx) error关闭 VM、销毁沙箱并移除全部持久化元数据sandbox.Monitor()Monitor(ctx) (chan error, error)返回错误通道供调用方监听沙箱异常终止等回调sandbox.Release()Release(ctx) error释放沙箱数据结构、断开与 agent 的连接、退出相关 goroutine主要用于守护进程重启sandbox.Start()Start(ctx) error启动沙箱及其容器sandbox.Stats()Stats(ctx) (SandboxStats, error)获取运行中沙箱的统计信息sandbox.Status()Status() SandboxStatus获取沙箱与容器状态sandbox.Stop(force)Stop(ctx, force bool) error停止沙箱并销毁其中容器force 为 true 时忽略 guest 侧停止失败sandbox.CreateContainer(contConfig)CreateContainer(ctx, contConfig ContainerConfig) (VCContainer, error)在沙箱中创建新容器并将配置追加到sandbox.config.Containerssandbox.DeleteContainer(containerID)DeleteContainer(ctx, containerID string) (VCContainer, error)按 ID 删除容器并返回被删除的Containersandbox.EnterContainer(containerID, cmd)EnterContainer(ctx, containerID, cmd types.Cmd) (VCContainer, *Process, error)在容器中运行新进程执行用户传入的types.Cmd命令对应 OCIexecsandbox.KillContainer(containerID, signal, all)KillContainer(ctx, containerID, signal syscall.Signal, all bool) error向容器内进程发送信号对应 OCIkillsandbox.PauseContainer(containerID)PauseContainer(ctx, containerID) error暂停运行中的容器对应 OCIpausesandbox.ProcessListContainer(containerID, options)经ps相关内部方法实现列出容器内所有进程对应 OCIpssandbox.ResumeContainer(containerID)ResumeContainer(ctx, containerID) error恢复被暂停的容器对应 OCIresumesandbox.StartContainer(containerID)StartContainer(ctx, containerID) (VCContainer, error)启动沙箱内指定容器sandbox.StatsContainer(containerID)StatsContainer(ctx, containerID) (ContainerStats, error)获取容器统计信息sandbox.StatusContainer(containerID)StatusContainer(containerID) (ContainerStatus, error)获取容器状态sandbox.StopContainer(containerID, force)StopContainer(ctx, containerID, force bool) (VCContainer, error)停止沙箱内指定容器sandbox.UpdateContainer(containerID, resources)UpdateContainer(ctx, containerID, resources specs.LinuxResources) error更新运行中容器的资源限制对应 OCIupdatesandbox.WaitProcess(containerID, processID)WaitProcess(ctx, containerID, processID string) (int32, error)等待指定进程终止值得注意的对应关系Sandbox 操作 API 基本是 OCI 运行时命令的虚拟化映射。CreateContainer/StartContainer/StopContainer/DeleteContainer/EnterContainer/KillContainer/PauseContainer/ResumeContainer/UpdateContainer分别对应 OCI 的 create/start/stop/delete/exec/kill/pause/resume/update这正是设计需求中「OCI 兼容」要求kata-design-requirements.md 列出的runc命令全集在库 API 层面的落地——上层 CRI shim 与 kata-runtime CLI 都通过这组接口与 VM 内的容器交互。四、Sandbox 热插拔 API动态设备与网络管理热插拔 API 让运行中的沙箱VM可以动态调整设备与网络拓扑对应接口定义见 interfaces.go文档 API接口签名说明sandbox.AddDevice(info)AddDevice(ctx, info config.DeviceInfo) (api.Device, error)向沙箱添加存储等设备返回Device结构体sandbox.AddInterface(inf)AddInterface(ctx, inf *pbTypes.Interface) (*pbTypes.Interface, error)向沙箱添加新的 NICsandbox.RemoveInterface(inf)RemoveInterface(ctx, inf *pbTypes.Interface) (*pbTypes.Interface, error)从沙箱移除 NICsandbox.ListInterfaces()ListInterfaces(ctx) ([]*pbTypes.Interface, error)列出沙箱内所有 NIC 及其配置sandbox.UpdateRoutes(routes)UpdateRoutes(ctx, routes []*pbTypes.Route) ([]*pbTypes.Route, error)更新沙箱路由表如端口映射支持sandbox.ListRoutes()ListRoutes(ctx) ([]*pbTypes.Route, error)列出沙箱路由表从签名可以看到网络类热插拔操作直接复用了 agent 协议中的pbTypes.Interface与pbTypes.Route类型来自src/runtime/virtcontainers/pkg/agent/protocols这意味着这些调用最终通过 gRPC 下发到 guest 内的 Kata agent由 agent 在 guest 侧完成网卡的创建/删除与路由表更新。AddDevice则走设备管理路径支持存储设备与直通设备的动态挂载。这一组 API 是 Kata Containers 支撑 Kubernetes 网络插件CNI动态增删网卡、以及容器运行时挂载新卷hotplug volume的基础设施上层只需传入标准的设备/接口描述结构即可在不重启 VM 的前提下完成变更。五、Sandbox 中继Relay与监控 API中继 API进程 I/O 与信号透传文档 API说明sandbox.WinsizeProcess(containerID, processID, Height, Width)将 TTY 尺寸调整请求中继给指定进程sandbox.SignalProcess(containerID, processID, signalID, signalALL)向容器内单个进程或全部进程中继信号sandbox.IOStream(containerID, processID)中继进程 stdio返回与进程 stdin/stdout/stderr 流对接的管道实现中SignalProcess与WinsizeProcess均带syscall.Signal/ 宽高参数直接透传给 agentIOStream的签名是IOStream(containerID, processID string) (io.WriteCloser, io.Reader, io.Reader, error)返回的写管道stdin与两个读管道stdout/stderr正是kata-runtime exec与 containerd shim 将宿主机终端接入 guest 进程的关键路径。WaitProcess与SignalProcess的组合也构成了 CRI 对容器内进程做生命周期管理的底层支撑。监控 APIOOM 事件与运行时指标文档 API说明sandbox.GetOOMEvent()监控沙箱内发生的 OOM 事件接口返回string事件描述sandbox.UpdateRuntimeMetrics()更新运行中沙箱的 shim/hypervisor 指标sandbox.GetAgentMetrics()获取 agent 与 guest 侧的指标VCSandbox接口中还包含GetHypervisorPid()、GetAgentURL()等配套方法以及GuestVolumeStats/ResizeGuestVolumeguest 卷统计与扩容、GetIPTables/SetIPTablesiptables 规则同步、SetPolicyagent 策略下发等较新加入的能力反映了 API 面向实际运行观测与安全加固的持续演进。六、插件框架外部私有 Kata 运行时扩展文档将插件框架划分为三类其中 hypervisor 插件标注为 TBD而存储与 VM 工厂两类给出了明确契约。元数据存储插件元数据存储插件决定沙箱元数据的保存位置所有插件必须实现API描述storage.Save(key, value)保存一条记录storage.Load(key)加载一条记录storage.Delete(key)删除一条记录文档列出的内置实现为Filesystem storage与LevelDB storage。在 persist 目录下可以看到该设计的实际形态persist/api定义了抽象的PersistDriver接口persist/fs/fs.go 实现了文件系统驱动——它将沙箱状态序列化为 JSON 写入/run/vc/sbs/sandboxID/persist.jsonpersistFile常量目录权限 0700、文件权限 0600并提供Init()工厂方法返回PersistDriver抽象persist/plugin目录则承载插件注册机制。该设计沿用了文档的 Save/Load/Delete 语义实现中对应ToDisk、Load与Destroy等使元数据后端可以按需替换。VM Factory 插件VM 工厂插件控制沙箱工厂如何创建新 VM契约只有一条API描述VMFactory.NewVM(HypervisorConfig)基于HypervisorConfig创建新 VM内置实现名称描述CreateNew()基于HypervisorConfig创建全新 VMCreateFromTemplate()从模板创建新 VMCreateFromCache()从 VM 缓存创建新 VM源码中factory.go 定义了顶层Factory接口GetVM、GetBaseVM、CloseFactory等其下再分出内部FactoryBase接口factory/base/base.go并对应三套实现direct对应CreateNewdirect.go 直接调用vc.NewVM(ctx, config)创建全新 VM 并立即Pause备妥template对应CreateFromTemplatetemplate/template_linux.go 在 tmpfs 上构建模板 VM设置BootToBeTemplate true等待 agent 重启后Pause并Save()内存与设备状态此后每次GetBaseVM以BootFromTemplate true从模板状态快速派生新 VM显著缩短启动时间cache对应CreateFromCachecache/cache.go 在底层工厂之上维护一个 VM 缓存通道cacheCh后台 goroutine 预先创建并暂停 VM 放入缓存调用方直接取用实现 VM 池化即文档中CreateFromCache语义。需要说明的是文档中CreateFromTemplate的模板机制仅支持 Linux源码文件名为template_linux.go并区分了 QEMU 的state与 Cloud Hypervisor 的state.json状态文件cache 缓存也以 Linux 为主要目标平台。这套工厂插件机制正是 VM 缓存与模板化 以及template/cache相关配置项如enable_template、enable_cache的编程接口。插件工作流示意文档中给出了两张插件工作流图Sandbox Creation 与 Sandbox Connection用于说明工厂在沙箱创建与连接阶段如何介入。由于原图托管于外部地址本文不再内嵌其含义可结合上文实现描述理解创建沙箱时CreateSandbox接收的Factory实例决定 VM 是全新创建、来自模板还是来自缓存而连接阶段则对应工厂提供的GetVM/GetBaseVM取用路径。七、API 的调用方与使用链路顶层VC接口CreateSandbox与CleanupContainer的实际调用方分布在 runtime 上层kata-runtime CLIsrc/runtime/cmd/kata-runtime下的create、start、delete、exec、kill、pause、resume、ps、state等命令逐一映射到上文 Sandbox 操作 APIcontainerd-shim-kata-v2src/runtime/cmd/containerd-shim-kata-v2与src/runtime/pkg/containerd-shim-v2基于VCSandbox接口实现 CRI 的 sandbox/container 生命周期、exec、metrics 等调用其中CleanupContainer即专为 shimv2 的清理路径设计kata-monitorsrc/runtime/pkg/kata-monitor通过GetAgentMetrics、UpdateRuntimeMetrics等监控 API 暴露 Prometheus 指标端点。因此本文介绍的 API 不是抽象摆设而是 Kata Containers 从 OCI 命令到 CRI 插件全链路的公共编程契约。八、总结Kata API 设计文档确立的「Sandbox 顶层 API 热插拔 API 插件框架」三层结构在 virtcontainers 包中得到了完整落地Sandbox 操作 API与 OCI/runc 命令一一映射通过 interfaces.go 的VCSandbox接口对外提供创建流程在 api.go 中实现了严格的失败回滚热插拔 API支持运行期动态添加设备与网卡、更新路由其网络类型直接复用 agent 协议类型最终由 guest 内 agent 执行插件框架中的存储插件persist/fs与 VM 工厂插件factory 下的 direct/template/cache 三实现为外部扩展和启动性能优化提供了标准挂载点。读者可以以此为地图进一步阅读 interfaces.go 中的完整接口定义、api.go 中的沙箱创建实现以及 kata-design-requirements.md 理解 API 设计背后的需求约束。赞分享云原生容器运行时【免费下载链接】kata-containersKata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. https://katacontainers.io/项目地址https://gitcode.com/gh_mirrors/ka/kata-containers点击查看免费下载相关推荐Kata Containers VMCache 实战预创建 VM 缓存加速 Sandbox 启动Kata Containers VMCache 实战预创建 VM 缓存加速 Sandbox 启动 本文基于 Kata Containers 官方文档 wha云原生容器运行时Kata Containers VM 模板VM Templating原理、配置与实操指南Kata Containers VM 模板VM Templating原理、配置与实操指南 VM 模板VM Templating是 Kata Contai云原生容器运行时Kata Containers virtcontainers 1.0 API 完全指南Sandbox 与 Container 编程接口详解Kata Containers virtcontainers 1.0 API 完全指南Sandbox 与 Container 编程接口详解 Kata Cont云原生容器运行时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kata Containers API 设计解析：从 Sandbox 操作到 VM 插件框架
云原生容器运行时【免费下载链接】kata-containersKata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. https://katacontainers.io/项目地址https://gitcode.com/gh_mirrors/ka/kata-containers点击查看免费下载Kata Containers 运行时库virtcontainers在设计上抽象出了一整套面向 Sandbox 的顶层 API将虚拟机生命周期管理、容器操作、设备网络热插拔、进程信号中继与指标监控统一收敛为可编程接口同时通过插件框架为外部私有扩展提供挂载点。本文基于仓库中的 API 设计文档逐层拆解这套 API 的划分逻辑并结合 interfaces.go、api.go 与 factory 子包源码说明每个 API 背后的真实实现路径读完本文你将能够理解 Kata Containers 的运行时接口全貌并掌握 Sandbox 创建、热插拔、VM 工厂三类扩展点的编程方式。一、设计背景与 API 总体划分Kata API 设计文档开篇即点明其目标为了满足 设计需求文档含 OCI 兼容、runcCLI 兼容、CRI/Kubernetes 支持、多架构、多 hypervisor、网络与 I/O 等硬性要求并基于 Virtcontainers API 扩展讨论运行时库最终确立了三层 API 结构Sandbox 顶层 API以 Sandbox沙箱即一个 VM 及其内运行的一组容器为核心对象的全部管理、操作、热插拔、中继与监控接口存储与网络热插拔 API支撑在 VM 运行期动态添加/移除设备与网络接口的能力插件框架为外部私有 Kata 运行时扩展hypervisor、元数据存储、VM 工厂预留的标准接口。在源码层面这套设计落地为virtcontainers包中的两大核心接口VC运行时入口与VCSandboxSandbox 抽象。由于Sandbox结构体的字段均为私有外部包只能通过公开接口访问interfaces.go中的注释明确说明了这一点VCSandbox is the Sandbox interface (required since virtcontainers.Sandbox only contains private fields)这种结构体私有 接口公开的设计保证了沙箱内部状态hypervisor 连接、agent 会话、持久化元数据不会被外部随意篡改所有操作都必须经由接口方法完成。二、Sandbox 管理 API创建入口与生命周期起点CreateSandbox一切 Sandbox 操作的入口文档定义的 Sandbox 管理 API 仅有一个方法也是整套 API 的起点名称描述CreateSandbox(SandboxConfig, Factory)基于SandboxConfig与Factory创建沙箱及其容器返回Sandbox结构体但不启动它们对应源码位于 api.gofunc CreateSandbox(ctx context.Context, sandboxConfig SandboxConfig, factory Factory, prestartHookFunc func(context.Context) error) (VCSandbox, error)文档中「创建但不启动」的语义在实现中被细化为一连串有序步骤见createSandboxFromConfigcreateSandbox(ctx, sandboxConfig, factory)——实例化 Sandbox 对象s.createNetwork(ctx)——创建沙箱网络s.setupResourceController()——设置宿主机 cgroupss.startVM(ctx, prestartHookFunc)——启动 VM注意此时 VM 已启动但容器尚未启动与 OCI 的create/start两阶段语义对齐s.getAndStoreGuestDetails(ctx)——采集并存储 guest 细节s.createContainers(ctx)——创建容器。同时实现内置了完善的失败回滚机制任一步骤出错时依次执行s.Delete(ctx)、s.removeNetwork(ctx)、s.stopVM(ctx)清理已创建的资源避免创建失败留下孤儿 VM 或残留网络。这正对应了文档中「do not start them」的设计意图——创建与启动解耦使上层如 containerd shim可以精确控制启动时机。顶层入口的另一个方法CleanupContainerVC接口还定义了CleanupContainer供 shimv2 在无容器残留时独占地停止并删除沙箱见 api.go它先对 sandboxID 加写锁取回沙箱后依次执行StopContainer、DeleteContainer若沙箱中已无容器则继续Stop与Delete整个沙箱。若 hypervisor 进程已消失还会先将 agent 标记为 dead 以避免对失效 vsock 连接的阻塞等待使清理快速失败。三、Sandbox 操作 API容器与沙箱的完整生命周期文档以表格形式给出了 18 个 Sandbox 操作 API这些方法在 interfaces.go 的VCSandbox接口中一一对应文档 API接口签名节选说明sandbox.Delete()Delete(ctx) error关闭 VM、销毁沙箱并移除全部持久化元数据sandbox.Monitor()Monitor(ctx) (chan error, error)返回错误通道供调用方监听沙箱异常终止等回调sandbox.Release()Release(ctx) error释放沙箱数据结构、断开与 agent 的连接、退出相关 goroutine主要用于守护进程重启sandbox.Start()Start(ctx) error启动沙箱及其容器sandbox.Stats()Stats(ctx) (SandboxStats, error)获取运行中沙箱的统计信息sandbox.Status()Status() SandboxStatus获取沙箱与容器状态sandbox.Stop(force)Stop(ctx, force bool) error停止沙箱并销毁其中容器force 为 true 时忽略 guest 侧停止失败sandbox.CreateContainer(contConfig)CreateContainer(ctx, contConfig ContainerConfig) (VCContainer, error)在沙箱中创建新容器并将配置追加到sandbox.config.Containerssandbox.DeleteContainer(containerID)DeleteContainer(ctx, containerID string) (VCContainer, error)按 ID 删除容器并返回被删除的Containersandbox.EnterContainer(containerID, cmd)EnterContainer(ctx, containerID, cmd types.Cmd) (VCContainer, *Process, error)在容器中运行新进程执行用户传入的types.Cmd命令对应 OCIexecsandbox.KillContainer(containerID, signal, all)KillContainer(ctx, containerID, signal syscall.Signal, all bool) error向容器内进程发送信号对应 OCIkillsandbox.PauseContainer(containerID)PauseContainer(ctx, containerID) error暂停运行中的容器对应 OCIpausesandbox.ProcessListContainer(containerID, options)经ps相关内部方法实现列出容器内所有进程对应 OCIpssandbox.ResumeContainer(containerID)ResumeContainer(ctx, containerID) error恢复被暂停的容器对应 OCIresumesandbox.StartContainer(containerID)StartContainer(ctx, containerID) (VCContainer, error)启动沙箱内指定容器sandbox.StatsContainer(containerID)StatsContainer(ctx, containerID) (ContainerStats, error)获取容器统计信息sandbox.StatusContainer(containerID)StatusContainer(containerID) (ContainerStatus, error)获取容器状态sandbox.StopContainer(containerID, force)StopContainer(ctx, containerID, force bool) (VCContainer, error)停止沙箱内指定容器sandbox.UpdateContainer(containerID, resources)UpdateContainer(ctx, containerID, resources specs.LinuxResources) error更新运行中容器的资源限制对应 OCIupdatesandbox.WaitProcess(containerID, processID)WaitProcess(ctx, containerID, processID string) (int32, error)等待指定进程终止值得注意的对应关系Sandbox 操作 API 基本是 OCI 运行时命令的虚拟化映射。CreateContainer/StartContainer/StopContainer/DeleteContainer/EnterContainer/KillContainer/PauseContainer/ResumeContainer/UpdateContainer分别对应 OCI 的 create/start/stop/delete/exec/kill/pause/resume/update这正是设计需求中「OCI 兼容」要求kata-design-requirements.md 列出的runc命令全集在库 API 层面的落地——上层 CRI shim 与 kata-runtime CLI 都通过这组接口与 VM 内的容器交互。四、Sandbox 热插拔 API动态设备与网络管理热插拔 API 让运行中的沙箱VM可以动态调整设备与网络拓扑对应接口定义见 interfaces.go文档 API接口签名说明sandbox.AddDevice(info)AddDevice(ctx, info config.DeviceInfo) (api.Device, error)向沙箱添加存储等设备返回Device结构体sandbox.AddInterface(inf)AddInterface(ctx, inf *pbTypes.Interface) (*pbTypes.Interface, error)向沙箱添加新的 NICsandbox.RemoveInterface(inf)RemoveInterface(ctx, inf *pbTypes.Interface) (*pbTypes.Interface, error)从沙箱移除 NICsandbox.ListInterfaces()ListInterfaces(ctx) ([]*pbTypes.Interface, error)列出沙箱内所有 NIC 及其配置sandbox.UpdateRoutes(routes)UpdateRoutes(ctx, routes []*pbTypes.Route) ([]*pbTypes.Route, error)更新沙箱路由表如端口映射支持sandbox.ListRoutes()ListRoutes(ctx) ([]*pbTypes.Route, error)列出沙箱路由表从签名可以看到网络类热插拔操作直接复用了 agent 协议中的pbTypes.Interface与pbTypes.Route类型来自src/runtime/virtcontainers/pkg/agent/protocols这意味着这些调用最终通过 gRPC 下发到 guest 内的 Kata agent由 agent 在 guest 侧完成网卡的创建/删除与路由表更新。AddDevice则走设备管理路径支持存储设备与直通设备的动态挂载。这一组 API 是 Kata Containers 支撑 Kubernetes 网络插件CNI动态增删网卡、以及容器运行时挂载新卷hotplug volume的基础设施上层只需传入标准的设备/接口描述结构即可在不重启 VM 的前提下完成变更。五、Sandbox 中继Relay与监控 API中继 API进程 I/O 与信号透传文档 API说明sandbox.WinsizeProcess(containerID, processID, Height, Width)将 TTY 尺寸调整请求中继给指定进程sandbox.SignalProcess(containerID, processID, signalID, signalALL)向容器内单个进程或全部进程中继信号sandbox.IOStream(containerID, processID)中继进程 stdio返回与进程 stdin/stdout/stderr 流对接的管道实现中SignalProcess与WinsizeProcess均带syscall.Signal/ 宽高参数直接透传给 agentIOStream的签名是IOStream(containerID, processID string) (io.WriteCloser, io.Reader, io.Reader, error)返回的写管道stdin与两个读管道stdout/stderr正是kata-runtime exec与 containerd shim 将宿主机终端接入 guest 进程的关键路径。WaitProcess与SignalProcess的组合也构成了 CRI 对容器内进程做生命周期管理的底层支撑。监控 APIOOM 事件与运行时指标文档 API说明sandbox.GetOOMEvent()监控沙箱内发生的 OOM 事件接口返回string事件描述sandbox.UpdateRuntimeMetrics()更新运行中沙箱的 shim/hypervisor 指标sandbox.GetAgentMetrics()获取 agent 与 guest 侧的指标VCSandbox接口中还包含GetHypervisorPid()、GetAgentURL()等配套方法以及GuestVolumeStats/ResizeGuestVolumeguest 卷统计与扩容、GetIPTables/SetIPTablesiptables 规则同步、SetPolicyagent 策略下发等较新加入的能力反映了 API 面向实际运行观测与安全加固的持续演进。六、插件框架外部私有 Kata 运行时扩展文档将插件框架划分为三类其中 hypervisor 插件标注为 TBD而存储与 VM 工厂两类给出了明确契约。元数据存储插件元数据存储插件决定沙箱元数据的保存位置所有插件必须实现API描述storage.Save(key, value)保存一条记录storage.Load(key)加载一条记录storage.Delete(key)删除一条记录文档列出的内置实现为Filesystem storage与LevelDB storage。在 persist 目录下可以看到该设计的实际形态persist/api定义了抽象的PersistDriver接口persist/fs/fs.go 实现了文件系统驱动——它将沙箱状态序列化为 JSON 写入/run/vc/sbs/sandboxID/persist.jsonpersistFile常量目录权限 0700、文件权限 0600并提供Init()工厂方法返回PersistDriver抽象persist/plugin目录则承载插件注册机制。该设计沿用了文档的 Save/Load/Delete 语义实现中对应ToDisk、Load与Destroy等使元数据后端可以按需替换。VM Factory 插件VM 工厂插件控制沙箱工厂如何创建新 VM契约只有一条API描述VMFactory.NewVM(HypervisorConfig)基于HypervisorConfig创建新 VM内置实现名称描述CreateNew()基于HypervisorConfig创建全新 VMCreateFromTemplate()从模板创建新 VMCreateFromCache()从 VM 缓存创建新 VM源码中factory.go 定义了顶层Factory接口GetVM、GetBaseVM、CloseFactory等其下再分出内部FactoryBase接口factory/base/base.go并对应三套实现direct对应CreateNewdirect.go 直接调用vc.NewVM(ctx, config)创建全新 VM 并立即Pause备妥template对应CreateFromTemplatetemplate/template_linux.go 在 tmpfs 上构建模板 VM设置BootToBeTemplate true等待 agent 重启后Pause并Save()内存与设备状态此后每次GetBaseVM以BootFromTemplate true从模板状态快速派生新 VM显著缩短启动时间cache对应CreateFromCachecache/cache.go 在底层工厂之上维护一个 VM 缓存通道cacheCh后台 goroutine 预先创建并暂停 VM 放入缓存调用方直接取用实现 VM 池化即文档中CreateFromCache语义。需要说明的是文档中CreateFromTemplate的模板机制仅支持 Linux源码文件名为template_linux.go并区分了 QEMU 的state与 Cloud Hypervisor 的state.json状态文件cache 缓存也以 Linux 为主要目标平台。这套工厂插件机制正是 VM 缓存与模板化 以及template/cache相关配置项如enable_template、enable_cache的编程接口。插件工作流示意文档中给出了两张插件工作流图Sandbox Creation 与 Sandbox Connection用于说明工厂在沙箱创建与连接阶段如何介入。由于原图托管于外部地址本文不再内嵌其含义可结合上文实现描述理解创建沙箱时CreateSandbox接收的Factory实例决定 VM 是全新创建、来自模板还是来自缓存而连接阶段则对应工厂提供的GetVM/GetBaseVM取用路径。七、API 的调用方与使用链路顶层VC接口CreateSandbox与CleanupContainer的实际调用方分布在 runtime 上层kata-runtime CLIsrc/runtime/cmd/kata-runtime下的create、start、delete、exec、kill、pause、resume、ps、state等命令逐一映射到上文 Sandbox 操作 APIcontainerd-shim-kata-v2src/runtime/cmd/containerd-shim-kata-v2与src/runtime/pkg/containerd-shim-v2基于VCSandbox接口实现 CRI 的 sandbox/container 生命周期、exec、metrics 等调用其中CleanupContainer即专为 shimv2 的清理路径设计kata-monitorsrc/runtime/pkg/kata-monitor通过GetAgentMetrics、UpdateRuntimeMetrics等监控 API 暴露 Prometheus 指标端点。因此本文介绍的 API 不是抽象摆设而是 Kata Containers 从 OCI 命令到 CRI 插件全链路的公共编程契约。八、总结Kata API 设计文档确立的「Sandbox 顶层 API 热插拔 API 插件框架」三层结构在 virtcontainers 包中得到了完整落地Sandbox 操作 API与 OCI/runc 命令一一映射通过 interfaces.go 的VCSandbox接口对外提供创建流程在 api.go 中实现了严格的失败回滚热插拔 API支持运行期动态添加设备与网卡、更新路由其网络类型直接复用 agent 协议类型最终由 guest 内 agent 执行插件框架中的存储插件persist/fs与 VM 工厂插件factory 下的 direct/template/cache 三实现为外部扩展和启动性能优化提供了标准挂载点。读者可以以此为地图进一步阅读 interfaces.go 中的完整接口定义、api.go 中的沙箱创建实现以及 kata-design-requirements.md 理解 API 设计背后的需求约束。赞分享云原生容器运行时【免费下载链接】kata-containersKata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. https://katacontainers.io/项目地址https://gitcode.com/gh_mirrors/ka/kata-containers点击查看免费下载相关推荐Kata Containers VMCache 实战预创建 VM 缓存加速 Sandbox 启动Kata Containers VMCache 实战预创建 VM 缓存加速 Sandbox 启动 本文基于 Kata Containers 官方文档 wha云原生容器运行时Kata Containers VM 模板VM Templating原理、配置与实操指南Kata Containers VM 模板VM Templating原理、配置与实操指南 VM 模板VM Templating是 Kata Contai云原生容器运行时Kata Containers virtcontainers 1.0 API 完全指南Sandbox 与 Container 编程接口详解Kata Containers virtcontainers 1.0 API 完全指南Sandbox 与 Container 编程接口详解 Kata Cont云原生容器运行时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
