youki 集成测试深度指南:Rust 移植版 OCI 运行时验证测试(contest)的原理与实战

原创2026-09-27 20:06:041,949 阅读
文章标签:容器运行时云原生

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 编写)。直接沿用这套测试会带来三个现实问题:

  1. 多语言环境依赖:Go 测试需要开发者同时具备 Rust 与 Go 两套编译环境才能编译 youki 并进行测试。
  2. 潜在的第三门语言依赖:验证测试本身还可选依赖 Node.js 来解析其输出,这使得依赖链可能扩展到三门语言。
  3. 本地运行困难:这些测试在部分本地系统上运行时会暴露问题,导致难以在本地环境稳定执行。

而容器运行时本身是复杂的系统软件,开发者在修改某一部分代码时,迫切需要一套能在本地随时运行、且能快速回归的测试,以确认改动没有意外破坏其他功能模块。因此 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路径> [测试组选择参数...]

脚本逻辑如下:

  1. 校验传入的 runtime 路径或 $PATH 中的名字是否存在;
  2. 若仓库根目录没有 bundle.tar.gz,则按 uname -m 选择架构对应的 bundle 压缩包(如 tests/contest/contest/bundle-aarch64.tar.gz),找不到则回退到默认的 bundle.tar.gz 并给出警告;
  3. 执行 contest run --runtime "$RUNTIME" --runtimetest "${ROOT}/runtimetest"(带 -t "$@" 时只跑指定测试组),输出同时写入 test.log;
  4. 统计 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)适用于从宿主机侧验证容器行为(例如检查创建是否成功、状态是否正确)的场景。其流程为:

  1. 生成 UUID 作为容器 ID;
  2. prepare_bundle 准备 bundle 并 set_config 写入测试 spec;
  3. create_container(...).wait() 创建容器并等待 create 进程退出;
  4. 调用 get_state 获取容器状态输出,解析成 State 结构;
  5. 组装 ContainerData(包含 id、state、state_err、create_result、bundle 路径)交给传入的 execute_test 闭包执行断言;
  6. 清理阶段执行 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)用于验证"从容器进程内部看,限制与约束是否真正生效"。它的使用前提与流程如下:

  1. 测试的 spec 必须以 runtimetest 作为容器进程,即 process.args 形如 ["runtimetest", "<测试名>"];
  2. 调用方传入一个 setup_for_test 闭包,负责在 rootfs 内做必要的测试准备(如创建测试文件、放置预期内容等),它接收 rootfs 路径参数;
  3. 因为 runtimetest 约定从 /config.json 读取 spec(见 runtimetest 的 main.rs,常量 SPEC_PATH = "/config.json"),测试会把 spec 保存到 rootfs/config.json,并把 runtimetest 二进制复制到 rootfs/bin/runtimetest;
  4. 调用 create_container 创建容器,但不立即 wait,而是 sleep 约 1000ms 后调用 start_container 并对其 wait_with_output()——因为需要拿到容器内 runtimetest 的输出,若过早 wait 会丢失 stdio(这正是上一节讲述的管道陷阱);
  5. 对 create 进程执行 wait_with_output(),检查其 stdout(非空仅告警打印)与 stderr(非空即判定测试失败);
  6. 再次 get_state 校验容器处于 stopped 状态(说明容器内进程已自行结束);
  7. 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 测试:

  1. create_spec 使用 SpecBuilder + ProcessBuilder 构造 spec,进程参数为 ["runtimetest", "hello_world"]——即容器启动后运行容器内的 runtimetest,并分发到 hello_world 用例;
  2. example_test 调用 test_inside_container(&spec, &CreateOptions::default(), &|_| Ok(())),setup 闭包为空操作;
  3. 容器内的 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_framework crate(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 文档 中继续查阅。

登录后查看全文
youki