Kata Containers Pod 注解（Pod Annotations）完全指南：逐 Pod 定制运行时、Hypervisor 与 Agent 行为

发布时间：2026/9/25 2:13:06来源：尧图网络

云原生容器运行时【免费下载链接】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 通过 Pod 注解annotation机制让用户可以在每个 Pod 的规范spec中按需声明 Kata 专属配置从而实现同一个集群、不同 Pod 各用各的虚拟化参数。本文以 docs/pod-annotations.md 为骨架完整梳理全局、运行时、Agent、Hypervisor、容器资源五类注解的键名与取值约束讲解 containerd 的透传配置方式与受限注解Restricted Annotations的安全校验机制并结合 annotations.go、pkg/oci/utils.go 与 agent/src/rpc.rs 等源码说明一条注解从 OCI spec 解析到 guest 内核生效的完整链路。读完本文你将能够为特定 Pod 注入内核模块、开关 guest seccomp、调整 Hypervisor 资产路径等而无需修改全局configuration.toml。一、Kata Pod 注解机制概述Kata Containers 给予用户在每个 Pod 级别自由定制的能力在 Pod 规范中设置一系列 Kata 专属注解即可。所有 Kata 注解共用io.katacontainers.*前缀具体键名在源码中统一定义于 src/runtime/virtcontainers/pkg/annotations/annotations.go其前缀常量如下kataAnnotationsPrefix io.katacontainers. kataConfAnnotationsPrefix kataAnnotationsPrefix config. kataAnnotHypervisorPrefix kataConfAnnotationsPrefix hypervisor. kataAnnotContainerPrefix kataAnnotationsPrefix container.可以看出绝大多数配置类注解位于io.katacontainers.config.*命名空间下按runtime、agent、hypervisor等维度分组与配置文件configuration.toml中的配置项一一对应。受限注解Restricted Annotations部分注解可能被配置文件出于安全原因限制restricted尤其是那些可能导致运行时在宿主机上执行程序的注解。这类注解在下文表格中以(R)标记。所谓限制是指配置文件中预先指定了可接受的值通常是 shell 通配模式见下文受限注解一节。二、Kata 配置注解分类全表Kata 的配置注解分为若干类下文逐一列出完整键名、值类型与语义说明。所有表均继承自官方文档并补充了源码层面的印证。2.1 全局选项Global OptionsKeyValue TypeCommentsio.katacontainers.pkg.oci.bundle_pathstringOCI bundle 路径io.katacontainers.pkg.oci.container_typestringOCI 容器类型。仅接受pod_container和pod_sandbox这两个键由运行时shim内部使用用于标记沙箱与容器通常不面向最终用户手工设置。其常量定义见 annotations.go 中的BundlePathKey与ContainerTypeKey。2.2 运行时选项Runtime OptionsKeyValue TypeCommentsio.katacontainers.config.runtime.experimentalboolean是否启用实验性特性experimental features。值的解析在 pkg/oci/utils.go 中进行按空格拆分特性名逐一查表遇到未注册的特性会报错Unsupported experimental featureio.katacontainers.config.runtime.disable_guest_seccompboolean是否在 guest 内部应用seccomp。置为false即启用 guest seccomp 以获得更强隔离代价是少量性能开销io.katacontainers.config.runtime.disable_new_netnsboolean是否为 hypervisor 进程创建新的 netns。解析后写入NetworkConfig.DisableNewNetwork见 pkg/oci/utils.goio.katacontainers.config.runtime.internetworking_modelstring决定 VM 如何接入容器网络接口。合法取值macvtap、tcfilter、l3forwarding仅 runtime-rs 支持实验性和none。非法值会在解析时报Unknown network model specified in annotationio.katacontainers.config.runtime.sandbox_cgroup_onlyboolean决定 Kata 进程是否仅由 sandbox cgroup 管理io.katacontainers.config.runtime.enable_pprofboolean为containerd-shim-kata-v2进程启用 Golangpprof便于性能剖析与问题排查io.katacontainers.config.runtime.create_container_timeoutuint64创建容器超时时间单位为秒默认60io.katacontainers.config.runtime.experimental_force_guest_pullboolean强制运行时在 guest VM 内拉取镜像默认false。属实验性特性未来可能移除2.3 Agent 选项Agent OptionsKeyValue TypeCommentsio.katacontainers.config.agent.enable_tracingboolean为 agent 启用 tracing与运行时 tracing 配套详见 docs/tracing.mdio.katacontainers.config.agent.container_pipe_sizeuint32指定为容器创建的 std(in/out) 管道大小。解析时经setUint转为uint32写入AgentConfig.ContainerPipeSize见 pkg/oci/utils.goio.katacontainers.config.agent.kernel_modulesstring需要在 guest 内核中加载的内核模块及参数列表以分号分隔每个元素第一个词为模块名其余为参数。guest 内使用modprobe(8) 加载。例如e1000e InterruptThrottleRate3000,3000,3000 EEE1; i915 enable_ppgtt0io.katacontainers.config.agent.cdh_api_timeoutuint32Go 运行时中 Confidential Data HubCDHAPI 服务的超时时间秒默认50io.katacontainers.config.agent.cdh_api_timeout_msuint32runtime-rs 中 Confidential Data HubCDHAPI 服务的超时时间毫秒默认500002.4 Hypervisor 选项Hypervisor OptionsHypervisor 注解必须显式列入Kata 运行时配置的白名单enable_annotations后才会生效。示例配置文件中的写法# List of valid annotation names for the hypervisor enable_annotations [enable_iommu, kernel_params]安全警告除非你完全信任所有注解来源否则不要将virtio_fs_extra_args加入enable_annotations。向virtiofsd传递任意参数可能被滥用造成恶意的宿主机侧行为。完整 Hypervisor 注解表如下(R)表示受限注解KeyValue TypeCommentsio.katacontainers.config.hypervisor.asset_hash_typestring资产asset校验使用的哈希类型默认sha512。对应的SHA512常量见 annotations.goio.katacontainers.config.hypervisor.block_device_cache_directboolean是否启用O_DIRECT绕过宿主机 page cacheio.katacontainers.config.hypervisor.block_device_cache_noflushboolean是否忽略设备的 flush 请求io.katacontainers.config.hypervisor.block_device_cache_setboolean是否将 cache 相关选项应用到块设备io.katacontainers.config.hypervisor.block_device_driverstring块设备驱动合法值virtio-blk、virtio-scsi、nvdimmio.katacontainers.config.hypervisor.blk_logical_sector_sizeuint32块设备向 guest 报告的逻辑扇区大小字节。0表示采用 hypervisor 默认值必须是 512 到 65536 之间、2 的幂io.katacontainers.config.hypervisor.blk_physical_sector_sizeuint32块设备向 guest 报告的物理扇区大小字节。0表示 hypervisor 默认必须是 512 到 65536 之间、2 的幂io.katacontainers.config.hypervisor.cpu_featuresstring传递给 CPUQEMU的特性列表逗号分隔io.katacontainers.config.hypervisor.default_max_vcpusuint32hypervisor 为 VM 分配的最大 vCPU 数io.katacontainers.config.hypervisor.default_memoryuint32hypervisor 为 VM 分配的内存单位MiBio.katacontainers.config.hypervisor.default_vcpusfloat32hypervisor 为 VM 分配的默认 vCPU 数io.katacontainers.config.hypervisor.disable_block_device_useboolean禁止将宿主机块设备热插拔到 guest VM 用作容器 rootfs仅 Go 运行时io.katacontainers.config.hypervisor.disable_image_nvdimmboolean是否使用nvdimm设备作为 guest 的 rootfsQEMUio.katacontainers.config.hypervisor.disable_vhost_netboolean宿主机上是否没有vhost-netio.katacontainers.config.hypervisor.enable_hugepagesboolean内存是否从 huge pages 预分配io.katacontainers.config.hypervisor.enable_iommu_platformboolean在 CCW 设备上启用iommuQEMU s390xio.katacontainers.config.hypervisor.enable_iommuboolean在 Q35 上启用iommuQEMU x86_64io.katacontainers.config.hypervisor.enable_iothreadsboolean是否在独立线程中处理 IO。目前支持 virtio-scsi驱动io.katacontainers.config.hypervisor.enable_mem_preallocbooleanhypervisor 为nvdimm设备使用的内存空间是否预分配io.katacontainers.config.hypervisor.enable_vhost_user_storeboolean启用 vhost-user 存储设备QEMUio.katacontainers.config.hypervisor.vhost_user_reconnect_timeout_secstringvhost-user socket 重连超时时间QEMUio.katacontainers.config.hypervisor.enable_virtio_memboolean启用 virtio-memQEMUio.katacontainers.config.hypervisor.entropy_source(R)string宿主机熵源路径/dev/random、/dev/urandom或真实硬件 RNG 设备io.katacontainers.config.hypervisor.firmware_hashstring容器固件 SHA-512 哈希值io.katacontainers.config.hypervisor.firmwarestring运行容器 VM 的 guest 固件io.katacontainers.config.hypervisor.firmware_volume_hashstring容器固件卷 SHA-512 哈希值io.katacontainers.config.hypervisor.firmware_volumestring传递给容器 VM 的 guest 固件卷io.katacontainers.config.hypervisor.guest_hook_pathstringVM 内用于 drop-in hooks 的路径io.katacontainers.config.hypervisor.cold_plug_vfiostringVFIO cold-plug 模式合法值no-port、bridge-port仅 Go 运行时、root-port、switch-port仅 Go 运行时io.katacontainers.config.hypervisor.hot_plug_vfiostringVFIO hot-plug 模式仅 Go 运行时合法值no-port、bridge-port、root-port、switch-portio.katacontainers.config.hypervisor.hypervisor_hashstring容器 hypervisor 二进制 SHA-512 哈希值io.katacontainers.config.hypervisor.image_hashstring容器 guest 镜像 SHA-512 哈希值io.katacontainers.config.hypervisor.imagestring在容器 VM 中运行的 guest 镜像io.katacontainers.config.hypervisor.initrd_hashstring容器 guest initrd SHA-512 哈希值io.katacontainers.config.hypervisor.initrdstring在容器 VM 中运行的 guest initrd 镜像io.katacontainers.config.hypervisor.jailer_hashstring容器 jailer SHA-512 哈希值io.katacontainers.config.hypervisor.jailer_path(R)string约束容器 VM 的 jailerFirecrackerio.katacontainers.config.hypervisor.kernel_hashstring容器内核镜像 SHA-512 哈希值io.katacontainers.config.hypervisor.kernel_paramsstring附加的 guest 内核参数io.katacontainers.config.hypervisor.kernelstring用于启动容器 VM 的内核io.katacontainers.config.hypervisor.machine_acceleratorsstringhypervisor 的机器级加速器io.katacontainers.config.hypervisor.machine_typestringhypervisor 模拟的机器类型io.katacontainers.config.hypervisor.memory_offsetuint64hypervisor 为nvdimm设备使用的内存空间偏移io.katacontainers.config.hypervisor.memory_slotsuint32分配给 VM 的内存槽位io.katacontainers.config.hypervisor.msize_9puint329p 共享的msizeio.katacontainers.config.hypervisor.pathstring运行容器 VM 的 hypervisor。路径必须被运行时配置中的valid_hypervisor_paths白名单收录io.katacontainers.config.hypervisor.pcie_root_port(无类型标注)PCIe Root Port 设备数量用于热插拔 PCIe 设备QEMUio.katacontainers.config.hypervisor.shared_fsstring共享文件系统类型virtio-9p或virtio-fsio.katacontainers.config.hypervisor.use_vsockboolean是否使用vsock与 agent 通信io.katacontainers.config.hypervisor.vhost_user_store_path(R)stringvhost-user 设备相关目录、socket 与设备节点的存放路径QEMUio.katacontainers.config.hypervisor.virtio_fs_cache_sizeuint32virtio-fs DAX cache 大小单位MiBio.katacontainers.config.hypervisor.virtio_fs_cachestringvirtio-fs 缓存模式合法值always、auto、neverio.katacontainers.config.hypervisor.virtio_fs_daemonstringvirtio-fsvhost-userdaemon 路径io.katacontainers.config.hypervisor.virtio_fs_extra_argsstring传递给virtiofsdaemon 的额外参数。安全警告启用此注解可能被滥用造成恶意的宿主机侧行为io.katacontainers.config.hypervisor.enable_guest_swapboolean在 guest 内启用 swapio.katacontainers.config.hypervisor.use_legacy_serialboolean为 guest 控制台使用 legacy serial 设备QEMUio.katacontainers.config.hypervisor.default_gpusuint32VM 所需的最少 GPU 数量。仅由 remote hypervisor 用于实例选择io.katacontainers.config.hypervisor.default_gpu_modelstringVM 所需的 GPU 型号。仅由 remote hypervisor 用于实例选择io.katacontainers.config.hypervisor.block_device_num_queuesusize块设备使用的队列数仅 runtime-rsio.katacontainers.config.hypervisor.block_device_queue_sizeuint32块设备使用的队列大小仅 runtime-rs补充说明资产类注解*_hash与对应的kernel、image、initrd、hypervisor、jailer、firmware、firmware_volume允许用户为单个 Pod指定内核、镜像、固件等资产及其 SHA-512 哈希实现细粒度的启动资产定制与完整性校验。这些常量均定义于 annotations.go。2.5 容器选项Container OptionsKeyValue TypeCommentsio.katacontainers.container.resource.swappinessuint64指定Resources.Memory.Swappiness内存交换倾向io.katacontainers.container.resource.swap_in_bytesuint64指定Resources.Memory.Swap交换空间大小注意容器级注解的前缀是io.katacontainers.container.resource.无config段与其余配置注解不同其常量前缀定义在 annotations.go。三、containerd 配置把注解透传给 Kata对于 containerd从1.3.0版本起Pod spec 中指定的注解会传递给 Kata。此外还需要在 containerd 配置文件中额外提供pod_annotations与container_annotations两个字段。它们是可传给 Kata 作为 OCI 注解的注解列表支持 Golang 匹配模式golang match patterns。由于 Kata 支持的注解遵循io.katacontainers.*模式下面的配置即可将注解从 containerd 传给 Kata$ cat /etc/containerd/config .... [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.kata] runtime_type io.containerd.kata.v2 pod_annotations [io.katacontainers.*] container_annotations [io.katacontainers.*] ....pod_annotations控制Pod 级别注解的透传对应 sandbox 配置container_annotations控制容器级别注解的透传通配模式io.katacontainers.*可一次匹配所有 Kata 注解你也可以改为更精确的模式例如只放行io.katacontainers.config.agent.kernel_modules以缩小暴露面。完整的 containerd Kata 集成步骤可参考仓库内文档 docs/how-to/containerd-kata.md 与 docs/install/container-manager/containerd/README.md。使用 CRI-O 时的注解透传方式可参见 docs/how-to/use-k8s-with-crio-and-kata.md。四、实战示例按 Pod 注入内核模块与启用 guest seccomp正如上文所述并非所有容器都需要相同的内核模块因此把模块列表写死在全局配置文件中会很不灵活。注解恰恰提供了按 Pod 定制配置的能力内核模块与参数列表通过注解io.katacontainers.config.agent.kernel_modules设置以分号分隔每个元素的第一个词视为模块名其余视为其参数用户可能希望启用 guestseccomp以获得更好的隔离以少量性能开销为代价此时可使用io.katacontainers.config.runtime.disable_guest_seccomp注解将其置为false。下面示例创建两个 Pode1000e与i915内核模块只注入到pod1guestseccomp只在pod2中启用apiVersion: v1 kind: Pod metadata: name: pod1 annotations: io.katacontainers.config.agent.kernel_modules: e1000e EEE1; i915 spec: runtimeClassName: kata containers: - name: c1 image: busybox command: - sh stdin: true tty: true --- apiVersion: v1 kind: Pod metadata: name: pod2 annotations: io.katacontainers.config.runtime.disable_guest_seccomp: false spec: runtimeClassName: kata containers: - name: c2 image: busybox command: - sh stdin: true tty: true要点runtimeClassName: kata将 Pod 调度到 Kata 运行时类pod1的注解会被 containerd 透传为 OCI annotationruntime 侧在 pkg/oci/utils.go 中按;常量KernelModulesSeparator定义于 pkg/oci/utils.go切分写入AgentConfig.KernelModulespod2的disable_guest_seccomp: false表示不关闭guest seccomp即显式启用它。4.1 从注解到 guest 内核底层调用链一条kernel_modules注解的完整生效路径如下可从源码逐一印证runtime 解析pkg/oci/utils.go 的addAgentConfigOverrides读取 OCI 注解中的KernelModules按分号切分后存入SandboxConfig.AgentConfig.KernelModulesagent 下发runtime 通过 ttrpc 将kernel_modules列表随 sandbox 创建请求发送给 guest 内 agentguest 加载src/agent/src/rpc.rs 中agent 在创建 sandbox 时遍历req.kernel_modules逐个调用load_kernel_module(m)内部对应modprobe语义完成 guest 内核模块加载。因此注解与配置文件中的kernel_modules项见 src/runtime/pkg/katautils/config.go作用等价但注解方式粒度更细、无需改全局配置。五、受限注解Restricted Annotations机制部分注解是受限的意味着配置文件指定其可接受值。目前只有 hypervisor 注解是受限的出于安全原因——其意图是控制 Kata Containers 运行时将代表你启动哪些二进制。配置文件会同时校验注解的名称name与值value可接受的注解名称由配置文件中的enable_annotations条目定义可接受的值由额外的配置条目提供。由于大多数受限注解用于控制运行时可以执行的二进制合法值通常以 shell 模式给出按glob(3)定义。下表给出每个受限注解对应的配置条目KeyConfig file entryCommentsentropy_sourcevalid_entropy_sources合法熵源如/dev/randomjailer_pathvalid_jailer_paths约束容器 VM 的 jailerFirecracker的合法路径pathvalid_hypervisor_paths运行容器 VM 的合法 hypervisor 路径vhost_user_store_pathvalid_vhost_user_store_pathsvhost-user 相关文件的合法路径virtio_fs_daemonvalid_virtio_fs_daemon_pathsvirtiofsddaemon 的合法路径这些配置项在源码中的对应字段可见于 src/runtime/pkg/katautils/config.goHypervisorPathList、JailerPathList、VirtioFSDaemonList、VhostUserStorePathList、EntropySourceList并随 Hypervisor 配置一起被持久化见 src/runtime/virtcontainers/persist/api/config.go 的EnableAnnotations字段。5.1 默认白名单情况不同发布配置对enable_annotations的默认值不同可直接在仓库配置模板中查看常规 QEMU/CLH/FC 配置使用DEFENABLEANNOTATIONS占位符例如 configuration-qemu.toml.in、configuration-clh.toml.inCoCoConfidential Containers相关配置使用DEFENABLEANNOTATIONS_COCO例如 configuration-qemu-coco-dev.toml.inremote 配置显式列出了白名单如 configuration-remote.toml.in 中的enable_annotations [machine_type, default_memory, default_vcpus, image, default_gpus, gpu_model, cc_init_data]runtime-rs 各配置模板同样包含该机制例如 configuration-clh-runtime-rs.toml.in 中注释以io.katacontainers.config.hypervisor.path为例说明注解名写法。若某注解键不在enable_annotations白名单内即使 Pod 中写了该注解也会被运行时忽略或拒绝这正是对宿主机二进制执行面的安全收敛手段。六、runtime-rs 与 Go 运行时的差异提示仓库同时维护 Go 运行时src/runtime与 Rust 运行时 runtime-rssrc/runtime-rs注解机制在两套实现中大体一致但存在少量差异使用前请留意internetworking_model的l3forwarding取值仅 runtime-rs 支持且为实验性disable_block_device_use仅 Go 运行时支持cold_plug_vfio/hot_plug_vfio的部分取值bridge-port、switch-port仅 Go 运行时支持block_device_num_queues、block_device_queue_size仅 runtime-rs 支持cdh_api_timeout秒对应 Go 运行时cdh_api_timeout_ms毫秒对应 runtime-rs默认分别为50与50000。七、使用建议与安全实践优先使用注解做细粒度定制内核模块、vCPU/内存、块设备缓存策略、共享文件系统等都可以按 Pod 声明避免全局配置一刀切严格收敛enable_annotations仅放行确有必要的键尤其绝不要开放virtio_fs_extra_args对entropy_source、path、jailer_path、vhost_user_store_path、virtio_fs_daemon等可执行二进制相关注解务必配合valid_*条目用glob(3)模式收紧到可预期路径资产哈希防篡改为kernel、image、initrd、firmware等资产同时声明对应*_hash默认sha512可在启动前校验资产完整性确认 CRI 透传配置使用 containerd 时需在 CRI 插件下配置pod_annotations/container_annotations为[io.katacontainers.*]或更窄的模式否则 Pod 注解不会到达 Kata运行时兼容性生产环境请确认所用的运行时实现Go runtime 或 runtime-rs对目标注解的支持情况避免误用仅单侧支持的键。参考与延伸阅读注解键名与语义权威定义src/runtime/virtcontainers/pkg/annotations/annotations.goOCI 注解解析实现src/runtime/pkg/oci/utils.go配置白名单字段src/runtime/pkg/katautils/config.goguest 内核模块加载src/agent/src/rpc.rs配置模板中的enable_annotationssrc/runtime/config/configuration-qemu.toml.in、src/runtime/config/configuration-remote.toml.in相关部署指南docs/how-to/containerd-kata.md、docs/how-to/use-k8s-with-crio-and-kata.md、docs/runtime-configuration.md赞分享云原生容器运行时【免费下载链接】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 实战使用 crictl 通过 CRI 接口在 Kata 运行时中运行与调试 PodKata Containers 实战使用 crictl 通过 CRI 接口在 Kata 运行时中运行与调试 Pod 本文基于 Kata Containers云原生容器运行时Cilium Pod Annotations 详解为 Pod 指定 MAC 地址与禁用源 IP 校验Cilium Pod Annotations 详解为 Pod 指定 MAC 地址与禁用源 IP 校验 Cilium 通过 Pod 级 Annotation 提后端前端AI 技能AI 插件搜索引擎Prowler Kubernetes Pod安全策略容器运行时安全Prowler Kubernetes Pod安全策略容器运行时安全引言容器安全的隐形威胁你是否知道70%的容器安全问题源于配置不当而非镜像本身在Kub网络安全应用安全合规审计风险控制云原生上一篇探索Windows Exploit Suggester智能安全防护的新助力下一篇LightningCLI 高级定制指南为 PyTorch Lightning 打造可扩展的命令行工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

网站建设高端定制企业官网