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编译。针对当前操作系统与架构构建镜像在仓库根目录执行REPOlocalhost:5000/my-test-repo/image TAGtag make quick如果希望为其他架构交叉构建只需额外设置ARCH变量REPOlocalhost:5000/my-test-repo/image \ TAGtag \ ARCHamd64 \ 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}设置TARGETbinary-server则只产出本地二进制到当前目录TARGETk3s-images则导出 k3s 镜像列表。构建参数自动注入脚本会从 package/Dockerfile 中提取CATTLE_K3S_VERSION、CATTLE_KDM_BRANCH、CATTLE_HELM_VERSION等版本信息并从 git 当前 HEAD 取短 commit随后以--build-arg形式传入保证镜像内嵌的版本号与源码一致。调试构建设置BINARY_DEBUGtrue时脚本会移除 Go 的-s剥离符号表flag 并关闭编译器优化GCFLAGSall-N -l便于在镜像内进行断点调试。本地依赖替换replace directive支持脚本会扫描 go.mod 中的replace指令若本地路径存在于BUILD_SAFE_DIRS允许前缀内会通过--build-context与--build-arg注入 apiserver、lasso、norman、remotedialer、shepherd、steve、wrangler 等模块的本地源码路径让开发者可以直接用本地依赖进行镜像验证。推送设置PUSHtrue时构建完成后会自动执行docker push。因此make quick不仅是「快」它本质上是一条完整的、可定制的 Rancher 镜像生产线。二、通过 Helm 部署自定义镜像镜像构建好之后下一步就是把它部署到集群中验证。Rancher 官方使用 Helm Chart 进行安装Chart 定义见 chart/Chart.yaml部署自定义镜像只需要覆盖两个变量helm upgrade --install rancher/rancher \ --namespace cattle-system \ --create-namespace \ --set rancherImagemy-test-repo/image \ --set rancherImageTagdev-tagrancherImage自定义镜像仓库与镜像名对应上一节构建出的镜像。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/quickRancher 首次启动时会向集群安装 TurtlesRancher Turtles 是 CAPI 与 Rancher 之间的桥接组件这一步为后续安装 CAPI Provider 打下基础。第 3 步安装 CAPRKE2 CAPD ProviderRancher 起来之后执行make install-caprke2-providers对应脚本 dev-scripts/install-caprke2-providers 的流程是等待 Turtles CRD轮询等待capiproviders.turtles-capi.cattle.ioCRD 出现Rancher 启动后约 12 分钟通过 scripts/retry 实现 300 秒超时重试若一直不出现脚本会提示先启动 Rancher 再重试。应用 Provider 清单默认应用仓库内 tests/v2prov/defaults/caprke2-providers.yaml。该清单定义了三个 CAPIProviderrke2-bootstraptype: bootstrap由 RKE2Config/RKE2ConfigTemplate 生成 bootstrap secretrke2-control-planetype: controlPlane负责调和 RKE2ControlPlanedockertype: 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_CAPRKE2true go test -v -failfast -timeout 60m \ -run ^Test_Operation_SetE_CAPRKE2DockerOperations$ \ ./tests/v2prov/tests/imported/...V2PROV_TEST_CAPRKE2true是测试的开关测试源码 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_CAPRKE2true 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_CLUSTERk3d 集群名同时作用于make dev-env与make dev-env-cleanuplocal-caprke2K3S_VERSIONk3s 镜像 tagv1.33.5-k3s1V2PROV_TEST_CAPRKE2_MANIFEST本地 Provider 清单的绝对路径make install-caprke2-providers将原样应用它而不用仓库默认清单未设置V2PROV_TEST_CAPRKE2_TURTLES_REFrancher/turtles的 git reftag/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镜像 TAGtag 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），仅供参考 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编译。针对当前操作系统与架构构建镜像在仓库根目录执行REPOlocalhost:5000/my-test-repo/image TAGtag make quick如果希望为其他架构交叉构建只需额外设置ARCH变量REPOlocalhost:5000/my-test-repo/image \ TAGtag \ ARCHamd64 \ 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}设置TARGETbinary-server则只产出本地二进制到当前目录TARGETk3s-images则导出 k3s 镜像列表。构建参数自动注入脚本会从 package/Dockerfile 中提取CATTLE_K3S_VERSION、CATTLE_KDM_BRANCH、CATTLE_HELM_VERSION等版本信息并从 git 当前 HEAD 取短 commit随后以--build-arg形式传入保证镜像内嵌的版本号与源码一致。调试构建设置BINARY_DEBUGtrue时脚本会移除 Go 的-s剥离符号表flag 并关闭编译器优化GCFLAGSall-N -l便于在镜像内进行断点调试。本地依赖替换replace directive支持脚本会扫描 go.mod 中的replace指令若本地路径存在于BUILD_SAFE_DIRS允许前缀内会通过--build-context与--build-arg注入 apiserver、lasso、norman、remotedialer、shepherd、steve、wrangler 等模块的本地源码路径让开发者可以直接用本地依赖进行镜像验证。推送设置PUSHtrue时构建完成后会自动执行docker push。因此make quick不仅是「快」它本质上是一条完整的、可定制的 Rancher 镜像生产线。二、通过 Helm 部署自定义镜像镜像构建好之后下一步就是把它部署到集群中验证。Rancher 官方使用 Helm Chart 进行安装Chart 定义见 chart/Chart.yaml部署自定义镜像只需要覆盖两个变量helm upgrade --install rancher/rancher \ --namespace cattle-system \ --create-namespace \ --set rancherImagemy-test-repo/image \ --set rancherImageTagdev-tagrancherImage自定义镜像仓库与镜像名对应上一节构建出的镜像。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/quickRancher 首次启动时会向集群安装 TurtlesRancher Turtles 是 CAPI 与 Rancher 之间的桥接组件这一步为后续安装 CAPI Provider 打下基础。第 3 步安装 CAPRKE2 CAPD ProviderRancher 起来之后执行make install-caprke2-providers对应脚本 dev-scripts/install-caprke2-providers 的流程是等待 Turtles CRD轮询等待capiproviders.turtles-capi.cattle.ioCRD 出现Rancher 启动后约 12 分钟通过 scripts/retry 实现 300 秒超时重试若一直不出现脚本会提示先启动 Rancher 再重试。应用 Provider 清单默认应用仓库内 tests/v2prov/defaults/caprke2-providers.yaml。该清单定义了三个 CAPIProviderrke2-bootstraptype: bootstrap由 RKE2Config/RKE2ConfigTemplate 生成 bootstrap secretrke2-control-planetype: controlPlane负责调和 RKE2ControlPlanedockertype: 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_CAPRKE2true go test -v -failfast -timeout 60m \ -run ^Test_Operation_SetE_CAPRKE2DockerOperations$ \ ./tests/v2prov/tests/imported/...V2PROV_TEST_CAPRKE2true是测试的开关测试源码 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_CAPRKE2true 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_CLUSTERk3d 集群名同时作用于make dev-env与make dev-env-cleanuplocal-caprke2K3S_VERSIONk3s 镜像 tagv1.33.5-k3s1V2PROV_TEST_CAPRKE2_MANIFEST本地 Provider 清单的绝对路径make install-caprke2-providers将原样应用它而不用仓库默认清单未设置V2PROV_TEST_CAPRKE2_TURTLES_REFrancher/turtles的 git reftag/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镜像 TAGtag 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），仅供参考