Rancher 本地开发实战指南：构建自定义镜像、Helm 部署与 CAPRKE2 v2prov 集成测试-创锋一号

Rancher 本地开发实战指南：构建自定义镜像、Helm 部署与 CAPRKE2 v2prov 集成测试

【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher

本篇开发指南以仓库 docs/development.md 为骨架，系统讲解在 Rancher 项目中完成一次「本地闭环开发」的完整路径：先用make quick通过 docker buildx 构建自定义架构的 Rancher 镜像，再用 Helm 将自定义镜像部署到集群，最后深入 CAPRKE2 v2prov 本地集成测试的完整环境搭建、运行与清理流程。读完你将掌握 Rancher 镜像的跨架构构建技巧、Helm 覆盖参数的正确用法，以及一套可在本机反复运行的 CAPI + CAPD + CAPRKE2 集成测试配方。

一、快速构建本地容器镜像：`make quick`

在将改动提交到 Pull Request 之前，开发者往往需要先在容器镜像里验证变更是否按预期工作。Rancher 仓库提供了一个便捷脚本make quick（其实现位于 dev-scripts/quick），它基于docker buildx构建，天然支持跨 CPU 架构（cross-building）编译。

针对当前操作系统与架构构建镜像，在仓库根目录执行：

REPO="localhost:5000/my-test-repo/image" TAG="tag" make quick

如果希望为其他架构交叉构建，只需额外设置ARCH变量：

REPO="localhost:5000/my-test-repo/image" \ TAG="tag" \ ARCH="amd64" \ make quick

脚本背后的构建细节

阅读 dev-scripts/quick 源码可以了解该命令的底层实现：

多阶段构建目标：package/Dockerfile 定义了server、agent、server-binary、k3s-images等多个 target。未设置TARGET时，脚本默认构建server与agent两个镜像，产物 tag 分别为${REPO}/rancher:${TAG}和${REPO}/rancher-agent:${TAG}；设置TARGET=binary-server则只产出本地二进制到当前目录，TARGET=k3s-images则导出 k3s 镜像列表。
构建参数自动注入：脚本会从 package/Dockerfile 中提取CATTLE_K3S_VERSION、CATTLE_KDM_BRANCH、CATTLE_HELM_VERSION等版本信息，并从 git 当前 HEAD 取短 commit，随后以--build-arg形式传入，保证镜像内嵌的版本号与源码一致。
调试构建：设置BINARY_DEBUG=true时，脚本会移除 Go 的-s（剥离符号表）flag 并关闭编译器优化（GCFLAGS=all=-N -l），便于在镜像内进行断点调试。
本地依赖替换（replace directive）支持：脚本会扫描 go.mod 中的replace指令，若本地路径存在于BUILD_SAFE_DIRS允许前缀内，会通过--build-context与--build-arg注入 apiserver、lasso、norman、remotedialer、shepherd、steve、wrangler 等模块的本地源码路径，让开发者可以直接用本地依赖进行镜像验证。
推送：设置PUSH=true时，构建完成后会自动执行docker push。

因此，make quick不仅是「快」，它本质上是一条完整的、可定制的 Rancher 镜像生产线。

二、通过 Helm 部署自定义镜像

镜像构建好之后，下一步就是把它部署到集群中验证。Rancher 官方使用 Helm Chart 进行安装（Chart 定义见 chart/Chart.yaml），部署自定义镜像只需要覆盖两个变量：

helm upgrade --install rancher/rancher \ --namespace cattle-system \ --create-namespace \ --set rancherImage="my-test-repo/image" \ --set rancherImageTag="dev-tag"

rancherImage：自定义镜像仓库与镜像名（对应上一节构建出的镜像）。
rancherImageTag：自定义 tag。

--create-namespace会自动创建cattle-system命名空间；helm upgrade --install兼具安装与升级能力，便于反复迭代部署。Chart 的完整可配置项定义在 chart/values.yaml 与 chart/values.schema.json 中，需要调整资源、探针、Ingress 等参数时可参考这两份文件。

三、CAPRKE2 v2prov 本地集成测试全流程

Test_Operation_SetE_CAPRKE2DockerOperations是 Rancher 中一个仅限本地运行的集成测试：它针对 CAPI Cluster（控制平面为 CAPRKE2 的RKE2ControlPlane，基础设施为 CAPI Docker 提供方）执行 Rancher 的操作适配器（operation adapter）系列操作——etcd 快照保存/恢复与加密密钥轮换。CI 不会运行它，因为所需的环境（kind docker 网络 + 挂载到管理集群节点的宿主机 docker socket）只在本地接好。

本机前置条件：docker、k3d、kubectl。三个工具的完整使用流程如下。

第 1 步：准备本地集群

make dev-env

该目标对应脚本 dev-scripts/dev-env，它做三件事：

创建 CAPD 硬编码使用的kinddocker 网络（sigs.k8s.io/cluster-api/test/infrastructure/docker/internal/docker/manager.go中的DefaultNetwork名即kind）。
创建挂接到该网络的 k3d 集群（默认名local-caprke2），并把宿主机/var/run/docker.sock以 hostPath 方式 bind-mount 进 server 节点——这正是 CAPD 上游 manager.yaml 的挂载方式。这两个不变量共同保证 CAPD 的 controller 既能访问宿主机 docker daemon，又能路由到 CAPD 派生的负载容器。
把默认 kubectl context 切换到新集群（k3d-local-caprke2），使后续读取~/.kube/config的工具（包括 Rancher）自动指向它。

脚本同时检查docker、k3d、jq、kubectl是否在 PATH 中，且具备幂等性——集群已存在时直接复用，不会重复创建。

第 2 步：让 Rancher 连接新集群

Rancher 读取~/.kube/config，此时它已指向k3d-local-caprke2。用你习惯的方式启动 Rancher 即可，例如 GoLand 运行目标，或：

./dev-scripts/quick

Rancher 首次启动时会向集群安装 Turtles（Rancher Turtles 是 CAPI 与 Rancher 之间的桥接组件），这一步为后续安装 CAPI Provider 打下基础。

第 3 步：安装 CAPRKE2 + CAPD Provider

Rancher 起来之后，执行：

make install-caprke2-providers

对应脚本 dev-scripts/install-caprke2-providers 的流程是：

等待 Turtles CRD：轮询等待capiproviders.turtles-capi.cattle.ioCRD 出现（Rancher 启动后约 1～2 分钟），通过 scripts/retry 实现 300 秒超时重试；若一直不出现，脚本会提示先启动 Rancher 再重试。
应用 Provider 清单：默认应用仓库内 tests/v2prov/defaults/caprke2-providers.yaml。该清单定义了三个 CAPIProvider：
- rke2-bootstrap（type: bootstrap）：由 RKE2Config/RKE2ConfigTemplate 生成 bootstrap secret；
- rke2-control-plane（type: controlPlane）：负责调和 RKE2ControlPlane；
- docker（type: infrastructure）：在宿主 docker socket 上运行 DockerCluster/DockerMachine。
等待就绪：分别等待rke2-bootstrap-system/rke2-bootstrap-controller-manager、rke2-control-plane-system/rke2-control-plane-controller-manager、capd-system/capd-controller-manager三个 Deployment 完成 rollout。

第 4 步：运行测试

V2PROV_TEST_CAPRKE2=true go test -v -failfast -timeout 60m \ -run '^Test_Operation_SetE_CAPRKE2DockerOperations$' \ ./tests/v2prov/tests/imported/...

V2PROV_TEST_CAPRKE2=true是测试的开关：测试源码 tests/v2prov/tests/imported/caprke2_test.go 中，若该环境变量不等于true会直接t.Skip，这也是该测试无法在 CI 运行的原因之一。
-failfast在首个失败用例处停止，-timeout 60m给出充足超时预算（整个操作序列涉及多次重启控制平面）。

关于测试名的说明：development.md 中的-run正则对应历史单节点冒烟测试名；从当前源码 tests/v2prov/tests/imported/caprke2_test.go 看，同族测试已扩展为Test_Imported_Operation_SetE_CAPRKE2DockerOperations（单控制平面）及其_OneServerOneAgent、_ThreeServers、_ThreeServersThreeAgents变体，文件顶部注释给出了现行推荐用法：

V2PROV_TEST_CAPRKE2=true go test -v \ -run '^Test_Imported_Operation_SetE_CAPRKE2Docker' \ ./tests/v2prov/tests/imported/...

第 5 步：清理环境

make dev-env-cleanup

对应脚本 dev-scripts/dev-env-cleanup 会删除 k3d 集群；对于kinddocker 网络，仅当没有任何容器挂接时才删除（避免误伤仍在使用的真实 kind 集群或其他 CAPI/CAPD 环境）。

环境变量覆盖项

变量	作用	默认值
`CAPRKE2_DEV_CLUSTER`	k3d 集群名，同时作用于`make dev-env`与`make dev-env-cleanup`	`local-caprke2`
`K3S_VERSION`	k3s 镜像 tag	`v1.33.5-k3s1`
`V2PROV_TEST_CAPRKE2_MANIFEST`	本地 Provider 清单的绝对路径，`make install-caprke2-providers`将原样应用它而不用仓库默认清单	未设置
`V2PROV_TEST_CAPRKE2_TURTLES_REF`	`rancher/turtles`的 git ref（tag/branch/SHA），脚本会克隆该 ref 并对`charts/rancher-turtles-providers`执行`helm template`后应用，便于测试仓库锁定版本之外的上游 Turtles 版本	未设置

四、原理纵深：operation adapter 与测试如何验证

操作适配器的注册与分派

CAPRKE2 操作之所以能作用于 CAPI Cluster，关键在于操作适配器（adapter）机制。pkg/operations/capi.go 在init()中为cluster.x-k8s.io/v1beta2的ClusterGVK 注册了适配器工厂：它从 CAPI Client 缓存读取 Cluster 对象，再通过capiClusterAdapter根据controlPlaneRef分派——RKEControlPlane走 CAPR 适配器，RKE2ControlPlane则走 CAPRKE2 适配器（pkg/operations/capi.go）。这也解释了为何测试中的操作ClusterRef指向 CAPI Cluster 而非 mgmt v3 的镜像资源。

测试的操作序列与“恢复证明”

tests/v2prov/tests/imported/caprke2_test.go 中的runCAPRKE2OperationsTest依次执行三个操作并逐步验证：

ETCDSnapshotSave：先在目标集群的default命名空间写入一个 value 为wow的 ConfigMap（作为“恢复证明”标记），再发起快照保存操作；由于 etcd 只跑在控制平面节点上，测试会等待与Replicas数量一致、且时间戳在保存开始之后的快照文件出现。
ETCDSnapshotRestore：先删除该 ConfigMap，然后从控制平面 CAPI Machine 中挑选最新的一个作为 init-node 标识（多轮 restore/轮换后旧机器可能已被滚动替换），据此查找快照并执行恢复；单节点集群按磁盘上的原始快照文件名恢复，多节点集群按ETCDSnapshotCR 名恢复（由CAPRKE2Options.UseSnapshotFileName区分）。恢复后轮询最多 60 次、每次间隔 5 秒，等待 ConfigMap 重新出现且值为wow——期间 apiserver 会因重启而短暂不可达，测试对此做了容错。
EncryptionKeyRotation：最后执行加密密钥轮换（该操作会暂停并重启集群），断言操作进入OperationPhaseSucceeded阶段。

此外，tests/v2prov/operations/etcdsnapshot.go 等文件提供了下游客户端构建、快照 CR 轮询等公共操作工具，展示了完整的测试基建。若某步失败，测试还会调用cluster.GatherDebugData收集调试数据 bundle，方便本地排障。

五、总结与本地迭代建议

综合以上流程，一套高效的 Rancher 本地开发循环是：

修改代码 →REPO=<镜像> TAG=<tag> make quick构建镜像（需要时可指定ARCH交叉构建）；
helm upgrade --install覆盖rancherImage/rancherImageTag完成热部署；
涉及 CAPRKE2/操作适配器改动时，按「make dev-env→ 启动 Rancher →make install-caprke2-providers→ 运行 v2prov 测试 →make dev-env-cleanup」的完整链路做集成验证。

这套工具链的每一环都能在仓库中找到对应的可读脚本（dev-scripts/ 目录下），是理解 Rancher 镜像构建与 CAPI 集成测试机制的最佳入口。

【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析