youki e2e 测试体系全指南:从 Rust OCI 集成测试到 Kind 多节点集群验证
youki e2e 测试体系全指南:从 Rust OCI 集成测试到 Kind 多节点集群验证
本篇技术指南以 e2e 测试总览文档 为骨架,系统梳理 youki(Rust 编写的 OCI 容器运行时)的四层端到端测试体系:Rust OCI 集成测试(contest + runtimetest + test_framework)、containerd 集成测试、OCI runtime-tools 符合性测试、以及基于 Kind 的 Kubernetes 运行时验证。读完本文,你将掌握每个测试的用途、一键运行命令(基于 justfile)、如何编写并注册一个新的集成测试用例,以及如何把 youki 部署进单节点与多节点 Kind 集群做冒烟验证。
测试全景:youki 的四类 e2e 测试
youki 的 e2e(端到端)测试不是单一脚本,而是覆盖从"底层运行时行为"到"上层编排系统集成"四个不同层次的测试集合,由 e2e_tests.md 统一索引:
| 测试类别 | 验证目标 | 核心入口 |
|---|---|---|
| rust oci tests | youki 作为底层容器运行时的原始集成测试(OCI 运行时生命周期行为) | just test-contest |
| containerd integration test | containerd 的集成测试套件以 youki 作为运行时运行 | just containerd-test |
| runtime tools | OCI 官方管理的 runtime-tools 符合性测试(验证满足 OCI Runtime Spec) | just test-oci |
| Kubernetes test | 通过 Kind 验证 youki 作为 Kubernetes 容器运行时正常工作 | just test-kind / just test-kind-deploy |
这四层测试的关系可以这样理解:rust oci tests 与 runtime tools 验证的是"OCI 运行时契约"本身,containerd 测试验证的是"上层容器引擎 + 运行时"的衔接,而 Kind 测试验证的是"Kubernetes + 运行时"在生产形态下的工作状态。它们共同构成 youki 从开发到上线前的质量防线。
第一层:Rust OCI 集成测试(contest)
定位与设计动机
rust_oci_test.md 明确指出,这套测试是 youki 自有的、用于验证底层容器运行时行为的原始集成测试。它的诞生源于一个实际痛点:OCI 官方 runtime-tools 的验证测试用 Go 编写,且其输出解析还依赖 Node.js,这意味着 youki 开发者被迫维护 Go 与 Node 两个额外的语言环境。因此 youki 将这些测试移植为 Rust 实现,形成一个可以随代码变更随时本地运行的测试集(详见 integration_test.md)。
从仓库结构看,这套测试由三个相互协作的 crate 组成,位于 tests/contest 目录:
- contest:测试主程序,负责构造 OCI Runtime Spec、驱动容器生命周期(create/start/exec/kill/delete 等)、汇总测试结果;
- runtimetest:一个静态链接的小二进制,被放入容器内执行,从容器内部验证约束(readonly paths、seccomp、capabilities、cgroup 等)是否真正生效;
- test_framework:通用测试框架 crate,提供
Test、TestGroup、TestManager、TestResult等结构与 trait,contest 基于它组织测试。
运行方式
just test-contest
该命令展开后的实际动作(见 justfile):
sudo scripts/contest.sh ./youki
contest.sh 脚本会依次完成:确认运行时二进制存在、按 CPU 架构选择测试 bundle(优先 bundle-$(uname -m).tar.gz,缺失时回退到 x86_64 的 bundle.tar.gz)、调用 contest run --runtime <runtime> --runtimetest ./runtimetest 运行全部测试,最后通过扫描日志中 not ok 的出现次数判定整体成败。
得益于 test-contest 任务的可选参数(justfile 中的 *TESTNAME),你可以只运行选中的测试组,例如:
just test-contest lifecycle::create,delete cgroups::memory
其测试选择格式在 contest/src/main.rs 中定义:-t group1::test1,test3 group2 group3::test5,即组名后跟 :: 和逗号分隔的用例名,不带 :: 则运行整个测试组。contest 二进制还提供 list 子命令(just contest-list)列出全部已注册测试组。
另外,仓库提供 validate-contest-runc 任务(justfile),以 runc 为被测运行时跑同一套测试,用于在 CI 中验证"测试本身"的正确性——因为 contest 也处于持续开发中。
框架基石:test_framework 的抽象
要理解如何编写测试,先看框架提供的最小抽象(testable.rs):
TestResult:枚举三种结果——Passed(通过)、Skipped(String)(跳过并给出原因,如当前环境不满足前置条件)、Failed(Error)(失败)。它是"扩展版 Result",Ok变体不带值;Testabletrait:要求实现get_name()与run() -> TestResult,can_run()有默认实现(默认 true),用于条件测试;TestableGrouptrait:要求实现get_name()、parallel()、run_all()、run_selected();test_result!宏:把Result<T>快速转换为TestResult,Err 时直接return TestResult::Failed(err),配合From<Result<T>>实现使用。
并行执行是默认行为:TestGroup(test_group.rs)默认 parallel: true,组内测试通过 crossbeam 线程池并发运行;TestManager(test_manager.rs)则按 CPU 核数分批并发执行各测试组,并用 thread::scope 保证线程安全。如果你的测试有先后依赖(例如容器生命周期:必须先 create 再 start 再 stop),需要调用 set_nonparallel() 标记串行,或自行实现 trait 以精确控制执行顺序——这也是 test_framework.md 强调的场景。
完整示例:编写一个 hello world 测试
下面按 rust_oci_test.md 给出的五个步骤,对照仓库中的真实样例 hello_world.rs 逐步讲解。
第 1 步:构建要验证的 OCI Runtime Spec
测试框架会自动把 runtimetest 放入容器,因此常规做法是让 Spec 的进程参数指向 runtimetest <测试名>:
fn create_spec() -> Result<Spec> {
SpecBuilder::default()
.process(
ProcessBuilder::default()
.args(
["runtimetest", "hello_world"]
.iter()
.map(|s| s.to_string())
.collect::<Vec<String>>(),
)
.build()?,
)
.build()
.context("failed to create spec")
}
进程参数 ["runtimetest", "hello_world"] 中的第二个元素,就是 runtimetest 主程序中分发的测试名(见下文第 5 步)。
第 2 步:准备返回 TestResult 的测试函数
fn example_test() -> TestResult {
let spec = test_result!(create_spec());
test_inside_container(&spec, &CreateOptions::default(), &|_| Ok(()))
}
test_inside_container 是 test_utils.rs 提供的核心工具函数:它按 Spec 创建并启动容器,等待容器内进程结束,然后检查其 stderr 是否为空——非空即判定失败。这正是"从容器内部验证约束"的实现机制。
关于 create_container 与 stdio 管道还有一个容易踩的坑(integration_test.md 有专门说明):youki create 进程 fork 出的子进程会一直等待 start 信号才 exec 容器程序,因此如果只是创建容器而没有启动它,对返回的 Child 调用 wait_with_output() 会永久挂起;正确的做法是在调用 start 之后、容器真正运行起来时再收集 stdout/stderr。
第 3 步:创建 TestGroup 并注册用例
pub fn get_example_test() -> TestGroup {
let mut test_group = TestGroup::new("example");
let test1 = Test::new("hello world", Box::new(example_test));
test_group.add(vec![Box::new(test1)]);
test_group
}
TestGroup::new("example") 定义了组名,Test::new("hello world", ...) 定义用例名,二者构成 example::hello world 的完整定位标识。
第 4 步:把 TestGroup 注册进 TestManager
在 contest/src/main.rs 中:
let mut tm = TestManager::new();
let example = get_example_test();
tm.add_test_group(Box::new(example));
TestManager 内部用 BTreeMap 以组名维护全部测试组,还可通过 add_cleanup 注册清理回调(contest 注册了 cgroups::cleanup_v2,用于测试结束后清理 cgroup v2 残留)。
第 5 步:编写容器内的验证逻辑
在 runtimetest 主程序 main.rs 中注册测试名分发:
fn main() {
let spec = get_spec();
let args: Vec<String> = env::args().collect();
let execute_test = match args.get(1) {
Some(execute_test) => execute_test.to_string(),
None => return eprintln!("error due to execute test name not found"),
};
match &*execute_test {
"hello_world" => tests::hello_world(&spec),
// ... 其余测试名分发
_ => eprintln!("error due to unexpected execute test name: {execute_test}"),
}
}
runtimetest 从容器内的固定路径 /config.json 加载 Spec(const SPEC_PATH: &str = "/config.json"),然后在 tests.rs 中实现实际校验:
pub fn hello_world(_spec: &Spec) {
println!("Hello world");
}
验证函数通过 println! 输出正常信息、通过 eprintln! 输出错误;test_inside_container 侧正是依赖"stderr 为空"来判定测试通过。
runtimetest:必须静态链接的原因
runtimetest 之所以独立于主 workspace(runtimetest.md),有两个原因:
- 必须静态链接 crt0:如果动态链接,二进制会依赖
/lib64/ld-linux-x86-64.so.2解释器,而容器内通常没有/lib64目录,二进制将无法运行。可以用以下命令检查:
输出readelf -l path/to/binary | grep "program interpreter"[Requesting program interpreter: /lib64/ld-linux-x86-64.so.2]表示动态链接;无输出则为静态链接。file命令同样可以判断:输出含statically linked即可在容器内运行。 - 避免双重编译开销:runtimetest 依赖
oci-spec、nix等包,这些也是主 workspace 其他 crate 的依赖。若放入同一 workspace,这些依赖需分别按动态(供主工程)与静态(供 runtimetest)编译两次,拖慢开发迭代。独立成 crate 后拥有独立target/目录,改动哪个就只重编哪个。
既有测试覆盖面
contest 的测试覆盖相当广(contest/src/main.rs 中注册了 50+ 个测试组),包括但不限于:cgroups v2 的 cpu/memory/pids、seccomp 与 seccomp notify、容器生命周期(create/start/stop/delete/exec/kill)、hooks(prestart/poststart/poststop 及失败场景)、readonly/masked paths、mount propagation 与递归挂载、hostname/domainname/sysctl、进程 capabilities 及其边界情况、rlimits、oom score adj、uid mappings、网络设备、terminal、checkpoint/restore、scheduler 策略、io priority、memory policy(NUMA)等。runtimetest 侧则通过 /proc、netlink、sched_getattr、ioprio_get 等系统接口做"进程内自证"。
第二层:containerd 集成测试
containerd_integration_test_using_youki.md 说明,该测试的作用是让 containerd 官方集成测试套件以 youki 作为运行时来执行,从而验证 containerd 与 youki 的衔接。
本地运行方式(依赖 Vagrant,见 justfile):
just containerd-test
展开后是 vagrant up containerd2youki 加 vagrant provision containerd2youki --provision-with test,即拉起一台预置了 containerd 与 youki 的虚拟机并执行测试。清理环境使用 just clean-containerd-test(vagrant destroy containerd2youki)。
注意该测试的一键运行是以 Vagrant 虚拟机为前提的,与本机直接跑 just test-contest 不同,需要相应的基础设施准备。
第三层:OCI runtime-tools 符合性测试
runtime_tools.md 说明,这类测试使用 OCI 官方维护的 runtime-tools,作为检验运行时是否满足 OCI Runtime Spec 的测试工具。
本地运行需要先初始化子模块(仓库以 git submodule 形式引用了 runtime-tools 源码,见 tests/oci-runtime-tests):
$ git submodule update --init --recursive
$ just test-oci
test-oci 在 justfile 中展开为 scripts/oci_integration_tests.sh,由脚本驱动 runtime-tools 的验证流程。另外 justfile 中 test-integration: test-oci test-contest 把两层测试合并为一次集成测试入口,而 test-all 则在不包含 rust-oci 的情况下聚合基础单测、特性编译测试与 containerd 测试(说明 contest 套件整体耗时较长,故从默认全量门禁中分离)。
第四层:Kubernetes 测试(Kind)
kubernetes_test.md 说明,该测试通过 Kind(Kubernetes in Docker) 验证 youki 作为 Kubernetes 容器运行时是否工作正常。仓库提供了单节点与多节点两种形态。
单节点部署测试
流程:构建内置 youki 的自定义 Kind 节点镜像 → 创建集群 → 用 RuntimeClass 指定 youki 为运行时 → 部署 nginx Pod 冒烟验证。
$ just test-kind
清理已有集群:
$ just clean-test-kind
其实现细节(justfile):先用 docker buildx 基于 tests/k8s/Dockerfile 构建 kind 节点镜像并加载进 docker,再 kind create cluster 创建名为 youki 的集群;随后 kubectl apply runtimeclass.yaml 与 deploy.yaml,等待 nginx-deployment 可用后 kubectl get pods -o wide 查看运行结果,最后删除资源。RuntimeClass 声明 handler: youki,Deployment 的 Pod 模板通过 runtimeClassName: youki 指定使用 youki。
justfile 中还提供了 systemd cgroup 变体 test-kind-systemd-cgroup(针对 dbus socket 路径的回归测试)及对应清理命令。
多节点部署测试
多节点变体更贴近生产集群的安装方式(kubernetes_test.md):集群节点保持 vanilla 的 kindest/node 镜像,通过在每个节点上运行的 DaemonSet 把 youki 安装到宿主机并在运行时注册进 containerd。
$ just test-kind-deploy
若只想拉起集群与 DaemonSet、跳过 nginx 冒烟测试:
$ just kind-deploy
清理:
$ just clean-test-kind-deploy
实现细节(justfile):kind-cluster-multi 按 kind-config.yaml 创建 1 个 control-plane + 2 个 worker 的三节点集群;youki-installer-image 构建 youki-installer:latest 镜像;kind-deploy 把镜像加载进集群并应用 youki-deploy.yaml,等待 ds/youki-deploy 完成 rollout;test-kind-deploy 随后部署 nginx Deployment 并等待可用。这套流程同时演示了 youki 在 Kubernetes 环境的两种接入模式:自定义节点镜像内置(单节点)与 DaemonSet 动态安装(多节点)。
常见问题与排查要点
- contest 需要 root 权限:
test-contest会以sudo执行 contest.sh,因为容器创建涉及 cgroup、namespace、挂载等特权操作; - runtimetest 无法在容器内运行:优先检查是否静态链接(
file或readelf -l判断),这是文档明确强调的坑; - 测试 hang 住:注意
create_container返回的 Child 在 start 之前不能wait_with_output(),否则会因等待 start 信号而永久阻塞; - 选中测试语法:
-t参数支持组名::用例1,用例2与单独组名两种粒度,可通过just contest-list查看全部注册组名; - bundle 架构回退:contest.sh 优先使用当前架构的 bundle(如
bundle-aarch64.tar.gz),缺失时回退默认 x86_64 bundle,跨架构运行时需留意。
结语
youki 的 e2e 测试体系按"运行时契约 → 容器引擎衔接 → Kubernetes 生产形态"三层递进,覆盖从 contest 的 Rust 原生集成测试(配合静态链接的 runtimetest 与可复用的 test_framework)、containerd 测试的 Vagrant 流程、OCI runtime-tools 符合性验证,到 Kind 单/多节点测试 的完整链路。对运行时开发者而言,just test-contest 与 contest 的"Spec 构造 + 容器内自证"模式是日常迭代中最常使用的工具;对平台工程师而言,test-kind-deploy 则演示了把 youki 引入 Kubernetes 集群的真实安装路径。所有一键命令均可在仓库根目录的 justfile 中追溯其底层实现。