Rancher 集成测试环境搭建指南：从本地 k3d 集群创建到导入的全流程

Rancher 集成测试环境搭建指南从本地 k3d 集群创建到导入的全流程【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher导读Rancher 仓库的tests/v2/integration下有一套面向真实集群的端到端集成测试运行它们需要一个带下游集群的 Rancher 环境。本文围绕 tests/v2/integration/setup/README.md 展开讲解如何用配套的 setup 程序在本地一键完成「连接 Rancher Server → 创建 k3d 集群 → 将集群导入 Rancher → 生成测试配置」的完整流程。读完本文你将掌握从源码构建 Rancher 镜像、启动本地 Rancher Server、编译并运行集成测试 setup 二进制、以及后续执行整套集成测试的完整实战链路。这个工具解决什么问题Rancher 的 v2 集成测试如catalogv2、rbac、projects等测试套件需要真实的 Rancher 实例和一个已导入的 Kubernetes 下游集群作为被测对象。手动准备这套环境繁琐且易错因此仓库提供了一个名为integrationsetup的独立程序它按顺序完成以下四件事连接本地已启动的 Rancher Server 实例通过 k3d 创建一个新的下游 Kubernetes 集群把该 k3d 集群导入 Rancher Server列出导入集群中的 Deployment验证连接是否正常对应 setup/main.go 中CreateAndImportK3DCluster调用完成后由后续测试自行验证连接。除了创建集群它还会生成一份测试配置config.yaml后续所有集成测试都依赖这份文件定位 Rancher 与集群。工作原理一览setup 程序的核心逻辑全部位于 tests/v2/integration/setup/main.go其执行流程可以概括为读取环境变量(CATTLE_*) │ ▼ 确定 Rancher HostCATTLE_RANCHER_HOST 优先否则自动探测出网 IP │ ▼ 轮询等待 Rancher 就绪并用 bootstrap 密码生成 admin Token │ ▼ 生成随机集群名写入 rancherConfig含 Token/Host/Cleanup/ClusterName/AdminPassword │ ▼ config.WriteConfig() 落盘 config.yaml │ ▼ 通过 shepherd 客户端创建客户端实例调用 k3d.CreateAndImportK3DCluster() │ ▼ 创建并导入 k3d 下游集群其中getOutboundIP()setup/main.go通过向8.8.8.8:80建立 UDP socket 来读取本机出网 IP作为默认的 Rancher 访问地址。环境前置条件在开始之前需要准备以下工具依赖版本要求用途Go1.24 或更高以仓库根目录 go.mod 声明为准编译 setup 程序与运行测试Docker任意可用版本运行 Rancher Server、k3d 集群k3dv5.8.3 或兼容版本创建本地下游 Kubernetes 集群安装 k3dTAG 指定为 v5.8.3curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAGv5.8.3 bash步骤 1构建 Rancher 镜像可选如果你是 Rancher 的开发者、需要验证自己的代码改动建议构建自己的rancher/rancher与rancher/rancher-agent镜像。先从仓库根目录取到当前 git commit 哈希并设置好镜像参数# 从 rancher/rancher 仓库根目录执行 export COMMIT$(git rev-parse --short HEAD) export DEV_TAGdev # 或任意自定义 dev 镜像 tag export ARCHamd64 # 或 arm64 export RANCHER_REPOrancher # 或你的自定义 docker repo构建 agent 镜像make quick-agent构建 Rancher Server 镜像make quick-server这两个命令对应 Makefile 中定义的quick-agent/quick-server目标它们内部复用scripts/quick系列脚本完成镜像构建。如果你并非在开发 Rancher也可以直接使用 Docker Hub 上已有的镜像例如rancher/rancher:stable与rancher/rancher-agent:stable跳过本步骤。步骤 2启动 Rancher Serversetup 程序只会连接一个已经存在的 Rancher Server因此需要先用 Docker 把 Server 跑起来。首先确定机器的内网主 IP它将用于CATTLE_SERVER_URLexport RANCHER_IP$(ip route get 8.8.8.8 | awk {print $7}) echo Your Rancher IP is: $RANCHER_IP然后启动 Server把_YOUR_IP_ADDRESS_替换为上一步得到的 IP# 设置要测试的 Rancher 与 Agent 镜像 tag export RANCHER_IMAGE_TAGstable # 或你的自定义 tag如 dev export RANCHER_AGENT_IMAGE_TAGstable # 或你的自定义 tag如 dev docker run -d --name rancher-server --restartunless-stopped \ -p 80:80 -p 443:443 \ --privileged \ -e CATTLE_SERVER_URLhttps://_YOUR_IP_ADDRESS_ \ -e CATTLE_BOOTSTRAP_PASSWORDadmin \ -e CATTLE_DEV_MODEyes \ -e CATTLE_AGENT_IMAGErancher/rancher-agent:${RANCHER_AGENT_IMAGE_TAG} \ rancher/rancher:${RANCHER_IMAGE_TAG}几个关键环境变量的含义CATTLE_SERVER_URLRancher Server 对外暴露的 HTTPS 地址后续 agent 接入和测试访问都依赖它CATTLE_BOOTSTRAP_PASSWORD首次登录的引导密码setup 程序会用它换取 admin TokenCATTLE_DEV_MODEyes开发模式便于本地调试CATTLE_AGENT_IMAGE指定下游集群导入时要拉取的 agent 镜像。Rancher 启动需要几分钟可用docker logs -f rancher-server观察启动日志直到日志中出现 Rancher 就绪信息也可以参考 tests/v2/integration/README.md 中用curl -sk https://${RANCHER_IP}/ping轮询/ping接口等待pong的方式。步骤 3构建 setup 二进制仓库提供了专用的构建脚本必须通过它编译直接执行裸go build会失败——因为 setup 依赖的github.com/containers/image会引入 C 库依赖。# 从 rancher/rancher 仓库根目录执行 cd tests/v2/integration ./scripts/build-integration-setup # 产物位于: tests/v2/integration/bin/integrationsetupbuild-integration-setup 脚本内部的实际编译命令是CGO_ENABLED0 go build -tags containers_image_openpgp,integrationsetup -o bin/integrationsetup ./setup两点值得注意CGO_ENABLED0禁用 CGO配合 build tag 避免编译containers/image的 C 依赖-tags integrationsetup与 setup/main.go 顶部注释相呼应——该文件用 build tag 保护只有在需要运行集成测试 setup 程序时才会被编译从而避免引入不必要的 C 库构建。步骤 4运行 setup 程序在 Rancher Server 已启动的前提下设置所需环境变量后运行二进制# 从 rancher/rancher 仓库根目录执行 export CATTLE_BOOTSTRAP_PASSWORDadmin export CATTLE_AGENT_IMAGErancher/rancher-agent:stable # 或你的自定义 tag export CATTLE_TEST_CONFIG$(pwd)/tests/v2/integration/config.yaml # 可选覆盖自动探测的 host当 Rancher 不在本机、 # 或出网 IP 探测结果不对时使用 # export CATTLE_RANCHER_HOST192.168.1.100:443 ./tests/v2/integration/bin/integrationsetup关于 host 的自动探测与覆盖默认情况下二进制会通过向8.8.8.8打开 UDP socket 的方式自动探测本机出网 IP见 setup/main.go 与getOutboundIP函数并拼成https://IP:443作为 Rancher 地址。如果 Rancher 不在本机或探测到的 IP 不是正确网卡可通过CATTLE_RANCHER_HOST显式覆盖例如localhost:8443或远端 IP。该值会被直接写入config.yaml因此它也就是后续测试访问 Rancher 所用的地址。程序的内部行为结合 setup/main.go 源码可以看到 setup 实际做的事通过kwait.PollUntilContextTimeout500ms 间隔、最长 5 分钟轮询 Rancher 的认证接口等待 Server 就绪并用CATTLE_BOOTSTRAP_PASSWORD调用token.GenerateUserToken生成 admin Token账号固定为admin用namegen.AppendRandomString(k3d-cluster)生成带随机后缀的集群名如k3d-cluster-xxxx将 Token、Host、Cleanuptrue、集群名、admin 密码组装进 shepherd 的rancherClient.Config经defaults.Set补齐默认值后由config.WriteConfig写入配置文件通过session.NewSession()与rancherClient.NewClient建立客户端调用k3d.CreateAndImportK3DCluster(client, clusterName, agentImage, , 1, 0, true)来自github.com/rancher/shepherd/clients/k3d创建 1 个 server 节点的 k3d 集群并导入 Rancher。其中rancherConfig.Cleanup cleanup值为true表示会话结束时清理所创建的资源。环境变量速查表变量使用方说明CATTLE_TEST_CONFIG测试 setup必填。config.yaml的绝对路径运行测试或 setup 之前必须 exportCATTLE_BOOTSTRAP_PASSWORD仅 setupRancher 首次登录的引导密码默认adminCATTLE_AGENT_IMAGE仅 setupRancher agent 的完整镜像引用如rancher/rancher-agent:v2.14-head导入 k3d 集群时使用CATTLE_RANCHER_HOST仅 setup覆盖自动探测的 Rancher host如192.168.1.100:443或localhost:8443。未设置时由 setup 探测本机出网 IP生成的 config.yaml 与测试运行生成的config.yaml已被 gitignore写入位置为tests/v2/integration/config.yaml内容类似rancher: adminToken: token-xxxxx:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy host: 192.168.1.100 # Rancher host不含 https://无结尾斜杠 clusterName: k3d-cluster-xxxx # 已导入 Rancher 的下游集群名 insecure: true cleanup: true然后即可运行集成测试go test -v -timeout 30m -failfast -p 1 ./tests/v2/integration/...常用go test参数建议参数示例说明-timeout-timeout 30m整个测试二进制的硬性截止时间。默认仅 10 分钟对会拉取外部仓库的 catalog 测试来说太短-run-run TestChartsTestSuite只运行匹配正则的测试/套件支持/选择子测试-count-count1关闭测试结果缓存集成测试务必加上-v-v逐条输出测试名与 PASS/FAIL便于定位卡住的用例-failfast-failfast首个失败即停止CI 中节省时间-p-p 1并行构建/运行的包数量集成测试必须为1以避免资源冲突结合 Makefile 的一键流程如果你不想手动执行上述步骤仓库的 Makefile 已经封装好了两个目标make integration-setup # 编译 setup 二进制并运行自动生成 config.yaml make integration-test-local # 读取 config.yaml 并运行整套集成测试integration-setup目标等价于「执行 build-integration-setup 脚本 设置CATTLE_TEST_CONFIG后运行integrationsetup」而integration-test-local则用CGO_ENABLED0 go test -v -failfast -timeout 30m -p 1 ./tests/v2/integration/...跑完全部测试。若已有上次生成的config.yaml可跳过 setup 直接执行第二步。在 CI 场景下scripts/test 中同样调用 build-integration-setupRancher 会在Dockerfile.runtime构建的容器内启动并借助 k3s 创建 local 集群、部署 CRDs随后在同一容器内运行集成测试——这套在容器内的完整环境编排细节可参考 tests/v2/integration/README.md 的 Downstream Cluster Provisioning 一节。常见问题与排错要点裸go build报 C 库相关错误务必使用 build-integration-setup 脚本它通过CGO_ENABLED0与containers_image_openpgp,integrationsetup两个 build tag 规避了 C 依赖Rancher 未就绪导致 Token 生成失败setup 会最多轮询 5 分钟若仍失败检查docker logs -f rancher-server确认 Server 是否真正启动完成Host 探测到错误的网卡Rancher 不在本机或多网卡环境设置CATTLE_RANCHER_HOST显式指定地址即可测试超时集成测试对 CPU/内存消耗较大出现意外超时通常意味着本机算力不足出现 OOM 影响容器调度则说明内存不足见 tests/v2/integration/README.md 的提示。延伸阅读setup 程序完整源码tests/v2/integration/setup/main.go构建脚本tests/v2/integration/scripts/build-integration-setup集成测试总览含测试套件清单与 config 字段全量说明tests/v2/integration/README.mdMakefile 中的快捷目标Makefile根目录 Go 版本声明go.mod【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考