youki 的 Kubernetes 集成测试指南:基于 Kind 的单节点与多节点部署验证
youki 的 Kubernetes 集成测试指南:基于 Kind 的单节点与多节点部署验证
导读
本文讲解 youki 容器运行时(用 Rust 编写的 OCI 运行时)如何在 Kubernetes 环境中验证自身的正确性:通过 Kind(Kubernetes in Docker)构建包含 youki 的节点镜像并创建集群,再借助 RuntimeClass 将 Pod 调度到 youki 运行时上执行。读完本文,你将掌握 youki 仓库中 just test-kind 与 just test-kind-deploy 两套端到端测试的完整流程、底层实现细节,以及如何清理测试环境。
测试定位:为什么需要 Kubernetes 端到端测试
在 youki 的端到端测试体系中,Kubernetes 测试扮演着"最上层集成验证"的角色。仓库文档 e2e_tests.md 将端到端测试划分为四类:
- rust OCI 测试:验证底层运行时行为;
- containerd 集成测试:验证与 containerd 的配合;
- OCI runtime-tools:验证符合 OCI Runtime Spec;
- Kubernetes 测试:验证 youki 能作为 Kubernetes 容器运行时正常工作。
Kubernetes 测试的核心目标是回答一个实际问题:当 youki 被 containerd 以 io.containerd.runc.v2 风格的 runtime 插件方式注册、并被 kubelet 调度启动时,能否顺利创建并运行容器。这要求测试环境尽可能贴近真实集群的软件栈,而 Kind 恰好提供了低成本、可复现的方案——它把整个控制平面和节点都跑在 Docker 容器里,非常适合 CI 和本地验证。
youki 仓库为此准备了两套测试路径(定义在根目录 justfile 中):
- 单节点部署测试(
test-kind):构建一个预装了 youki 的自定义 Kind 节点镜像,创建单节点集群,部署使用 youki 运行时的 nginx Pod。 - 多节点部署测试(
test-kind-deploy/kind-deploy):节点保持 vanillakindest/node镜像不变,通过运行在每个节点上的 DaemonSet 在运行时把 youki 安装进宿主机并注册到 containerd——这种方式更贴近真实生产集群的安装形态。
单节点部署测试:把 youki 烧进节点镜像
测试流程总览
文档 kubernetes_test.md 对单节点测试的描述是:"构建一个自定义 Kind 节点镜像(内置 youki),创建集群,然后使用指定 youki 为运行时的 RuntimeClass 部署 nginx Pod。" 本地执行命令只有一条:
$ just test-kind
该命令对应的 justfile 任务为:
test-kind: kind-cluster
kubectl --context=kind-{{ KIND_CLUSTER_NAME }} apply -f tests/k8s/runtimeclass.yaml -f tests/k8s/deploy.yaml
kubectl --context=kind-{{ KIND_CLUSTER_NAME }} wait deployment nginx-deployment --for condition=Available=True --timeout=90s
kubectl --context=kind-{{ KIND_CLUSTER_NAME }} get pods -o wide
kubectl --context=kind-{{ KIND_CLUSTER_NAME }} delete -f tests/k8s/runtimeclass.yaml -f tests/k8s/deploy.yaml
其中 KIND_CLUSTER_NAME 固定为 youki。整个链路可以拆解为四步:
- 构建自定义 Kind 节点镜像(
kind-cluster私有任务):通过 Docker buildx 多阶段构建生成包含 youki 的节点镜像; - 创建 Kind 集群:
bin/kind create cluster --name youki --image=<自定义镜像>; - 应用清单并验证:先应用 RuntimeClass 与 nginx Deployment,
kubectl wait等待 Deployment 可用(超时 90 秒),再用get pods -o wide观察 Pod 所在节点与运行状态; - 清理:删除测试清单(集群本身保留,由
clean-test-kind清理)。
测试前后如需清理已存在的 Kind 集群,文档给出的命令是:
$ just clean-test-kind
对应 justfile 中的 kind delete cluster --name youki。
自定义节点镜像:tests/k8s/Dockerfile 解读
单节点测试的关键在于镜像构建,详见 tests/k8s/Dockerfile。它采用多阶段构建,主要阶段如下:
-
youki-build:基于kindest/node:v1.34.0,安装编译依赖(pkg-config、libsystemd-dev、build-essential、libelf-dev、libseccomp-dev、libclang-dev、libssl-dev)和 Rust 工具链,然后执行:RUN cargo build --release -p youki --features "v1 v2 systemd"注意这里显式开启了
v1、v2、systemd特性——分别对应 cgroup v1 支持、cgroup v2 支持,以及 systemd cgroup 驱动支持,这是 youki 在带 systemd 的节点镜像上正常工作所必需的编译特性。 -
shim:用scratch镜像仅提取编译产物target/release/youki单文件,缩小镜像体积。 -
kind-fetch/kind-bin:下载 Kind 二进制(KIND_VERSION=v0.30.0),供创建集群使用(justfile中bin-kind任务用--target kind-bin把它导出到bin/)。 -
kind-node-base:在kindest/node的 containerd 配置/etc/containerd/config.toml末尾追加 youki runtime 注册段:[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.youki] runtime_type = "io.containerd.runc.v2" [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.youki.options] BinaryName = "/usr/local/bin/youki"这是 containerd CRI 插件注册自定义运行时的标准写法:
runtime_type使用io.containerd.runc.v2(即 shim v2 协议),BinaryName指向 youki 二进制——youki 实现了 containerd 的 shim v2 接口,因此能够以这种方式被 CRI 调用。随后安装运行时依赖libseccomp2,并把shim阶段的 youki 拷贝到/usr/local/bin/。 -
kind-node(默认):执行sed -i 's,SystemdCgroup = true,,' /etc/containerd/config.toml,将所有 runtime 的SystemdCgroup置空,即使用 cgroupfs 驱动(对应SystemdCgroup = false的行为)。
测试清单:RuntimeClass 与 nginx Deployment
单节点测试使用两个清单文件:
tests/k8s/runtimeclass.yaml 定义了 RuntimeClass:
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
name: youki
handler: youki
handler: youki 必须与 containerd 配置中注册的 runtime 段名 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.youki] 完全一致,kubelet 才能找到对应的运行时处理器。
tests/k8s/deploy.yaml 定义了测试负载:
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
selector:
matchLabels:
app: nginx
replicas: 2
template:
metadata:
labels:
app: nginx
spec:
runtimeClassName: youki
containers:
- name: nginx
image: nginx:alpine
ports:
- containerPort: 80
两个副本、使用 nginx:alpine 镜像、通过 runtimeClassName: youki 明确指定运行时。kubectl wait 命令等待 nginx-deployment 的 Available 条件在 90 秒内变为 True,从而证明 youki 能稳定地创建、启动并维持容器运行。
补充变体:systemd cgroup 回归测试
除文档描述的默认流程外,justfile 中还提供了 test-kind-systemd-cgroup 变体(KIND_SYSTEMD_CLUSTER_NAME 为 youki-systemd),用于回归验证 youki 在 systemd cgroup 驱动下的 dbus socket 路径兼容性。其节点镜像构建于 tests/k8s/Dockerfile 的 kind-node-systemd-cgroup 阶段:
FROM kind-node-base AS kind-node-systemd-cgroup
RUN echo ' SystemdCgroup = true' >> /etc/containerd/config.toml
Dockerfile 注释说明了动机:kindest/node 镜像内没有 dbus,因此该测试实际验证的是 youki 对 /run/systemd/private 回退路径的处理(对应 libcgroups crate 中 systemd 控制器的 dbus 客户端实现)。运行方式与清理命令分别为 just test-kind-systemd-cgroup 和 just clean-test-kind-systemd-cgroup,适合在启用 systemd cgroup 的集群场景下做回归验证。
多节点部署测试:用 DaemonSet 在运行时安装 youki
设计思路与 vanilla 节点
多节点测试模拟的是生产集群中的真实安装方式:集群节点本身不预装 youki,保持 vanilla kindest/node 镜像;部署一个 DaemonSet,让它在每个节点上把 youki 装进宿主机、注册进 containerd,再运行 nginx 冒烟测试。这样验证的不只是 youki 本身,还包括"在已运行集群中动态安装并注册新运行时"这条运维路径。
按文档 kubernetes_test.md,完整冒烟测试命令为:
$ just test-kind-deploy
若只想搭建集群 + 安装 DaemonSet、跳过 nginx 冒烟测试,则用:
$ just kind-deploy
清理命令:
$ just clean-test-kind-deploy
集群创建:多节点 kind-config
kind-cluster-multi 私有任务使用 tools/youki-deploy/kind-config.yaml 创建集群(名称为 youki-deploy):
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
即一个控制平面 + 两个 worker 节点。任务开头会先检查同名集群是否已存在,存在则直接跳过创建,保证幂等性。
安装器镜像与 DaemonSet 清单
kind-deploy 任务分三步:
kind-deploy: kind-cluster-multi youki-installer-image
kind load docker-image {{ YOUKI_INSTALLER_IMAGE }} --name {{ KIND_DEPLOY_CLUSTER_NAME }}
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} apply -f tools/youki-deploy/youki-deploy.yaml
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} -n youki-system rollout status ds/youki-deploy --timeout=180s
- 构建安装器镜像
youki-installer:latest(tools/youki-deploy/Dockerfile):第一阶段用rust:1-slim-bookworm以--features "v2 systemd"编译 youki 并缓存 cargo 目录;第二阶段基于debian:bookworm-slim,安装util-linux(提供nsenter)、下载 kubectl(KUBECTL_VERSION=v1.34.9,供脚本打节点标签),最终入口为/opt/youki/bin/install-youki.sh; kind load docker-image把安装器镜像导入集群节点;- 应用 tools/youki-deploy/youki-deploy.yaml 并用
rollout status等待 DaemonSet 就绪(超时 180 秒)。
该清单包含四类资源:
-
命名空间
youki-system:带pod-security.kubernetes.io/enforce: privileged标签,允许特权 Pod; -
RuntimeClass
youki:handler: youki,并带调度约束:scheduling: nodeSelector: youki.dev/runtime-ready: "true"只有被打上
youki.dev/runtime-ready=true标签的节点才会承接使用该 RuntimeClass 的 Pod,防止 Pod 在 youki 尚未安装完成时落到节点上; -
ServiceAccount + ClusterRole + ClusterRoleBinding:授权 DaemonSet 的 Pod 对
nodes资源执行get/patch(用于打标签); -
DaemonSet
youki-deploy:hostPID: true、privileged: true,容忍所有NoSchedule/NoExecute污点,挂载宿主机的/usr/local/bin(到/host/usr/local/bin)与/etc/containerd(到/host/etc/containerd)两个 hostPath 卷,并通过 downward API 注入NODE_NAME。
安装脚本 install-youki.sh 逐步解析
DaemonSet 每个 Pod 的入口是 tools/youki-deploy/install-youki.sh,其执行逻辑(可用环境变量均带默认值)如下:
-
拷贝二进制:
install -m 0755 -D /opt/youki/bin/youki "${HOST_BIN_DIR}/youki",把 youki 写入宿主机/usr/local/bin/youki; -
幂等注册 containerd:脚本以
MARKER="# youki-deploy:youki"标记配置段。若配置中已存在该标记则跳过(保证重启 Pod 不会重复追加);否则向宿主机/etc/containerd/config.toml追加:# youki-deploy:youki [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.youki] runtime_type = "io.containerd.runc.v2" [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.youki.options] BinaryName = "/usr/local/bin/youki" SystemdCgroup = false然后通过
nsenter -t 1 -m -u -i -n -p -- systemctl restart containerd进入宿主 PID 1 的命名空间重启 containerd,使新配置生效; -
标记节点就绪:用 kubectl 执行
kubectl label node "${NODE_NAME}" "youki.dev/runtime-ready=true" --overwrite,把该节点标记为可用——此后带runtimeClassName: youki的 Pod 才会被调度上来; -
保持 Pod 存活:
exec sleep infinity,让 DaemonSet Pod 保持 Ready,避免被 kubelet 重启。
这个脚本揭示了多节点方案的核心设计:先安装、后标记、再调度,用节点标签做"安装完成"的闸门。
冒烟测试与验证
test-kind-deploy 任务在 kind-deploy 基础上追加 nginx 冒烟测试:
test-kind-deploy: kind-deploy
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} apply -f tests/k8s/deploy.yaml
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} wait deployment nginx-deployment --for condition=Available=True --timeout=120s
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} get pods -o wide
kubectl --context=kind-{{ KIND_DEPLOY_CLUSTER_NAME }} delete -f tests/k8s/deploy.yaml
流程与单节点测试一致,但等待超时放宽到 120 秒(考虑 DaemonSet 安装已计入前面 180 秒的 rollout)。由于 RuntimeClass 的 nodeSelector 约束,nginx 副本只会调度到已被打上 youki.dev/runtime-ready=true 标签的 worker 节点上,kubectl get pods -o wide 输出的节点列可以直接验证这一点。
测试命令速查与清理
| 场景 | 命令 | 说明 |
|---|---|---|
| 单节点测试(完整流程) | just test-kind |
自定义节点镜像 + RuntimeClass + nginx |
| 清理单节点集群 | just clean-test-kind |
kind delete cluster --name youki |
| systemd cgroup 回归测试 | just test-kind-systemd-cgroup |
验证 /run/systemd/private 回退路径 |
| 清理 systemd 集群 | just clean-test-kind-systemd-cgroup |
kind delete cluster --name youki-systemd |
| 多节点:仅搭建 + 安装 | just kind-deploy |
DaemonSet 安装 youki 并注册 containerd |
| 多节点:完整冒烟测试 | just test-kind-deploy |
在 kind-deploy 基础上运行 nginx 测试 |
| 清理多节点集群 | just clean-test-kind-deploy |
kind delete cluster --name youki-deploy |
使用前需要准备 Docker(含 buildx)、just 命令以及 kubectl;仓库通过 bin-kind 私有任务(docker buildx build --target kind-bin)自动下载 Kind 到 bin/ 目录,无需手动安装。所有命令以仓库根目录为工作目录执行。
相关文档与资源导航
- Kubernetes 测试官方文档:本文对应的原始说明;
- e2e 测试总览:四类端到端测试的定位与入口;
- containerd 集成测试:youki 与 containerd 的另一条验证路径;
- rust OCI 测试:底层运行时行为验证;
- 测试资源:节点镜像构建 tests/k8s/Dockerfile、单节点清单 tests/k8s/runtimeclass.yaml 与 tests/k8s/deploy.yaml、多节点清单 tools/youki-deploy/youki-deploy.yaml、安装脚本 tools/youki-deploy/install-youki.sh、安装器镜像 tools/youki-deploy/Dockerfile、集群配置 tools/youki-deploy/kind-config.yaml;
- 任务定义:根目录 justfile 中
test-kind、test-kind-deploy、kind-deploy、clean-*等全部相关目标。
综上所述,youki 的 Kubernetes 测试通过"镜像内置安装"与"DaemonSet 动态安装"两条路径,分别验证了运行时在 Kind 集群中的可用性以及真实集群式的安装注册流程;配合 RuntimeClass 的 handler 映射、containerd shim v2 注册和节点标签调度闸门,构成了一个贴近生产、可本地复现的端到端验证方案。