youki 集成测试深度指南:Rust 移植版 OCI 运行时验证测试(contest)的原理与实战
youki 集成测试深度指南:Rust 移植版 OCI 运行时验证测试(contest)的原理与实战
导读
本文围绕 youki 仓库中 Rust 移植版 OCI 运行时集成测试展开,讲解这套测试为何从 Go 版 OCI runtime-tools 验证套件移植而来、测试代码在仓库中的布局与构建方式,以及 create_container、test_outside_container、test_inside_container 等核心测试辅助函数的底层原理与调用约定。读完本文,你将掌握如何构建、运行、筛选这套集成测试,并能基于源码理解 youki create 与 start 之间的进程与 stdio 管道协作机制,以及如何在容器内部验证 OCI 约束是否真正生效。
背景:为什么要把 OCI 验证测试从 Go 移植到 Rust
youki 的集成测试套件(文档撰写时位于 /tests/integration_test/,当前仓库中对应 tests/contest/contest 下的 contest crate)本质上是 OCI runtime-tools 集成测试的 Rust 移植版,其核心目标是验证运行时是否符合 OCI Runtime Spec 的约定。
最初 youki 直接使用 OCI 官方仓库中提供的验证测试实现(runtime-tools validation,使用 Go 编写)。直接沿用这套测试会带来三个现实问题:
- 多语言环境依赖:Go 测试需要开发者同时具备 Rust 与 Go 两套编译环境才能编译 youki 并进行测试。
- 潜在的第三门语言依赖:验证测试本身还可选依赖 Node.js 来解析其输出,这使得依赖链可能扩展到三门语言。
- 本地运行困难:这些测试在部分本地系统上运行时会暴露问题,导致难以在本地环境稳定执行。
而容器运行时本身是复杂的系统软件,开发者在修改某一部分代码时,迫切需要一套能在本地随时运行、且能快速回归的测试,以确认改动没有意外破坏其他功能模块。因此 youki 团队决定将测试移植为 Rust,从而同时拥有一套单元测试与一套集成测试来验证运行时行为。
需要说明的是,这套测试仍处于开发完善阶段,其配套测试本身也在 GitHub CI 中先针对 runc 这类标准运行时运行,以校验测试自身的正确性(即"用标准实现校验测试用例是否合理")。开发者文档 docs/src/developer/basics.md 也提到,项目提供 test(单元测试)、oci-integration-test(OCI 官方 Go 集成测试)与 integration-test(本文介绍的 Rust 移植版)三套测试目标,可见 Rust 移植版是独立于 OCI 官方 Go 套件之外的另一条验证路径。
测试代码在仓库中的布局与构建
当前仓库中,这套测试由两个部分构成:
- 测试驱动端:contest crate,位于 tests/contest/contest。它负责生成容器 bundle、调用被测试的运行时(youki 或 runc)、驱动容器生命周期并收集结果。
- 容器内验证端:runtimetest crate,位于 tests/contest/runtimetest。它提供一个在容器内部运行的二进制,用于从容器进程内部验证各项限制与约束是否真正生效。
构建:contest 与 runtimetest 需要分开编译
scripts/build.sh 展示了二者的构建方式(-c contest):
# 构建 contest 测试驱动
"$CARGO_SH" build ${OPTION} "${FEATURES[@]}" --bin contest
mv ${ROOT}/target/${TARGET}/${VERSION}/contest ${OUTPUT}/
# 构建 runtimetest,必须静态链接
CONTEST_TARGET="$ROOT/contest-target"
CARGO_TARGET_DIR=${CONTEST_TARGET} RUSTFLAGS="-Ctarget-feature=+crt-static" \
"$CARGO_SH" build ${OPTION} "${FEATURES[@]}" --bin runtimetest
mv ${CONTEST_TARGET}/${TARGET}/${VERSION}/runtimetest ${OUTPUT}/
注意这里的关键细节:runtimetest 必须使用 -Ctarget-feature=+crt-static 静态链接编译,并且使用独立的 CARGO_TARGET_DIR(contest-target 目录),与工作区其他 crate 的目标目录隔离。原因详见下文"runtimetest 与静态链接"一节。
contest 的命令行接口
contest 的入口在 tests/contest/contest/src/main.rs,使用 clap 定义了 run 与 list 两个子命令:
contest run --runtime <runtime路径> --runtimetest <runtimetest路径> [-t 测试组::用例,用例 测试组...]
contest list
--runtime:待测容器运行时的可执行文件路径(可以是相对路径,若在$PATH中也可以直接给名字,见get_abs_path的解析逻辑)。--runtimetest:容器内验证二进制路径。-t/--tests:选择要运行的测试,格式为空格分隔的测试组,例如-t group1::test1,test3 group2 group3::test5;不传则运行全部测试(test_manager.run_all())。
主程序在 main.rs 中通过 TestManager 注册了数十个测试组:生命周期(lifecycle)、钩子(hooks,含 prestart/poststart/poststop 及其失败场景)、cgroups v2 的 cpu/memory/pids、seccomp 与 seccomp_notify、state、只读路径、hostname、mount propagation、uid 映射、exec、终端、checkpoint/restore、update 等,并注册了 cgroups v2 的清理钩子(tm.add_cleanup(Box::new(cgroups::cleanup_v2)))。
运行集成测试:scripts/contest.sh 实战
仓库提供了开箱即用的运行脚本 scripts/contest.sh:
./scripts/contest.sh <runtime路径> [测试组选择参数...]
脚本逻辑如下:
- 校验传入的 runtime 路径或
$PATH中的名字是否存在; - 若仓库根目录没有
bundle.tar.gz,则按uname -m选择架构对应的 bundle 压缩包(如tests/contest/contest/bundle-aarch64.tar.gz),找不到则回退到默认的bundle.tar.gz并给出警告; - 执行
contest run --runtime "$RUNTIME" --runtimetest "${ROOT}/runtimetest"(带-t "$@"时只跑指定测试组),输出同时写入test.log; - 统计
test.log中 "not ok" 的个数,若大于 0 则以非零状态退出,否则输出 "Validation successful for runtime $RUNTIME"。
bundle 解包与配置写入由 support.rs 中的 prepare_bundle 完成:它把 bundle tarball 解压到临时目录,然后用默认 Spec 覆盖 config.json(默认进程为 sleep 10),最后通过 set_config 将测试自定义的 spec 写入 bundle/config.json。每次测试都会调用 generate_uuid 生成随机容器 ID,保证测试之间的隔离。
深入 create_container:stdio 管道与进程生命周期陷阱
create_container 是测试工具箱中最核心也最容易踩坑的函数,定义在 test_utils.rs。它实际构建的命令等价于:
<runtime> --root <dir>/runtime create <id> --bundle <dir>/bundle [--no-pivot] [额外参数]
其底层实现关键点在于:命令的 stdout 与 stderr 都被设置为 Stdio::piped()(见 test_utils.rs 中的 create_container_command),函数返回的是 std::process::Child 结构体。
为什么 wait_with_output() 会导致挂起
文档中反复强调的一个陷阱是:对 create_container 返回的 Child 直接调用 wait_with_output() 会让测试挂起。理解这一点的关键在于 youki create 的进程模型:
youki create进程启动后会 fork 出一个子进程;- fork 出来的子进程会一直等待另一个 youki 进程向它发送
start信号; - 收到信号后,该 fork 出的进程才 exec 容器内的程序(详见 youki 开发者文档 中对 create/start 生命周期的说明)。
对应地,stdio 的处理方式是:在 create 函数中把原始 youki 进程的 stdio 设为 Stdio::piped(),同时 spec 中的 terminal 选项保持默认的 false,使容器以 pass-through(直通)模式运行。当 create 进程完成它的工作、fork 出的进程在等待 start 信号时,它们仍在使用同一套 stdio 管道。因此:
- 若只是单纯创建容器(如
test_outside_container场景),直接调用wait_with_output()会因管道始终不关闭而挂起,应调用wait(); - 若确实要启动容器并获取容器内程序的输出,则必须先持有
create返回的 Child 结构体,在对其调用start命令之后再调用wait_with_output(),此时才能从youki create的进程中拿到容器内进程的stdout与stderr。
这套 stdio 直通模式与 runc 文档中描述的 detached pass-through 模式原理一致,也是 test_inside_container 能够拿到容器内 runtimetest 输出的根基。
实用建议
- 不确定场景时优先
wait(),避免挂起; - 需要容器内输出时,严格遵守"先 start、后 wait_with_output"的顺序;
- 若
start失败,可以先对 create 进程执行wait_with_output(),防止其成为僵尸进程(test_utils 源码中的错误处理正是这么做的)。
test_outside_container:在宿主机侧验证容器状态
test_outside_container(test_utils.rs)适用于从宿主机侧验证容器行为(例如检查创建是否成功、状态是否正确)的场景。其流程为:
- 生成 UUID 作为容器 ID;
prepare_bundle准备 bundle 并set_config写入测试 spec;create_container(...).wait()创建容器并等待 create 进程退出;- 调用
get_state获取容器状态输出,解析成State结构; - 组装
ContainerData(包含 id、state、state_err、create_result、bundle 路径)交给传入的execute_test闭包执行断言; - 清理阶段执行
kill与delete,最后返回测试结果。
其中 State 与 LifecycleStatus 定义于 test_utils.rs:State 包含 ociVersion、id、status、pid、bundle、annotations、created 等字段;LifecycleStatus 枚举为 Creating、Created、Running、Stopped。配套的 check_container_created 会校验 create 退出码、state 是否可取、id 是否匹配、status 是否恰为 created。
测试还提供状态轮询辅助:
get_container_status:解析state命令输出中的 JSON 并映射为LifecycleStatus;is_in_state/wait_for_state:带超时与轮询间隔地等待容器进入期望状态,WaitTarget::Deleted表示"容器已不存在"(用于等待删除完成)。
值得一提的边界处理:对于不创建 mount namespace 的测试(如 ns_itype),容器会把真实 rootfs 挂载到 bundle 上,导致临时目录在 drop 时删除失败。为此 test_outside_container 会检查 spec 的 namespaces 中是否缺少 Mount 类型,若缺失则手动执行 umount2(bundle/rootfs, MNT_DETACH),保证清理完整。
test_inside_container:在容器内部验证约束
test_inside_container(test_utils.rs)用于验证"从容器进程内部看,限制与约束是否真正生效"。它的使用前提与流程如下:
- 测试的 spec 必须以 runtimetest 作为容器进程,即
process.args形如["runtimetest", "<测试名>"]; - 调用方传入一个
setup_for_test闭包,负责在 rootfs 内做必要的测试准备(如创建测试文件、放置预期内容等),它接收 rootfs 路径参数; - 因为 runtimetest 约定从
/config.json读取 spec(见 runtimetest 的 main.rs,常量SPEC_PATH = "/config.json"),测试会把 spec 保存到rootfs/config.json,并把 runtimetest 二进制复制到rootfs/bin/runtimetest; - 调用
create_container创建容器,但不立即 wait,而是sleep约 1000ms 后调用start_container并对其wait_with_output()——因为需要拿到容器内 runtimetest 的输出,若过早 wait 会丢失 stdio(这正是上一节讲述的管道陷阱); - 对 create 进程执行
wait_with_output(),检查其stdout(非空仅告警打印)与stderr(非空即判定测试失败); - 再次
get_state校验容器处于stopped状态(说明容器内进程已自行结束); kill+delete清理,返回TestResult::Passed。
判定的核心约定:容器内的 runtimetest 逐项运行测试,失败的用例会把错误打印到 stderr;test_inside_container 等待测试结束后检查 stderr 是否为空——若非空,则测试判定失败。这与 runtimetest 的职责描述完全一致:"runs the tests one-by-one, and the failing test prints the error to the stderr"。
test_inside_container 的错误处理也比较稳健:若 start 失败,说明 create 大概率也已失败或提前完成,此时对 create 进程补一次 wait_with_output() 避免僵尸进程,再返回失败结果。
runtimetest:容器内的验证程序与静态链接
runtimetest 是集成测试的"容器内探头",源码位于 tests/contest/runtimetest/src/main.rs 与 tests/contest/runtimetest/src/tests.rs。它以第一个命令行参数作为测试名进行分发,目前支持的用例包括 hello_world、readonly_paths、masked_paths、set_host_name、mounts_recursive、seccomp、sysctl、scheduler_policy_*、io_priority_class_*、memory_policy、devices、root_readonly、process、process_capabilities、process_user、process_rlimits、no_pivot、process_oom_score_adj、fd_control、rootfs_propagation、mount_propagation、uid_mappings、net_devices、time_offsets 等(见 main.rs 的匹配表)。
每个验证函数从 /config.json 读取 spec,再结合容器内可见的实际情况做断言。以 validate_hostname 为例:它比较 gethostname() 的实际结果与 spec 中 hostname 字段是否一致,不一致则打印到 stderr。类似地,validate_readonly_paths 逐个检查 readonly paths 的读/写权限(对不存在路径容忍 ENOENT,对写操作期望 EROFS 只读错误)。
为什么必须静态链接
runtimetest 文档(docs/src/developer/e2e/runtimetest.md)给出了明确的约束:runtimetest 必须以静态链接方式编译。原因是:动态链接的可执行文件会在 ELF 头中请求 /lib64/ld-linux-x86-64.so 这类程序解释器,而容器进程通常无法访问宿主机的 /lib64 目录,因此动态链接二进制无法在容器内运行。
验证一个二进制能否在容器内运行有两种方式:
readelf -l path/to/binary | grep "program interpreter"
- 若输出
[Requesting program interpreter: /lib64/ld-linux-x86-64.so.2],说明是动态链接,无法在容器内运行; - 若无输出,说明不需要程序解释器,可以放进容器运行。
也可以用 file 命令:
file path/to/binary
- 输出
dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2→ 动态链接,不可用; - 输出
statically linked→ 静态链接,可用。
独立 target 目录的设计考量
文档还解释了 runtimetest 被独立出工作区的原因:若放在公共 workspace 中,runtimetest 依赖的 oci-spec、nix 等 crate 会同时以动态与静态两种方式各编译一遍(因为 runtimetest 静态链接、其他 crate 动态链接),递归依赖链都要编译两次,极大拖慢开发/新增测试时的编译速度。独立出来后,runtimetest 使用自己的 contest-target 目标目录缓存静态编译产物,工作区用 target/ 缓存动态编译产物,从而做到"只重编有改动的 crate"。仓库的 scripts/build.sh 正是通过 CARGO_TARGET_DIR=${CONTEST_TARGET} 与 RUSTFLAGS="-Ctarget-feature=+crt-static" 实现这一隔离的。文档同时提醒:若未来不再需要这种分离或采用其他方案,需注意不要重新引入重复编译问题。
用示例走一遍完整流程:hello_world 测试
example/hello_world.rs 是理解整套机制的最小范例。它定义了一个名为 example 的测试组,包含 hello world 测试:
create_spec使用SpecBuilder+ProcessBuilder构造 spec,进程参数为["runtimetest", "hello_world"]——即容器启动后运行容器内的 runtimetest,并分发到hello_world用例;example_test调用test_inside_container(&spec, &CreateOptions::default(), &|_| Ok(())),setup 闭包为空操作;- 容器内的 runtimetest 命中
hello_world,执行tests::hello_world——它调用println!("Hello world")输出到 stdout(见 tests.rs)。
这里可以看到 stdout 与 stderr 的职责差异:hello_world 打印到 stdout,在 test_inside_container 中只会触发告警("container stdout was not empty, found : ...")而不会判失败;而真正的失败信息约定写入 stderr,一旦 stderr 非空即判定测试失败。这套约定也是编写新容器内测试时需要遵循的规范。
测试选择与框架支持
- 测试组注册:所有测试组在 main.rs 中通过
tm.add_test_group(Box::new(...))注册,每个测试组由test_frameworkcrate(tests/contest/test_framework)的TestGroup/Test/TestManager组织。 - 选择运行:
-t参数支持精确到用例的选择,parse_tests会解析group::test1,test2形式;未传-t则全量运行;contest list可直接列出所有测试组名称。 - 运行时环境变量:support.rs 中的
is_runtime_youki/is_runtime_runc依据RUNTIME_KIND环境变量判断被测试的运行时种类(默认视为 youki),测试用例可据此做条件性断言。
常见问题与排错清单
| 现象 | 原因与对策 |
|---|---|
调用 wait_with_output() 后测试挂起 |
容器已 create 但未 start,stdio 管道未关闭;改为 wait(),或先 start 再取输出 |
| 容器内程序输出丢失 | 在 start 之前就对 create 的 Child 做了 wait;必须保留 Child 并在 start 之后 wait_with_output() |
| ns_itype 等测试残留 bundle 挂载 | spec 未创建 mount namespace 导致真实 rootfs 被挂上 bundle;test_outside_container 已用 umount2(MNT_DETACH) 兜底清理 |
| start 失败后出现僵尸进程 | 对 create 进程补一次 wait_with_output()(源码错误处理路径已覆盖) |
| runtimetest 在容器内 "command not found" | 二进制是动态链接的;用 readelf -l ... | grep "program interpreter" 或 file 验证,并用 -Ctarget-feature=+crt-static 重新构建 |
| 需要确认测试是否全部通过 | 查看 test.log 中是否出现 "not ok"(scripts/contest.sh 已自动据此判定退出码) |
总结
这套 Rust 移植版集成测试(contest + runtimetest)为 youki 提供了不依赖 Go/Node.js 环境的、可本地快速回归的 OCI 合规性验证手段。其核心设计可以概括为三点:驱动端在宿主机侧通过 create/start 的 stdio 管道约定拿容器输出,验证端以静态链接的 runtimetest 在容器内部逐项断言并以 stderr 上报失败,测试选择与构建脚本保证本地开发的高效迭代。相关的进一步资料可在 e2e 测试总览(含 rust_oci_test、containerd 集成测试、OCI runtime_tools、Kubernetes 测试等横向对比)与 runtimetest 文档 中继续查阅。