构建机密容器运行时组件

更新历史

• 2026-2-4：创建文档

1. 组件架构概览

运行机密容器涉及三类关键组件，如下图所示，分别部署在宿主机、机密虚拟机以及可信认证服务环境中。

1.1 宿主机侧组件

• kubelet：Kubernetes 节点上的核心代理，负责与 API Server 通信，接收 Pod 调度指令，并通过容器运行时接口（CRI）管理容器生命周期。
• containerd：符合 OCI（Open Container Initiative）标准的工业级容器运行时，作为 kubelet 与底层安全运行时（如 Kata Containers）之间的桥梁。它通过 CRI 接收来自 kubelet 的请求，管理镜像拉取、容器生命周期，并通过 shim 机制与 Kata 运行时交互。
• nydus-snapshotter：辅助机密容器跳过主机端的镜像拉取步骤。
• containerd-shim-kata-v2：Kata Containers 专用的 containerd shim，负责建立 containerd 与 Kata 运行时之间的通信通道。它管理轻量级虚拟机（VM）的生命周期，并将容器操作（如 start、stop、exec）转换为对 kata-agent 的 gRPC 调用，确保每个 Pod 在独立的隔离 VM 中运行。
• 主机内核：宿主机操作系统内核，需启用对机密计算（如海光 CSV）的支持。
• hypervisor：负责创建和管理虚拟机实例，默认使用 QEMU。

1.2 机密虚拟机内部组件

• OVMF：UEFI 固件实现，提供标准化引导环境，用于加载虚拟机内核与 initrd。
• 虚拟机内核：需支持 CSV 等机密计算特性。
• 虚拟机 initrd：初始内存文件系统，包含以下核心服务：
  • kata-agent：接收来自主机 containerd（经由 shim）的容器管理指令。其内置的 image-rs 模块支持在 TEE 内直接从远程仓库拉取并解包容器镜像。
  • attestation-agent（AA）：作为 RATS（Remote ATtestation architecture for Secure Systems）架构中的 Attester，负责收集当前 TEE 环境的运行时证据，并与外部 KBS 服务通信完成远程证明。
  • confidential-data-hub（CDH）：统一的机密资源访问代理，通过 gRPC 或 ttRPC 向容器应用或内部组件提供加密密钥、证书、配置等敏感数据。CDH 本身不存储机密，而是作为客户端向 KBS 等可信资源提供者请求资源。所有请求必须先通过 AA 完成身份与环境证明，确保“仅在合法 TEE 中才可获取机密”。
  • api-server-rest：以 RESTful API 封装 CDH 与 AA 的核心功能，为容器内应用提供标准化、易集成的接口。

1.3 可信认证服务组件

运行在可信环境中的 TEE 认证服务组件：

• KBS（Key Broker Service）：在 RATS 架构中扮演 Relying Party 角色，接收来自 Attester 的证据，提交给 Verifier 验证，并根据策略决定是否返回请求的机密资源。
• AS（Attestation Service）：即 RATS 中的 Verifier，负责验证 TEE 证据的真实性，需结合 RVPS 提供的参考值进行策略评估。
• RVPS（Reference Value Provider Service）：管理可信参考值，为 AS 的验证过程提供必要依据。

2. 构建流程

本文仅关注于构建运行在机密虚拟机中的组件，因为这是在实际使用中需要更多定制和开发的组件。

从源代码出发，构建可部署的机密容器运行时组件（最终用于生成 CoCo Operator 所需的镜像和配置），主要步骤如下：

1. 构建 kata-agent；
2. 构建 Guest Components，包括：attestation-agent、confidential-data-hub、api-server-rest；
3. 构建 Guest Kernel；
4. 构建 initrd 镜像，集成上述 kata-agent、Guest Components 及内核模块；
5. 构建 Kata Artifacts，打包 guest kernel 与 initrd；
6. 构建 Kata Deploy Payload 镜像，使用 Kata Artifacts 更新关键组件；
7. 生成用于部署 CoCo Operator 的 YAML 配置文件。

其中，initrd 支持两种构建方式： （1）Update 模式（默认）

• 基于海光提供的基础 initrd 镜像
• 仅更新已构建的 kata-agent、Guest Components 和内核模块
• 重新打包生成新 initrd
• 适用场景：开发与调试，快速迭代

（2）Full 模式

• 使用 Kata 官方脚本从零构建 rootfs
• 基于完整 rootfs 生成 initrd 镜像
• 适用场景：生产环境，确保镜像完整性和一致性

3. 使用脚本构建

本项目提供了构建脚本，以 build.sh 为入口。同时提供了 Makefile 进行快捷操作。

3.1 前置要求

• 系统环境：需要在基于 RHEL 的发行版（例如 BCLinux、openEuler）上运行，并支持 yum 包管理器；
• 网络环境：需要访问公网以下载源码和依赖；
• 权限要求：必须以 root 用户权限执行；
• 配置文件：根据需要修改 build.conf 文件。

3.2 使用 Makefile 构建

Makefile 提供了便捷的模块化构建接口，支持分步构建或完整构建。

可用构建目标

目标	功能说明
all	根据 build.conf 配置构建所有组件（默认目标）
kata-agent	构建 kata-agent 二进制文件
initrd-update	快速构建 initrd 镜像（update 模式）
initrd-full	完整构建 initrd 镜像（full 模式）
payload-images	构建 payload 相关容器镜像
coco-operator	定制化 coco-operator 部署清单
clean	清理构建结果（output、logs、source 目录）
help	显示帮助信息

3.3 使用 build.sh 脚本

build.sh 是主构建脚本，提供了更灵活的命令行控制选项。

基本用法

# 使用默认配置构建
sudo ./build.sh

# 使用自定义配置文件
sudo ./build.sh --config custom.conf

高级选项

选项	说明	示例
--config FILE	指定配置文件路径	--config my_config.conf
--only-steps STEPS	仅执行指定步骤（逗号分隔）	--only-steps "01_setup_build_env.sh,02_build_kata_agent.sh"
--skip-steps STEPS	跳过指定步骤（逗号分隔）	--skip-steps "04_build_guest_kernel.sh"
--help	显示帮助信息	--help

构建步骤说明

构建过程包含以下 12 个步骤，可通过 build.conf 中的 RUN_* 变量控制：

1. 01_setup_build_env.sh - 初始化构建环境；
2. 02_build_kata_agent.sh - 构建 kata-agent；
3. 03_build_guest_components.sh - 构建 guest-components 各组件；
4. 04_build_guest_kernel.sh - 构建 guest kernel；
5. 05_build_pause_bundle.sh - 构建 pause bundle；
6. 06_build_initrd.sh - 制作定制 initrd 镜像；
7. 07_package_kata_artifacts.sh - 打包 kata artifacts；
8. 08_build_reqs_payload_image.sh - 构建 pre-install reqs-payload 镜像；
9. 09_build_kata_deploy_image.sh - 构建定制的 kata-deploy-csv 镜像；
10. 10_customize_coco_operator.sh - 生成定制化 coco-operator 部署清单；
11. 11_build_kbs_images.sh - 构建 KBS 相关镜像；
12. 12_customize_trustee_operator.sh - 生成定制化 trustee-operator 部署清单。