Kata Containers CI 体系深度解析：从 GitHub Actions 工作流到本地调试实战-平芜编程栈

云原生
容器运行时

【免费下载链接】kata-containers

Kata 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 的持续集成（CI）体系基于 GitHub Actions 构建，动作定义位于.github/workflows目录，并通过调用tests目录下的辅助脚本来实际执行每个测试用例。本文以 ci/README.md 为骨架，结合仓库中的工作流文件、Gatekeeper 脚本与测试脚本，完整剖析 Kata Containers 的两级 CI 运行模型（PR 自动预检 + 维护者审批的完整测试矩阵）、四类运行器规格、Required 任务晋级机制，以及如何在本地用kcli复现 CI 环境进行 nerdctl 与 Kubernetes 测试调试的完整实战流程。

[!WARNING] 项目官方文档明确提示：本项目的 CI 尚有多处待改进之处，且仍在持续演进，本文描述的是其当前状态，可能因后续变更出现过时信息。读者在实际使用中如发现异常，欢迎反馈。

CI 总体架构：GitHub Actions + 辅助脚本

Kata Containers 的 CI 完全依托 GitHub Actions 执行，动作（workflow）文件集中存放在.github/workflows目录，目前包含约 60 个工作流文件，覆盖 PR 检查、静态检查、每日构建（nightly）、发布（release）、安全扫描（codeql、govulncheck、osv-scanner）等场景。

关键设计是工作流只负责编排，真正的测试动作由仓库tests目录下的脚本完成。以 nerdctl 测试为例，工作流 basic-ci-amd64.yaml 中的步骤依次调用 tests/integration/nerdctl/gha-run.sh 的install-dependencies、install-kata、run、collect-artifacts四个子命令。这种"薄工作流 + 厚脚本"的架构让测试逻辑可以脱离 GitHub 平台独立运行——这也是本地调试得以实现的基础。

两类工作流：自动预检与审批测试

PR 打开即自动运行的任务

每当 PR 被创建，一批"零成本"（GitHub 免费托管的 runner）预检任务会自动启动，用于评估 PR 是否达到可评审的基本门槛。从 commit-message-check.yaml 可以看到，社区对提交本身的硬性要求包括：

提交信息格式：subject 行不超过 75 个字符、body 行不超过 150 个字符、subject 必须以"子系统"前缀开头（如runtime: fix xxx）；
Developer's Certificate of Origin（DCO）：每个提交必须包含Signed-off-by标记，由tim-actions/dco动作校验；
静态检查（static checks）：由 static-checks.yaml 驱动，包含make static-checks、make check/make test构建检查、go mod tidy一致性校验、protobuf codegen 校验、内核配置版本校验、agent policy 覆盖率检查、broken symlink 检查等众多任务。

文档特别强调：社区期望贡献者在提交 PR 前至少能本地构建通过自己的代码，这是非常合理的要求。

需要维护者批准才能运行的任务

另一部分测试被社区称为"真正的 CI"，它们运行在付费 runner（当前使用 Azure 基础设施）上，因此必须由项目维护者批准。当前触发方式是给 PR 添加ok-to-test标签，社区计划迁移到在 PR review 评论中发送/test命令（ok-to-test标签的约束可以从 required-tests.yaml 中test集合的required-labels字段得到印证）。

批准后依次执行：

构建所有组件（免费 runner 或按架构使用 bare-metal）；
将全部组件打包为 tarball（即kata-static.tar.zst，仓库根 Makefile 中的kata-tarball目标负责产出）；
用 tarball 生成 kata-deploy 部署载荷（供 Kubernetes 集群安装使用）；
执行测试，分为两大族：

依赖 tarball 的测试（免费 runner）：

测试	运行位置
Metrics	bare-metal
docker	免费 runner
nerdctl	免费 runner
kata-monitor	免费 runner
cri-containerd	免费 runner
nydus	免费 runner
vfio	免费 runner

依赖 kata-deploy 载荷的测试：

kata-deploy（免费 runner）：在 k0s、k3s、rke2、Azure Kubernetes Service（AKS）等不同 Kubernetes 发行版上验证部署生命周期；
Kubernetes（Azure 小/中规格实例，以及 TEE bare-metal 机器）：覆盖不同运行时引擎（CRI-O 与 containerd）、containerd 的不同快照器（OverlayFS 与 devmapper），以及全部受支持虚拟机监控器——Cloud Hypervisor、Dragonball、Firecracker、QEMU。

从 ci.yaml 这个总编排工作流可以看到当前真实的全景：仅 cri-containerd 测试就在 amd64 上构成 5 种 VMM × 2 种 containerd 版本共 10 个矩阵组合（ci.yaml），另有 s390x、ppc64le 上的专项组合；Kubernetes 测试则按 AKS、免费 runner、CRI-O、NVIDIA GPU、CoCo（Confidential Containers，含 SEV-SNP TEE 测试）、z/VM（ZVSI）、ppc64le 等维度拆分为独立工作流。

文档提醒：这些 Azure 实例测试每小时都在消耗真实资金，社区请求维护者谨慎使用、避免将其当作免费调试沙箱。

四类 Runner 规格

CI 中使用的 runner 分为四类，规格差异直接影响测试能否本地复现：

类型	规格	说明
免费 runner	GitHub 官方托管，小型、带虚拟化能力	用于预检与轻量测试
Azure small 实例	2 CPU、8GB RAM、带虚拟化能力	名称带`-smaller`后缀（如`garm-ubuntu-2304-smaller`）
Azure normal 实例	4 CPU、16GB RAM、带虚拟化能力	通常是 garm 托管、无`-smaller`后缀
Bare-metal runner	社区贡献者提供，架构/规格不一	构建类 runner 无需虚拟化能力；执行测试的 runner 必须支持虚拟化，且 CPU/RAM 至少对齐 Azure normal 规格

新增测试：从"独立测试"到"更大测试的一部分"

文档建议新增测试前先通读 GitHub Actions 官方文档。在 Kata Containers 中测试分为两类：

独立（standalone）测试：如提交信息检查，直接在单个工作流中完成，本文不展开；
"更大测试的一部分"（part of something bigger）：指那些被并入既有大工作流的测试，是社区重点关注的复杂场景。

[!NOTE] 文档中的 TODO 注明：目前文档以"tests"称呼实际上的 GitHub jobs/workflows。理想情况下（除个别例外），新测试的加入不应需要新增工作流，社区计划改进工作流以支持这一目标。

社区强烈希望新测试自带运行说明 + 一次通过的实测记录（可参考 PR #8115）。添加"更大测试的一部分"只需两步：

新增 yaml 文件，并在"更大"的 yaml 中调用它（参考 Kata Monitor 测试示例）；
新增测试所需辅助脚本（参考 Kata Monitor 脚本示例）。

Required 与 Non-required 任务机制

CI 中任务分为两类：

Required（必需）：必须全部通过 PR 才能正常合并，覆盖希望确保不回归的核心功能；
Non-required（非必需）：用于不稳定测试或实验性、未完全支持的功能，理想情况下也希望通过，但即使失败也不阻塞合并（因为失败不一定意味着 PR 引入回归）。

晋级为 Required 的流程

初始标记标准：新任务或近期未标记为 required 的任务，需连续 10 天测试通过且期间无相关 PR 失败记录；同时需要一名或多名被提名的维护者负责其稳定性（维护者可登记在 CI Dashboard 关联的maintainers.yml中）。
保持 GitHub UI 与 Gatekeeper 同步的流程：
1. 若有新维护者，先创建 PR 更新maintainers.yml；
2. 创建 PR 更新 required-tests.yaml，加入新任务并附上满足上述要求的证据，通知所有维护者与 @kata-containers/architecture-committee 评审（有 PR #11015 作为先例）；
3. 维护者与架构委员会（AC）评审，可在 AC 会议上讨论；
4. PR 合并后通知项目 admin 更新 GitHub UI。

文档中附注说明：这些只是通用准则，Kata 架构委员会拥有最终裁量权，可随时推翻。

Required 任务维护者的职责

由于社区贡献者遍布全球，required 任务因基础设施或测试问题被阻塞会对协作产生较大影响。因此要求：发现问题后，维护者须在一个工作日内确认问题、完成初步调查，然后要么修复，要么在调查/修复期间将任务标记为 non-required。

重新标记为 Required

一旦任务从 required 列表移除，需要连续两次成功的 nightly 测试后才能重新标记为 required。

Gatekeeper 的实现机制

CI Dashboard（kata-containers.github.io）是收集任务稳定性证据的重要资源，其报告的 nightly 测试结果（当前覆盖最近十天）是晋级判断的参考依据。与之配套的 gatekeeper.yaml 工作流在pull_request_target事件上运行，通过 skips.py 计算当前 PR 需要的任务名/正则列表，再由 jobs.py 轮询各工作流运行状态，等待 required 任务全部完成或失败并上报状态。可见 required-tests.yaml 中paths字段按改动文件路径映射所需测试集合（例如改动docs/或任何.md文件只需通过static集合），而test/static集合各自声明了任务名与正则，并绑定ok-to-test标签门禁。

运行测试

在 CI 中运行

维护者：直接给 PR 添加ok-to-test标签即可自动启动测试（未来将切换为 review 评论中的/test命令）；
非维护者：在 Slack 留言或等待维护者评审，由维护者代为触发。

测试失败且疑似测试自身不稳定（flaky）时的操作路径：

定位失败的测试；
点击 "details"；
右上角点击 "Re-run jobs"；
选择 "Re-run failed jobs"；
点击绿色 "Re-run jobs" 按钮。

同时请为该 flaky 测试创建 issue 反馈。

在本地运行

由于本地通常没有 Azure 订阅，无法完全复现 CI 环境，但可以搭建"足够接近"的环境来调试现有测试、或为新测试提供概念验证。基本步骤：

创建与目标 runner 配置匹配的 VM；
生成测试所需 artifact（或用 CI 失败运行的产物）；
按 action 中的步骤执行测试。

下面分别演示非 Kubernetes 与 Kubernetes 测试的调试流程（以 PR #8070 为例，该 PR 当时同时存在 nerdctl 与 Kubernetes 测试失败）。

调试非 Kubernetes 测试（以 nerdctl 为例）

以失败的nerdctl测试为例。它运行在garm-ubuntu-2304-smaller虚拟机上，其中ubuntu-2304是操作系统，smaller表示 2 CPU / 8GB RAM 规格。据此用kcli创建本地 VM：

$ sudo kcli create vm -i ubuntu2304 -P disks=[60] -P numcpus=2 -P memory=8192 -P cpumodel=host-passthrough debug-nerdctl-pr8070

运行测试需要kata-tarball产物（kata-static.tar.zst），两种获取方式：

自行构建：在仓库根目录执行make kata-tarball（对应 Makefile 中的目标）；
从失败 PR 下载：点击 Job 页左上角 "Summary"，滚动到 artifacts 区域下载。注意 GitHub 不提供 VM 内直链，需在本机下载后用scp拷贝进 VM；且这些产物仅在全部 job 结束后保留 15 天。

将 tarball 放入 VM 后，登录并克隆开发分支：

$ kcli ssh debug-nerdctl-pr8070 $ git clone --branch feat_add-fc-runtime-rs https://github.com/nubificus/kata-containers

添加 upstream 远程、配置 git 并 rebase 到上游 main：

$ git remote add upstream https://github.com/kata-containers/kata-containers $ git remote update $ git config --global user.email "you@example.com" $ git config --global user.name "Your Name" $ git rebase upstream/main

将 tarball 拷入kata-artifacts目录：

$ mkdir kata-artifacts $ cp ../kata-static.tar.zst kata-artifacts/

[!NOTE] 若从 GitHub 下载的是 zip 压缩包，需先解压才能看到kata-static.tar.zst。

最后按测试对应的 yaml 步骤执行。以run-nerdctl-tests-on-garm.yaml为例（对应仓库中 basic-ci-amd64.yaml 的 nerdctl 段落），注意其中设置了KATA_HYPERVISOR等环境变量，核心步骤为：安装依赖 → 安装 kata → 运行测试：

$ export KATA_HYPERVISOR=dragonball $ bash ./tests/integration/nerdctl/gha-run.sh install-dependencies $ bash ./tests/integration/nerdctl/gha-run.sh install-kata $ bash tests/integration/nerdctl/gha-run.sh run

gha-run.sh 内部机制

tests/integration/nerdctl/gha-run.sh 揭示了测试脚本与工作流协作的细节：

install-dependencies安装 wget、pip，通过 pip 安装lastversion获取 nerdctl 最新版本号，下载nerdctl-full-*tarball 解压到/usr/local/，启动 containerd 并生成默认配置；当 hypervisor 不支持共享文件系统时（kata_hypervisor_runs_without_shared_fs），还会额外安装 erofs-utils 并配置 erofs 快照器；
run依次执行：先用 runc 跑一次 nerdctl 冒烟测试作为对照，创建 ipvlan（ipvlan10，以宿主eth0为 parent）与 macvlan（macvlan20）网络以及foo/bar两个 bridge 网络，然后分别以io.containerd.kata-${KATA_HYPERVISOR}.v2运行时运行 nerdctl 容器——覆盖默认网络、多 bridge 网络、ipvlan、macvlan 共 4 种网络场景，最后清理网络；
collect-artifacts用journalctl --since=${start_time}收集日志到/tmp/artifacts，供 CI 上传归档（工作流中Archive artifacts步骤以retention-days: 1保留）。

由此，你应能在本地复现 CI 中的完全一致的问题，之后即可自行构建代码、使用自己的二进制进行调试。

调试 Kubernetes 测试

Kubernetes 测试的调试步骤与上述类似，但所需的不是kata-static.tar.zst，而是供 kata-deploy 使用的部署载荷。

自行生成：先构建自己的kata-static.tar.zst，再借助打包脚本生成并上传 kata-deploy 镜像（该镜像必须能被测试 VM 访问）；
复用 CI 失败产物（更简单）：查看失败 job → 点击 "Deploy Kata" → 展开 "Final kata-deploy.yaml that is used in the test" 段落，即可看到本地集群部署 kata-deploy 所需的准确内容。

[!NOTE] 文档中此节标注 TODO，计划由维护者基于其"run a local CI"的 PR 补充完整。

新增 Runner

只有项目 admin 可以添加/移除 GitHub runner，普通成员如有需求应在 Kata Containers Slack 中 @ac 寻求帮助。admin 操作路径：

进入 kata-containers/kata-containers 仓库；
右上角点击 Settings；
左侧 "Code and automation" 下点击 Actions；
点击 Runners；
添加：右上角绿色按钮 "New self-hosted runner"；
移除：每个 runner 的 "..." 菜单中点击 "Remove runner"。

已知限制

由于当前 GitHub Actions 的结构，无法在 PR 中测试一个不受pull_request事件触发的 GitHub action 的添加——即新增工作流若不由 PR 事件触发，其行为无法在合并前被 CI 验证。

关键文件速查

用途	路径
CI 总编排工作流	.github/workflows/ci.yaml
PR 提交信息检查	.github/workflows/commit-message-check.yaml
静态检查	.github/workflows/static-checks.yaml
Gatekeeper 门禁工作流	.github/workflows/gatekeeper.yaml
Required 任务清单	tools/testing/gatekeeper/required-tests.yaml
Gatekeeper 计算逻辑	tools/testing/gatekeeper/skips.py、tools/testing/gatekeeper/jobs.py
nerdctl 测试脚本	tests/integration/nerdctl/gha-run.sh
基础 amd64 测试工作流（含 nerdctl/docker/agent-apis）	.github/workflows/basic-ci-amd64.yaml
kata-tarball 构建目标	Makefile