企业官网建设流程全解析

• 云原生
• 容器运行时

导读

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 Options）

这两个键由运行时（shim）内部使用，用于标记沙箱与容器，通常不面向最终用户手工设置。其常量定义见 annotations.go 中的BundlePathKey与ContainerTypeKey。

2.2 运行时选项（Runtime Options）

2.3 Agent 选项（Agent Options）

2.4 Hypervisor 选项（Hypervisor Options）

Hypervisor 注解必须显式列入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)表示受限注解）：

补充说明：资产类注解（*_hash与对应的kernel、image、initrd、hypervisor、jailer、firmware、firmware_volume）允许用户为单个 Pod指定内核、镜像、固件等资产及其 SHA-512 哈希，实现细粒度的启动资产定制与完整性校验。这些常量均定义于 annotations.go。

2.5 容器选项（Container Options）

注意：容器级注解的前缀是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。

下面示例创建两个 Pod：e1000e与i915内核模块只注入到pod1；guestseccomp只在pod2中启用：

apiVersion: v1 kind: Pod metadata: name: pod1 annotations: io.katacontainers.config.agent.kernel_modules: "e1000e EEE=1; 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

要点：

1. runtimeClassName: kata将 Pod 调度到 Kata 运行时类；
2. pod1的注解会被 containerd 透传为 OCI annotation，runtime 侧在 pkg/oci/utils.go 中按;（常量KernelModulesSeparator，定义于 pkg/oci/utils.go）切分，写入AgentConfig.KernelModules；
3. pod2的disable_guest_seccomp: "false"表示不关闭guest seccomp，即显式启用它。

4.1 从注解到 guest 内核：底层调用链

一条kernel_modules注解的完整生效路径如下（可从源码逐一印证）：

1. runtime 解析：pkg/oci/utils.go 的addAgentConfigOverrides读取 OCI 注解中的KernelModules，按分号切分后存入SandboxConfig.AgentConfig.KernelModules；
2. agent 下发：runtime 通过 ttrpc 将kernel_modules列表随 sandbox 创建请求发送给 guest 内 agent；
3. guest 加载：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)定义。

下表给出每个受限注解对应的配置条目：

这些配置项在源码中的对应字段可见于 src/runtime/pkg/katautils/config.go（HypervisorPathList、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.in）；
• CoCo（Confidential Containers）相关配置使用@DEFENABLEANNOTATIONS_COCO@（例如 configuration-qemu-coco-dev.toml.in）；
• remote 配置显式列出了白名单，如 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-rs（src/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。

七、使用建议与安全实践

1. 优先使用注解做细粒度定制：内核模块、vCPU/内存、块设备缓存策略、共享文件系统等都可以按 Pod 声明，避免全局配置"一刀切"；
2. 严格收敛enable_annotations：仅放行确有必要的键，尤其绝不要开放virtio_fs_extra_args；对entropy_source、path、jailer_path、vhost_user_store_path、virtio_fs_daemon等可执行二进制相关注解，务必配合valid_*条目用glob(3)模式收紧到可预期路径；
3. 资产哈希防篡改：为kernel、image、initrd、firmware等资产同时声明对应*_hash（默认sha512），可在启动前校验资产完整性；
4. 确认 CRI 透传配置：使用 containerd 时需在 CRI 插件下配置pod_annotations/container_annotations为["io.katacontainers.*"]（或更窄的模式），否则 Pod 注解不会到达 Kata；
5. 运行时兼容性：生产环境请确认所用的运行时实现（Go runtime 或 runtime-rs）对目标注解的支持情况，避免误用仅单侧支持的键。

参考与延伸阅读

• 注解键名与语义权威定义：src/runtime/virtcontainers/pkg/annotations/annotations.go
• OCI 注解解析实现：src/runtime/pkg/oci/utils.go
• 配置白名单字段：src/runtime/pkg/katautils/config.go
• guest 内核模块加载：src/agent/src/rpc.rs
• 配置模板中的enable_annotations：src/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

• 云原生
• 容器运行时