ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

youki 新手贡献指南:从 Issue、TODO 到 Rust 版 OCI 集成测试的入门路径

youki 新手贡献指南:从 Issue、TODO 到 Rust 版 OCI 集成测试的入门路径 容器运行时云原生【免费下载链接】youkiA container runtime written in Rust项目地址https://gitcode.com/gh_mirrors/yo/youki点击查看免费下载本篇指南面向初次接触 youki 的开发者围绕官方开发者文档 good_places_to_start.md 梳理出一条可落地的入门路径如何从 Issue 标签和 TODO/FIXME 标记中找到适合自己的任务如何通过补充文档注释熟悉底层运行时以及深入 youki 的集成测试体系OCI-runtime-tools 与正在 Rust 化的 contest 测试框架并参与其中。读完本文你将掌握 youki 代码仓库的组织方式、测试运行入口以及“在容器内验证约束”的测试对偶设计原理可以直接动手开始第一次贡献。一、从哪里找到适合新手的任务youki 官方文档给出的第一建议很朴素项目持续演进任何“适合新手”的清单都可能随时过时最可靠的信息源始终是仓库 Issues。官方维护者在 issue 上使用good first issue与help wanted两个标签来标记适合外部贡献者接手的工作前者通常意味着“范围明确、改动量小、有引导”后者则表示“需要帮助欢迎认领”。初次贡献时优先从这两个标签过滤 issue可以在不了解全貌的情况下安全起步。此外源码中遗留的TODO与FIXME注释也是一类任务来源但文档明确提醒并非所有 TODO/FIXME 都适合新手其中一些修复起来相当棘手。从当前仓库看这类标记分散在各 crate 中例如crates/libcgroups/src/v2/devices/bpf.rsBPF 设备过滤器实现crates/libcgroups/src/v2/devices/controller.rs 与 crates/libcgroups/src/v2/devices/emulator.rscgroup v2 设备模拟器crates/libcontainer/src/hooks.rsOCI hooks 执行crates/libcontainer/src/tty.rs伪终端处理crates/liboci-cli/src/checkpoint.rscheckpoint 命令参数你可以用rg TODO|FIXME crates/自行扫描最新状态。处理这类标记前建议先阅读 docs/src/developer/unwritten_rules.md 之类的约定文档并对照对应模块的单元测试避免踩坑。二、从文档注释入手边学底层边改进 API 文档文档推荐的第一类“长期有价值”的入门工作是补充文档注释doc comments。youki 目前对公开 API 和核心结构体的注释覆盖已经不错但仍有不少地方缺少说明性注释和使用示例导致cargo doc生成的文档无法完全充当“使用指南”。这对不了解容器运行时或底层系统机制的初学者尤其友好注释工作迫使你逐行读懂代码而容器运行时涉及命名空间、cgroup、挂载传播、seccomp 等大量 Linux 内核特性阅读过程本身就是一次系统学习。文档同时提醒如果某段代码行为特殊或者不掌握某些背景知识就难以理解务必把找到的参考资料链接补进注释方便后来者。在仓库中跑一遍cargo doc --open即可查看当前的 API 文档覆盖情况。注释的落点通常集中在 crates/libcontainer/src容器生命周期、进程、根文件系统与 crates/libcgroups/srccgroup 控制器这两大核心库上。配合 docs/src/developer/repo_structure.md 了解整体目录后可以挑一个你感兴趣的模块例如 crates/libcontainer/src/process/init/process.rs从结构体与公开函数开始。三、集成测试youki 验证体系的核心战场文档着重强调的第二类入门工作是集成测试——这也是目前 youki 验证体系中变动最活跃、最需要人手的地方。仓库里的集成测试目前分为两套并存体系。3.1 现状OCI-runtime-tools 提供的 Go 测试youki 目前使用 OCI-runtime-tools 驱动执行其工作流程如下从tests/oci-runtime-tests/src/github.com/opencontainers/runtime-tools读取用例列表逐个执行validation/case可执行文件用例覆盖 create、default、delete、hooks、kill、cgroupscpu/memory/pids/hugetlb/devices、mounts、process_capabilities、prestart/poststart/poststop 等场景脚本中test_cases数组即完整清单对特定用例做环境预检如 memory/hugetlb 用例要求/sys/fs/cgroup/memory/memory.memsw.limit_in_bytes存在否则跳过以sudo RUST_BACKTRACE1 RUNTIMEruntime validation/case方式运行并将输出写入log/case.log最后用grep not ok判断失败。这套方案的问题在文档中说得非常直白双语言环境依赖开发者必须同时具备 Rust 和 Go 环境才能编译并测试 youki潜在第三种语言依赖OCI-runtime-tools 的 Validation 测试解析输出时还可选依赖 Node.js本地运行困难部分用例在某些系统环境下存在兼容问题难以在本地稳定复现。脚本注释也印证了这一点例如linux_cgroups_relative_blkio用例因涉及 Linux 内核 5.0 已剔除的特性连 runc 都无法通过linux_process_apparmor_profile需要系统预装特定 AppArmor profilelinux_ns_itype则因 GitHub Action 上的清理步骤挂起而无法启用——这些正是“部分测试在某些环境上难用”的具体实例。3.2 演进用 Rust 重写 OCI 集成测试contest正因如此youki 团队决定将 OCI-runtime-tools 的集成测试移植为 Rust 实现目标是双重的既是 OCI 运行时集成测试的 Rust 版本也让测试能在本地系统轻松运行。移植工作由一个 tracking issue 持续跟进即文档中提到的 issue #361。当前仓库中这项工作对应的是 tests/contest 目录下的三个 crate文档写作时的tests/integration_test路径已迁移至此crate路径职责contesttests/contest/contest测试主体定义测试组、调用运行时命令、管理 bundleruntimetesttests/contest/runtimetest容器内执行的对偶测试程序运行在容器进程内部test_frameworktests/contest/test_framework测试框架基础设施Test、TestGroup、TestManager、条件测试从 tests/contest/contest/src/main.rs 可以看到contest 已覆盖了极其丰富的测试组lifecyclecreate/start/state/kill/delete 全生命周期、hooks、seccomp、seccomp_notify、process、process_capabilities、process_rlimits、cgroupscpu/memory/pids、devices、mount_propagation、rootfs_propagation、uid_mappings、net_devices、time_offsets、checkpoint_restore等等——许多原先在 OCI-runtime-tools 里由于环境问题被注释掉的用例如 delete、hooks、hostname、kill、linux_masked_paths、linux_readonly_paths、process_user 等见 scripts/oci_integration_tests.sh 中被注释的列表都已经或正在 Rust 版中重新实现。由于测试本身也在开发中contest 的结果会先在 GitHub CI 上用 runc 这类标准运行时做交叉验证validate-contest-runc确保是“测试写对了”而不是“运行时碰巧通过”。若你同时熟悉 Go 与 Rust这块正是文档点名推荐的高价值贡献区域。3.3 如何运行测试当前仓库不再使用旧文档提到的 Makefile而是改用justfile见 justfile相关命令一目了然# 单元测试--test-threads1 保证串行 just test-unit # 文档测试 just test-doc # OCI-runtime-tools 官方合规测试 just test-oci # Rust 版 OCI 集成测试contest可追加用例名过滤 just test-contest TESTNAME # 用 runc 交叉验证 contest 测试自身 just validate-contest-runc TESTNAME # 一键跑全部 just test-all其中test-contest与validate-contest-runc最终都会进入 scripts/contest.sh脚本首先根据uname -m挑选架构对应的 bundle 压缩包bundle-arch.tar.gz缺省回退bundle.tar.gz然后以contest run --runtime runtime --runtimetest path [-t testname]执行最后同样通过grep not ok判定失败。注意 contest 测试需要sudo权限且会先在脚本内调用youki-release与contest构建出二进制。四、参与集成测试移植前必须理解的两个机制如果你打算认领集成测试相关的 issue文档特别解释了两个容易踩坑的核心机制这里结合源码做一次完整拆解。4.1 create_container 与 stdio 的“挂起陷阱”contest 的工具函数 tests/contest/contest/src/utils/test_utils.rs 提供了create_container函数用于执行youki create命令。其实现要点是构造命令时把stdout与stderr都设为Stdio::piped()并携带--root、create id、--bundle等参数。理解这个函数的关键是 youki与 runc 一致的 create/start 两阶段设计youki create进程在完成初始化后会fork被 fork 出来的子进程继续等待另一个 youki 进程即youki start发送 start 信号收到信号后才 exec 容器内的用户程序。由于 stdio 管道从一开始就归属于youki create进程因此如果你只想“创建容器”验证资源是否正确创建如test_outside_runtime场景必须调用wait()而不是wait_with_output()——否则会因子进程等待 start 信号而永久挂起如果你真的要启动容器并读取容器内程序的输出则应保留create_container返回的Child先执行 start再调用wait_with_output()此时才能拿到容器内进程的stdout/stderr。这与 runc 文档中描述的 “detached pass-through” stdio 模式一致spec 中terminal默认设为false即 pass-through 模式stdio 管道直接贯通到容器内程序。contest 自身也是这么用的——tests/contest/contest/src/tests/example/hello_world.rs 中先create_container创建容器再由生命周期测试发起 start最后回收输出。4.2 test_inside_container 与 runtimetest 的对偶设计文档强调的另一机制是“如何在容器内部验证约束”这是 OCI 运行时测试与普通 CLI 测试最大的不同很多规范要求如只读路径、权限、seccomp 过滤、rlimits只有从容器进程内部才能真实感知。做法是成对设计外部contest 侧需要此类验证的测试先在 spec 中把容器进程设为runtimetest然后调用test_inside_container(spec, options, setup_fn)。setup_fn负责在启动容器前完成必要的环境准备如构造 spec、放置 fixture 文件。内部runtimetest 侧为每个测试在 runtimetest 中添加对偶实现。从 tests/contest/runtimetest/src/main.rs 可以看到runtimetest 从/config.json加载 OCI spec然后按第一个命令行参数分发到对应验证函数hello_world、readonly_paths、masked_paths、set_host_name、seccomp、sysctl、devices、process_capabilities、process_rlimits、uid_mappings、net_devices、time_offsets……每个函数在容器内部执行断言出错则打印到stderr。汇总判定外部test_inside_container等待容器结束然后检查 stderr 是否为空——非空即视为测试失败。以最基础的 tests/contest/contest/src/tests/example/hello_world.rs 为例create_spec()用SpecBuilder把进程 args 设为[runtimetest, hello_world]example_test()直接调用test_inside_containerruntimetest 侧收到hello_world后执行tests::hello_world(spec)无错误输出即通过。理解这条“外部组装、内部断言、stderr 汇总”的链路是移植或新增一个集成测试用例的前提。五、新手起步检查清单最后把整条路径浓缩成一份可执行的清单阅读用户文档先看 docs/src/user/introduction.md 了解 youki 是什么再按 docs/src/user/basic_setup.md 安装依赖、克隆仓库按 docs/src/user/basic_usage.md 跑通一个容器建立“运行时”的直觉建立测试基线在改动任何代码前先运行just test-unit与just test-contest确认本地基线全绿挑选任务从 Issues 的good first issue/help wanted标签找起或用rg TODO|FIXME crates/扫描代码标记优先选择注释类和集成测试移植类任务边读边记如果是注释类任务把阅读过程中发现的参考资料和“非常识”行为写进 doc comments如果是测试类任务先用just validate-contest-runc跑一遍目标用例理解测试预期小步提交保持改动聚焦单个模块利用仓库的 CI含 runc 交叉验证确认没有破坏其他功能。youki 的贡献门槛并不高——它需要的是对 Linux 系统机制的耐心而非对大型代码库的全知。从补一条注释到移植一个集成测试用例都是被官方文档认可的“好起点”。赞分享容器运行时云原生【免费下载链接】youkiA container runtime written in Rust项目地址https://gitcode.com/gh_mirrors/yo/youki点击查看免费下载相关推荐h2ogpt社区贡献指南新手入门与贡献路径h2ogpt社区贡献指南新手入门与贡献路径 为什么选择贡献h2ogpt h2ogpt是一个100%私有、基于Apache 2.0许可的开源项目支持本地部署AI 应用大模型RAGNLP后端语音计算机视觉TorchTitan 贡献指南从环境搭建、Loss 验证到集成测试的完整贡献路径TorchTitan 贡献指南从环境搭建、Loss 验证到集成测试的完整贡献路径 TorchTitan 是 PyTorch 原生的生成式模型训练平台仓库的人工智能大模型预训练分布式训练强化学习Mesop 贡献指南从 Issue 到代码合入的完整实践路径Mesop 贡献指南从 Issue 到代码合入的完整实践路径 Mesop 是一个面向 AI 应用开发的 Python Web 框架Rapidly buil前端后端Web框架上一篇ThinkPad风扇控制终极指南TPFanControl2完全使用教程下一篇JSPatch GCD API实战清单dispatch_after、dispatch_async_main 等线程调度完全参考创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表