Rancher v2prov 集成测试指南基于 CAPR 与 systemd-node 的端到端验证体系【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher导读v2prov是 Rancher 新一代 provisioning-v2provisioning.cattle.io集群管理能力的端到端e2e测试套件位于仓库的 tests/v2prov 目录。它运行在单节点集群上通过真实拉起 K3s / RKE2 下游集群验证 v2prov 与 CAPRCluster API for Rancher的完整链路包括集群创建/删除、节点池nodepool编排、自建节点Custom接入以及加密密钥轮换、证书轮换、etcd 快照备份与恢复等 Day-2 运维操作。读完本文你将掌握 v2prov 测试的分类体系、命名规则、本地运行方法与关键环境变量并能结合源码理解其底层运行机制。测试套件概览设计目标与运行前提v2prov 集成测试的核心设计目标是在单节点集群上运行源码注释明确说明这一点原因是 Custom 测试依赖 HostPath 卷对v2prov CAPR的组合进行 e2e 验证使用systemd-node即 rancher/systemd-node 容器镜像模拟真实的系统节点让被测的下游集群进程K3s / RKE2、rancher-system-agent以接近生产的方式运行。这些测试是资源密集型的因此仓库特意将测试按类别组织、以固定命名格式区分避免单个 CI 流水线阶段被“塞满”从而保证每个 pipeline stage 的负载可控。目录结构速览路径职责tests/v2prov/clients构造面向 v2prov 测试的 Kubernetes 客户端wrangler Context CAPI Factory Dynamic controller-runtime clienttests/v2prov/cluster集群对象创建、Custom/Import 注册命令获取、等待创建/删除、调试数据收集tests/v2prov/systemdnode以 Pod 形式创建 systemd-node模拟 Custom 集群节点tests/v2prov/defaults默认镜像、K8s 版本、通用集群配置、重试退避参数tests/v2prov/tests实际测试用例按类别分子目录tests/v2prov/operationsDay-2 运维测试的公共执行逻辑如加密密钥轮换tests/v2prov/wait基于 watch 的等待/重试工具tests/v2prov/DEBUG.md调试数据解码说明测试类别体系README 中描述了四类主要测试而源码中还新增了若干补充类别下面逐一说明。General通用校验General 测试用于验证 Rancher 全局设置是否符合预期。最典型的是 tests/v2prov/tests/general/general_test.go 中的三个用例Test_General_SystemAgentVersion读取system-agent-version设置断言非空且等于环境变量CATTLE_SYSTEM_AGENT_VERSIONTest_General_WinsAgentVersion校验wins-agent-version与CATTLE_WINS_AGENT_VERSION一致Test_General_CSIProxyAgentVersion校验csi-proxy-agent-version与CATTLE_CSI_PROXY_AGENT_VERSION一致。这些版本号由 scripts/provisioning-tests 从package/Dockerfile的ENV CATTLE_SYSTEM_AGENT*系列变量中解析并导出测试运行时直接与 Rancher 的 Setting 比对确保镜像构建产物与运行时行为一致。另外tests/v2prov/tests/autoscaler/autoscaler_test.go 中的Test_General_RKEMachinePool_Autoscaling_Field_Validation也属于 General 范畴专门校验机器池自动扩缩容字段的准入校验逻辑。Provisioning_MP机器供给nodepool驱动的集群生命周期MPmachine-provisioned测试通过nodepool管理测试基础设施测试代码在provisioningv1.Cluster的RKEConfig.MachinePools中声明机器池每个池通过nodeconfig.NewPodConfig生成PodConfigrke-machine-config.cattle.io/v1引用最终由 CAPR 的 MachineDeployment / MachineSet / Machine 驱动 PodMachine 的创建。典型用例见 tests/v2prov/tests/machineprovisioning/machine_test.goTest_Provisioning_SetA_MP_SingleNodeAllRolesWithDelete单节点全角色etcd controlplane worker创建并删除Test_Provisioning_SetA_MP_MultipleEtcdNodesScaledDownThenDelete多 etcd 节点缩容后删除Test_Provisioning_SetB_MP_FiveNodesUniqueRolesWithDelete五节点角色分离3 etcd / 1 cp / 1 worker的创建与删除Test_Provisioning_SetB_MP_Drain等节点排空drain行为验证。这类测试通常会校验机器数量、角色标签capr.WorkerRoleLabel/capr.ControlPlaneRoleLabel/capr.EtcdRoleLabel、Status.Addresses数量、Spec.Bootstrap.ConfigRef是否已设置并通过clients.ForCluster拿下游集群的 kubeconfig 做深入验证。Provisioning_Custom自建Custom集群测试Custom 测试使用 “Custom” 集群模型测试框架手动创建 systemd-node Pod来模拟加入集群的节点而不是依赖 nodepool。流程以 tests/v2prov/tests/custom/custom_test.go 的Test_Provisioning_Custom_SetA_OneNodeWithDelete为例创建provisioningv1.ClusterRKEConfig为空调用 cluster.CustomCommand等待ClusterRegistrationToken生成并解析出 token拼出--worker --etcd --controlplane ...的加入命令用systemdnode.New创建承载该命令的 Pod等待cluster.WaitForCreate完成随后校验 Machines、标签、plan secret 注解capr.LabelsAnnotation/capr.TaintsAnnotation最后删除集群并等待WaitForDelete完成清理。Custom 测试还覆盖了--label、--taint keyvalue:NoExecute等真实注册参数在 plan secret 中的落盘结果以及删除后通过EnsureMinimalConflictsWithThreshold检查系统 agent 与 Rancher 之间的 secret 更新冲突是否低于阈值SaneConflictMessageThreshold 10见 tests/v2prov/cluster/clusters.go。Operation_MP 与 Operation_CustomDay-2 运维测试Operation 系列是“第二天操作”Day-2 operations测试覆盖加密密钥轮换通过设置RKEConfig.RotateEncryptionKeys.Generation触发见 tests/v2prov/operations/encryptionkeyrotation.go轮换完成后还会向下游集群写入 ConfigMap 验证集群仍可用证书轮换见 tests/v2prov/tests/custom/operation_certificaterotation_test.go 与 tests/v2prov/tests/machineprovisioning/operation_certificaterotation_test.goetcd 快照创建/恢复包括原地恢复in-place与新节点恢复new-node两种路径多 etcd 节点场景见 tests/v2prov/tests/machineprovisioning/operation_etcdsnapshot_newnode_multietcd_test.go。MP 与 Custom 的区别与 Provisioning 系列一致前者由 nodepool 管理基础设施后者由框架手动创建 systemd-node Pod。其他补充类别源码扩展随着测试套件演进仓库还新增了以下类别Fleettests/v2prov/tests/fleet 下的Test_Fleet_Cluster、Test_Fleet_ClusterBootstrap验证 Fleet 纳管下游集群及引导流程PreBootstraptests/v2prov/tests/prebootstrap/prebootstrap_test.go 的Test_PreBootstrap_Provisioning_Flow覆盖预引导阶段Autoscalingtests/v2prov/tests/autoscaler/autoscaling_provisioning_test.go 的Test_Autoscaling_Provisioning验证机器池自动扩缩容Importedtests/v2prov/tests/imported 下的Test_Imported_Operation_*系列验证通过 systemd-node 独立引导 RKE2/K3s 集群后导入 Rancher 的场景涉及 etcd 快照保存/恢复、token 轮换、加密密钥轮换、Day-2 禁用/重新启用节点等CAPRKE2由V2PROV_TEST_CAPRKE2控制的 Docker 基础设施供给测试依赖 Rancher Turtles 部署的 CAPIProvider见 tests/v2prov/defaults/caprke2-providers.yaml。测试命名格式所有测试统一采用如下命名约定目的是让 CI 可以按类别精准筛选避免资源密集的用例挤占同一流水线阶段Test_Category_TestName其中Category即上节列出的类别General、Provisioning、Operation、Fleet、PreBootstrap、Autoscaling、Imported等TestName描述具体场景。多个用例之间还会用SetA/SetB等分组标记区分侧重如Test_Provisioning_SetA_MP_SingleNodeAllRolesWithDelete以及用MP/Custom后缀或前缀区分供给方式。go test -run支持正则匹配因此你可以用一条正则精确指定要跑的用例集合。本地运行环境准备与 make 入口环境前提运行机器需要支持在容器内运行 systemdprivileged 容器宿主需具备相应 cgroup 权限需要能够拉取 systemd-node 等测试镜像测试会启动一个本地 K3s 作为承载 Rancher 的管理集群因此需要 Docker 及 root 权限scripts/provisioning-tests 在启动时会主动将进程迁移到/initcgroup 并开启 subtree controller以支持容器内 systemd。运行全部测试直接执行make provisioning-tests会运行所有 provisioning / general 类测试。其底层入口是 scripts/provisioning-tests脚本会依次完成 cgroup 初始化、启动本地 K3s、构建并运行 Rancher server、部署 Rancher Turtles、预拉取 agent 镜像最终执行go test -run ${V2PROV_TEST_RUN_REGEX} -v -failfast -timeout 60m -p 3 -parallel ${V2PROV_TEST_PARALLELISM} ./tests/v2prov/tests/...默认参数为-failfast、-timeout 60m、-p 3、-parallel 1可通过V2PROV_TEST_PARALLELISM调整。自定义测试范围两个关键环境变量环境变量含义默认值说明V2PROV_TEST_DIST下游集群发行版k3s只能是k3s或rke2脚本会对非法值直接报错退出V2PROV_TEST_RUN_REGEX匹配测试名的正则^Test_(General\|Provisioning\|Fleet)_.*$用于精准筛选用例且脚本会校验其仅含[A-Za-z0-9_()|.^$*]防止注入额外go test参数README 给出的示例V2PROV_TEST_RUN_REGEXTest_Operation_Custom_EncryptionKeyRotation V2PROV_TEST_DISTrke2 make provisioning-tests该命令会用RKE2发行版专门运行Test_Operation_Custom_EncryptionKeyRotationCustom 集群下的加密密钥轮换这一个用例。其他可用环境变量结合 tests/v2prov/defaults/defaults.go 与 scripts/provisioning-tests你还可以通过以下变量进一步控制行为SOME_K8S_VERSION指定下游集群的 Kubernetes 版本为空时脚本按发行版从 KDM 数据解析最新版本也可用K3S_PINNED_VERSION/RKE2_PINNED_VERSION固定版本CATTLE_AGENT_IMAGERancher agent 镜像默认rancher/rancher-agent:head脚本会先检查本地/远端是否存在V2PROV_TEST_PARALLELISMgo test -parallel参数默认1V2PROV_TEST_CAPRKE2及V2PROV_TEST_CAPRKE2_MANIFEST/V2PROV_TEST_CAPRKE2_TURTLES_REF控制 CAPRKE2Docker 基础设施测试及 CAPIProvider 清单来源PRIME_MODE/PRIME_REG_HOSTPrime 镜像仓库场景下为集群追加system-default-registry全局镜像选择器V2PROV_DISTRO_DATA_DIR/V2PROV_PROVISIONING_DATA_DIR/V2PROV_SYSTEM_AGENT_DATA_DIR覆盖 K8s 发行版数据目录、provisioning 数据目录与 system-agent 数据目录V2PROV_ETCD_TMPFS_SIZE管理集群 etcd 目录 tmpfs 大小默认2g。底层机制systemd-node 如何模拟真实节点Custom 与 Imported 测试的核心是 tests/v2prov/systemdnode/systemnode.go 的New函数。它创建两类资源seed ConfigMap存放将要执行的 user-data 脚本/var/lib/cloud/seed/nocloud/user-data脚本即 Custom 注册命令或 imported 节点引导脚本configure ConfigMap写入INVOCATION_ID到/etc/default/rke2-server、/etc/default/rke2-agent、/etc/default/k3s、/etc/default/k3s-agent、/etc/default/rancher-system-agent等路径强制 K3s/RKE2 使用 cgroupfs 而非 systemd 作为 cgroup 驱动源码注释说明这是为了避免 rancher-system-agent 在恢复/重建 server 时的 cgroup 问题。Pod 本身以privileged运行SecurityContext.Privileged: true并做了一系列工程化处理将 etcd 数据目录/var/lib/rancher/rke2/server/db与/var/lib/rancher/k3s/server/db挂载为512Mi 上限的 tmpfsEmptyDir StorageMediumMemory避免磁盘压力导致 fsync 变慢、etcd leader 丢失支持extraDirs参数以host-source:pod-mount格式追加 HostPath 卷这也正是测试要求单节点集群、且依赖 HostPath 的原因Pod 创建后注册OnClose回调在测试收尾时自动删除ConfigMap 则设置OwnerReferences指向 Pod随 Pod 生命周期清理。客户端与等待机制tests/v2prov/clients/clients.go 构建了整套测试客户端基于 wrangler 的Context覆盖 Mgmt / Provisioning / RKE / Core / Batch 等资源显式创建CAPI Factorycluster.x-k8s.iov1beta2因为 CAPR CRD 是运行 v2prov 测试的前提额外的 Dynamic client 与 controller-runtime clientREST 客户端超时设为 30 分钟、禁用限流以适配长耗时 e2e 场景ForCluster通过读取cluster-name-kubeconfigSecret 构造下游集群客户端供测试对下游集群直接执行操作。等待逻辑集中在 tests/v2prov/wait/wait.go基于 watch 实现条件等待DefaultWatchTimeoutSeconds 270045 分钟遇到冲突Conflict时视为未完成继续等待避免瞬时更新冲突导致误报。以WaitForCreate为例tests/v2prov/cluster/clusters.go集群“创建成功”被严格定义为Status.ClusterName非空、Status.Ready、Status.ObservedGeneration Generation、capr.Ready与capr.Provisioned条件为真若配置了机器池还会等待 MachineDeployment 进入Running且副本数匹配、每台 Machine 的NodeRef已分配、管理集群的Ready条件为真。失败排查调试数据解读测试失败时如创建/删除/控制面等待超时cluster.GatherDebugData 会自动收集一份调试数据包并附加在错误信息中内容包括provisioning cluster、RKEControlPlane、mgmt cluster、CAPI Cluster/MachineDeployment/MachineSet/Machine、RKEBootstrap 与模板、infrastructure machine、Pod 日志PodMachine 与 custom 节点 Pod、以及 etcd 快照列表。调试数据是gzip base64 编码的 JSON按 tests/v2prov/DEBUG.md 提供的方式解码echo blob | base64 --decode | gzip -d | jq -r其中 Pod 日志内的换行被渲染为字面量SnewlineG需要额外替换echo podlogblob | base64 --decode | gzip -d | sed -e s/SnewlineG/\n/g对 RKE2 节点还会额外抓取agent/logs/kubelet.log一并打包便于定位 kubelet 层面的问题。小结v2prov 集成测试是 Rancher provisioning-v2 与 CAPR 能力的“试金石”它以 systemd-node 模拟真实节点在单节点管理集群上以近乎生产的方式验证 K3s/RKE2 集群的供给与运维链路。理解其类别体系与命名规范Test_Category_TestName、掌握V2PROV_TEST_RUN_REGEX与V2PROV_TEST_DIST两个核心环境变量即可在本地或 CI 中精准、高效地运行所需的端到端验证。想深入了解测试运行全流程可阅读 scripts/provisioning-tests想扩展新的测试用例可参考 tests/v2prov/tests/custom/custom_test.go 与 tests/v2prov/tests/machineprovisioning/machine_test.go 的既有模式。【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考