Rancher 测试框架实战指南从集成测试编写到本地运行与配置详解【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher导读本文基于 Rancher 仓库中的 tests/README.md 及配套的集成测试文档系统讲解 Rancher 测试框架的整体结构与使用方式。你将掌握集成测试Integration与验证测试Validation的适用场景与前置要求、基于 Shepherd 与 testify Suite 编写测试的规范、make ci全流程与面向外部 Rancher 实例的本地迭代两种运行方式以及config.yaml测试配置的每个字段含义。文中所有结论均可回溯到仓库中的文档、源码与 Makefile 目标进行验证。Rancher 测试框架概述Rancher 测试框架Rancher Test Framework为编写集成测试与验证测试提供了一整套工具。它的核心职责有两项管理被测外部服务之间的交互——测试需要连接运行中的 Rancher 实例、下游集群等外部服务帮助在测试结束后清理资源——通过 Session 机制跟踪并回收测试创建的资源避免测试之间相互干扰。从组织架构上看框架被划分为三个学科disciplines学科职责framework框架若干核心库用于让测试写得同构、一致降低不同测试套件之间的写法差异clients客户端封装与 Rancher、Kubernetes、k3d 等外部服务交互的客户端extensions扩展提供可复用的测试扩展能力如用户、Token、命名空间、注册表等场景的辅助函数其中 framework 是核心库层clients 与 extensions 分别对应文档中提到的 clients 与 extensions 两个补充章节当前仓库内以tests/v2下的集成测试、tests/v2prov下的 provisioning 测试等实际用例体现。运行前置要求Requirements集成测试Integration运行 Rancher 集成测试需要准备一个可访问 URL 的运行中 Rancher 实例管理员admin用户的Rancher 访问 TokenGo 1.22或更高版本仓库根目录go.mod声明了 Go 版本要求tests/v2/integration/setup/README.md 提到 Go 1.24k3d用于创建下游集群setup 文档建议 v5.8.3 或兼容版本。验证测试Validation验证测试与集成测试的前置要求相同但不同测试套件可能还需要云厂商的凭据例如 AWS、Azure 等具体以各套件的配置文件说明为准。核心概念Integration vs Validation理解这两类测试的边界是正确选择测试落点的基础维度集成测试Integration验证测试Validation外部依赖不依赖任何外部配置或其他外部服务依赖外部服务必须提供配置文件才能运行运行时长短运行因为每次 PR 都会在 CI 中执行较长按需运行云厂商访问密钥不需要可能需要简而言之集成测试追求“快速、无外部依赖、可反复在 CI 执行”验证测试追求“在真实外部环境中做深度验证”因此需要配置文件与可能的云凭据。测试框架ShepherdRancher 的测试框架名为Shepherd是 Rancher 官方维护的独立测试框架仓库当前仓库通过 Go module 依赖引用它例如 tests/v2/integration/setup/main.go 中导入github.com/rancher/shepherd/clients/k3d、github.com/rancher/shepherd/pkg/session等包。Shepherd 提供了客户端封装clients/rancher、clients/k3d会话管理pkg/session配置加载pkg/config名称生成pkg/namegenerator扩展功能extensions/token、extensions/users等。编写测试时优先使用框架客户端是保证资源可清理、测试可复用的关键。如何编写测试How to Write Tests测试存放位置测试应创建在tests/v2/integration目录下——对应仓库内的集成测试独立的 tests 仓库——对应验证测试。依据上文 Integration vs Validation 的边界决定落点。分组与组织开发者可以按需将测试分组到文件和包中但原则是让下一位开发者容易找到且与同一时间点运行的其他测试归组文件内部测试应分组为Suite基于github.com/stretchr/testify/suite一个 Suite 应在其所有测试间共享客户端clients和会话session一个 Suite 内的测试应测试同一类功能并复用 Suite 资源。例如如果要验证不同项目角色对项目资源的访问权限可以把所有角色对应的测试放进同一个 Suite并共享同一个项目。这样每个测试都不必重复创建项目显著节省时间——这正是仓库中 tests/v2/integration/rbac/rtbs_test.go 的做法。Suite 的代码骨架以 tests/v2/integration/rbac/rtbs_test.go 为实例可以看到一个典型 Suite 的写法type RTBTestSuite struct { suite.Suite client *rancher.Client project *management.Project session *session.Session downstreamClusterID string } func (p *RTBTestSuite) SetupSuite() { p.downstreamClusterID local testSession : session.NewSession() p.session testSession client, err : rancher.NewClient(, testSession) p.Require().NoError(err) p.client client // 在 Suite 内共享一个项目所有测试复用 projectConfig : management.Project{ ClusterID: p.downstreamClusterID, Name: TestProject, } testProject, err : client.Management.Project.Create(projectConfig) p.Require().NoError(err) p.project testProject } func (p *RTBTestSuite) TearDownSuite() { client, err : p.client.WithSession(p.session) p.Require().NoError(err) err client.Management.Project.Delete(p.project) p.Require().NoError(err) p.session.Cleanup() }文件末尾通过suite.Run(t, new(RTBTestSuite))启动测试见 rtbs_test.go。命名规范测试名中不能包含/因为/用于表示测试套件sub-test层级包含该字符会造成测试结构上的歧义。例如-run TestRTBTestSuite/TestUserVsUserBaseGlobalRoleVisibility中的/用于选中 Suite 内的具体子测试。资源清理与 Session测试应尽可能使用框架客户端确保测试创建的资源会被清理不干扰其他测试每个测试都有责任在下一个测试运行前完整清理自己创建的所有资源资源跟踪依赖Session机制会话Session会记录测试过程中创建的资源并在结束时统一清理。上述SetupSuite/TearDownSuite中session.NewSession()与p.session.Cleanup()的配对就是这一机制的落地。更细粒度的做法是为单个测试创建子会话sub-session实现测试级隔离见newSubSession。运行测试的两种方式仓库中的 tests/v2/integration/README.md 给出了两条完整运行路径。方式一完整 CI 运行make ci推荐用于验证make ci流程说明在由Dockerfile.runtime构建的 Rancher 运行时容器内执行scripts/testscripts/test会搭建并启动 RancherRancher 启动时用k3s创建 local 集群并部署 CRDRancher 与 local 集群就绪后运行测试套件。该方法理论上开箱即用地支持 Mac 与 Linux。需要注意整个集成测试过程会消耗较多 CPU 与内存——出现意外超时往往意味着计算资源不足出现影响容器调度的 OOM 则意味着内存不足。方式二针对外部 Rancher 实例本地运行适合迭代开发该方式将测试指向一个已经在运行的 Rancher 实例而不是在容器内重新拉起一个适合开发调试。快速上手复制即用# 1. 启动 Rancher如果尚未运行 export RANCHER_IP$(ifconfig | grep inet | grep -v 127.0.0.1 | head -1 | awk {print $2}) docker run -d --name rancher-server --restartunless-stopped \ -p 80:80 -p 443:443 --privileged \ -e CATTLE_SERVER_URLhttps://${RANCHER_IP} \ -e CATTLE_BOOTSTRAP_PASSWORDadmin \ -e CATTLE_DEV_MODEyes \ -e CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head \ rancher/rancher:v2.14-head # 2. 创建 k3d 下游集群并生成 config.yaml export CATTLE_BOOTSTRAP_PASSWORDadmin export CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head make integration-setup # 3. 运行测试 make integration-test-local对应的 Makefile 目标定义在 Makefilemake integration-setup构建 setup 二进制tests/v2/integration/bin/integrationsetup连接 Rancher、创建 k3d 下游集群并将连接信息写入tests/v2/integration/config.yamlmake integration-test-local读取config.yaml并运行完整测试套件CGO_ENABLED0 go test -v -failfast -timeout 30m -p 1 ./tests/v2/integration/...。如果之前已生成过config.yaml可以直接跳过第 2 步执行第 3 步。分步详解Step 1启动 Rancher Serverexport RANCHER_IP$(ifconfig | grep inet | grep -v 127.0.0.1 | head -1 | awk {print $2}) docker run -d --name rancher-server --restartunless-stopped \ -p 80:80 -p 443:443 \ --privileged \ -e CATTLE_SERVER_URLhttps://${RANCHER_IP} \ -e CATTLE_BOOTSTRAP_PASSWORDadmin \ -e CATTLE_DEV_MODEyes \ -e CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head \ rancher/rancher:v2.14-head等待 Rancher 就绪until curl -sk https://${RANCHER_IP}/ping | grep -q pong; do echo waiting for Rancher...; sleep 5; doneStep 2构建并运行 Integration Setupsetup 程序负责连接 Rancher、创建 k3d 下游集群并导入、最后写出测试配置文件# 构建 setup 二进制在仓库根目录执行 cd tests/v2/integration ./scripts/build-integration-setup # 产出: tests/v2/integration/bin/integrationsetup # 运行 setup回到仓库根目录 cd ../../.. export CATTLE_BOOTSTRAP_PASSWORDadmin export CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head export CATTLE_TEST_CONFIG$(pwd)/tests/v2/integration/config.yaml ./tests/v2/integration/bin/integrationsetupsetup 程序会自动探测 Rancher 主机 IP、生成 admin Token、创建 k3d 集群、导入 Rancher并把连接信息写入CATTLE_TEST_CONFIG指定的路径。Step 3可选手动创建config.yaml如果已有带导入集群的 Rancher 实例可以跳过 setup 二进制直接创建配置文件字段说明见下文“配置参考”。Step 4运行测试export CATTLE_TEST_CONFIG$(pwd)/tests/v2/integration/config.yaml # 运行全部集成测试 go test -v -timeout 30m -failfast -p 1 ./tests/v2/integration/... # 运行指定测试套件 go test -v -count1 -timeout 30m -run TestChartsTestSuite ./tests/v2/integration/catalogv2/ # 运行套件内的具体测试 go test -v -count1 -run TestRTBTestSuite/TestUserVsUserBaseGlobalRoleVisibility ./tests/v2/integration/rbac/ # 仅运行 Steve API 测试仅 local 集群无需下游集群 go test -v -count1 -run TestSteveLocal ./tests/v2/integration/steveapi/常用go test参数参数示例说明-timeout-timeout 30m整个测试二进制的硬性截止时间。默认10 分钟对需要拉取外部仓库的 catalog 类测试来说太短完整套件建议30m-run-run TestChartsTestSuite只运行匹配正则的测试/套件支持/选择子测试-run Suite/TestName-count-count1禁用测试结果缓存。运行集成测试时应始终加-count1确保是全新执行-v-v详细输出逐个打印测试名与 PASS/FAIL便于定位挂起的测试-failfast-failfast首个测试失败即停止CI 中用于避免失败后继续浪费资源-p-p 1并行构建/运行的测试包数量。集成测试必须为1避免资源冲突配置参考config.yaml测试配置文件的路径由环境变量CATTLE_TEST_CONFIG指定。最小示例rancher: adminToken: token-xxxxx:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy host: 192.168.1.100 # Rancher 主机不含 https://末尾无斜杠 clusterName: my-k3d-cluster # Rancher 中导入的下游集群名称 insecure: true cleanup: true全部支持字段字段类型说明是否必填rancher.adminTokenstring用于 admin API 访问的 Bearer Token。可在 Rancher UI 获取用户头像 → Account API Keys → Create API KeyNo Scope是rancher.hoststringRancher 服务器主机名或 IP不含协议 scheme、末尾无斜杠是rancher.clusterNamestringRancher 中下游集群的名称。下游相关测试必填仅测 local 集群时填local是rancher.insecurebool跳过 TLS 校验适用于自签名证书。默认false否rancher.cleanupbool测试是否删除其创建的资源。默认true否rancher.adminPasswordstringadmin 密码adminToken的替代方案否rancher.caFilestring用于 TLS 校验的 CA 证书文件路径否rancher.caCertsstring内联 PEM 编码的 CA 证书否环境变量变量使用者说明CATTLE_TEST_CONFIG测试 setup必填。config.yaml的绝对路径。运行测试或 setup 二进制前必须导出CATTLE_BOOTSTRAP_PASSWORD仅 setupRancher 首次登录的引导密码。默认adminCATTLE_AGENT_IMAGE仅 setupRancher agent 的完整镜像引用如rancher/rancher-agent:v2.14-head导入 k3d 集群时使用CATTLE_RANCHER_HOST仅 setup覆盖自动探测的 Rancher 主机如192.168.1.100:443或localhost:8443。未设置时setup 二进制通过探测机器出站 IP 确定主机关于主机探测机制tests/v2/integration/setup/main.go 给出了实现细节默认通过向8.8.8.8:80建立 UDP socket 读取本地地址来获取出站 IP并用fmt.Sprintf(%s:443, ip)拼出host当CATTLE_RANCHER_HOST非空时直接使用该值。rancherConfig中的AdminToken、Host、Cleanup、ClusterName、AdminPassword字段均由 setup 程序生成并写入配置。测试套件一览Test Suites仅使用local集群的测试不需要下游集群只需基础config.yaml即可运行标记为“需要下游集群”的测试必须通过rancher.clusterName引用已导入的集群目录测试函数测试内容需要下游集群catalogv2/TestChartsTestSuiteChart 安装、容忍度、pull-through是catalogv2/TestClusterRepoTestSuiteClusterRepo CRUD、OCI 仓库否catalogv2/TestSystemChartsVersionSuite系统 chart 版本约束否catalogv2/TestUIPluginSuiteUI 插件扩展否catalogv2/TestRancherManagedChartsSuiteRancher 托管的 Helm chart否clusters/TestK8sProxy经 Rancher 的 K8s API 代理是projects/TestResourceQuotaTestSuite命名空间资源配额否projects/TestProjectUserTestSuite项目级用户访问否rbac/TestRTBTestSuite角色/ClusterRole 模板绑定、features、impersonation、projects否使用localsteveapi/TestSteveLocalSteve 资源列表 APIlocal 集群否steveapi/TestSteveDownstream下游集群上的 Steve API是当前跳过users/TestUserTestSuite用户 CRUD 操作否authconfigs/TestAuthConfig认证配置管理否serviceaccount/TestSATestSuiteServiceAccount Token 处理否上述目录均位于仓库tests/v2/integration/下例如 tests/v2/integration/catalogv2、tests/v2/integration/rbac。测试环境搭建细节Test Setup Details集成测试的 setup 逻辑分布在scripts/test与 tests/v2/integration/setup/main.go 中。后者主要承担四项职责生成并保存测试配置文件供集成测试使用创建一个用户及对应 Token供测试访问 Rancher在 local 集群中创建新的测试命名空间并以 Secret 形式部署 Docker 容器注册表凭据在default命名空间部署两个注册表。scripts/test中对应流程可参看其build-integration-setup、integrationsetup、go integration tests三段调用。注册表Registry搭建setup 过程中部署的两个注册表各有分工第一个注册表按常规方式配置支持镜像的 push 与 pull第二个注册表配置为pull-through 缓存唯一目的是缓存下游集群创建容器时拉取的镜像以加速测试过程。创建注册表的同时会向上述测试命名空间部署对应的 Secret。随后由scripts/ci本地构建的 cattle cluster agent 镜像会被推送到第一个注册表供下游集群拉取。两个注册表的配置会被合并用于创建集成测试使用的测试集群——合并后的注册表配置正是下游集群能够访问 local 集群内注册表的关键。下游集群的供应方式集成测试 setup 中创建下游集群的方式与 v2 provisioning 测试完全一致通过github.com/rancher/rancher/tests/v2prov/cluster包提供的cluster.New()函数创建。该函数利用 Rancher 的 v2 provisioning 功能在测试命名空间中创建一个运行 machine provisioner 的容器machine provisioner 再创建systemd-node容器由其自建一个内嵌的 Kubernetes 集群。最终的整体形态为一个运行 Rancher 运行时环境的 Docker 容器其中scripts/test正在运行集成测试RancherRancher 的 “local” 集群k3s 集群其中运行若干容器网络相关组件以及 rancher-webhook 等 Rancher 特有组件一个systemd-node容器其中运行“下游集群”一个运行 cluster agent 及其他 Rancher 下游组件的 k3s 集群这一嵌套架构说明一次make ci实际上在同一运行时环境内容纳了 Rancher 服务器、local 集群与下游集群三层结构这也是它对 CPU 与内存要求较高的原因。小结Rancher 测试框架以 Shepherd 为核心将测试划分为 framework、clients、extensions 三个层次并明确区分“快速、无外部依赖”的集成测试与“需要外部服务与配置”的验证测试。编写测试时遵循“Suite 共享客户端与会话、测试名不含/、优先使用框架客户端、测试自行清理资源”的规范即可写出同构、可复用、可清理的测试。运行时既可通过make ci在容器内一键完成端到端验证也可通过make integration-setupmake integration-test-local对已运行的 Rancher 实例做快速迭代config.yaml的字段与CATTLE_*系列环境变量则提供了从 Token、主机、集群名到 TLS 校验、资源清理策略的完整可控项。【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rancher 测试框架实战指南：从集成测试编写到本地运行与配置详解
Rancher 测试框架实战指南从集成测试编写到本地运行与配置详解【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher导读本文基于 Rancher 仓库中的 tests/README.md 及配套的集成测试文档系统讲解 Rancher 测试框架的整体结构与使用方式。你将掌握集成测试Integration与验证测试Validation的适用场景与前置要求、基于 Shepherd 与 testify Suite 编写测试的规范、make ci全流程与面向外部 Rancher 实例的本地迭代两种运行方式以及config.yaml测试配置的每个字段含义。文中所有结论均可回溯到仓库中的文档、源码与 Makefile 目标进行验证。Rancher 测试框架概述Rancher 测试框架Rancher Test Framework为编写集成测试与验证测试提供了一整套工具。它的核心职责有两项管理被测外部服务之间的交互——测试需要连接运行中的 Rancher 实例、下游集群等外部服务帮助在测试结束后清理资源——通过 Session 机制跟踪并回收测试创建的资源避免测试之间相互干扰。从组织架构上看框架被划分为三个学科disciplines学科职责framework框架若干核心库用于让测试写得同构、一致降低不同测试套件之间的写法差异clients客户端封装与 Rancher、Kubernetes、k3d 等外部服务交互的客户端extensions扩展提供可复用的测试扩展能力如用户、Token、命名空间、注册表等场景的辅助函数其中 framework 是核心库层clients 与 extensions 分别对应文档中提到的 clients 与 extensions 两个补充章节当前仓库内以tests/v2下的集成测试、tests/v2prov下的 provisioning 测试等实际用例体现。运行前置要求Requirements集成测试Integration运行 Rancher 集成测试需要准备一个可访问 URL 的运行中 Rancher 实例管理员admin用户的Rancher 访问 TokenGo 1.22或更高版本仓库根目录go.mod声明了 Go 版本要求tests/v2/integration/setup/README.md 提到 Go 1.24k3d用于创建下游集群setup 文档建议 v5.8.3 或兼容版本。验证测试Validation验证测试与集成测试的前置要求相同但不同测试套件可能还需要云厂商的凭据例如 AWS、Azure 等具体以各套件的配置文件说明为准。核心概念Integration vs Validation理解这两类测试的边界是正确选择测试落点的基础维度集成测试Integration验证测试Validation外部依赖不依赖任何外部配置或其他外部服务依赖外部服务必须提供配置文件才能运行运行时长短运行因为每次 PR 都会在 CI 中执行较长按需运行云厂商访问密钥不需要可能需要简而言之集成测试追求“快速、无外部依赖、可反复在 CI 执行”验证测试追求“在真实外部环境中做深度验证”因此需要配置文件与可能的云凭据。测试框架ShepherdRancher 的测试框架名为Shepherd是 Rancher 官方维护的独立测试框架仓库当前仓库通过 Go module 依赖引用它例如 tests/v2/integration/setup/main.go 中导入github.com/rancher/shepherd/clients/k3d、github.com/rancher/shepherd/pkg/session等包。Shepherd 提供了客户端封装clients/rancher、clients/k3d会话管理pkg/session配置加载pkg/config名称生成pkg/namegenerator扩展功能extensions/token、extensions/users等。编写测试时优先使用框架客户端是保证资源可清理、测试可复用的关键。如何编写测试How to Write Tests测试存放位置测试应创建在tests/v2/integration目录下——对应仓库内的集成测试独立的 tests 仓库——对应验证测试。依据上文 Integration vs Validation 的边界决定落点。分组与组织开发者可以按需将测试分组到文件和包中但原则是让下一位开发者容易找到且与同一时间点运行的其他测试归组文件内部测试应分组为Suite基于github.com/stretchr/testify/suite一个 Suite 应在其所有测试间共享客户端clients和会话session一个 Suite 内的测试应测试同一类功能并复用 Suite 资源。例如如果要验证不同项目角色对项目资源的访问权限可以把所有角色对应的测试放进同一个 Suite并共享同一个项目。这样每个测试都不必重复创建项目显著节省时间——这正是仓库中 tests/v2/integration/rbac/rtbs_test.go 的做法。Suite 的代码骨架以 tests/v2/integration/rbac/rtbs_test.go 为实例可以看到一个典型 Suite 的写法type RTBTestSuite struct { suite.Suite client *rancher.Client project *management.Project session *session.Session downstreamClusterID string } func (p *RTBTestSuite) SetupSuite() { p.downstreamClusterID local testSession : session.NewSession() p.session testSession client, err : rancher.NewClient(, testSession) p.Require().NoError(err) p.client client // 在 Suite 内共享一个项目所有测试复用 projectConfig : management.Project{ ClusterID: p.downstreamClusterID, Name: TestProject, } testProject, err : client.Management.Project.Create(projectConfig) p.Require().NoError(err) p.project testProject } func (p *RTBTestSuite) TearDownSuite() { client, err : p.client.WithSession(p.session) p.Require().NoError(err) err client.Management.Project.Delete(p.project) p.Require().NoError(err) p.session.Cleanup() }文件末尾通过suite.Run(t, new(RTBTestSuite))启动测试见 rtbs_test.go。命名规范测试名中不能包含/因为/用于表示测试套件sub-test层级包含该字符会造成测试结构上的歧义。例如-run TestRTBTestSuite/TestUserVsUserBaseGlobalRoleVisibility中的/用于选中 Suite 内的具体子测试。资源清理与 Session测试应尽可能使用框架客户端确保测试创建的资源会被清理不干扰其他测试每个测试都有责任在下一个测试运行前完整清理自己创建的所有资源资源跟踪依赖Session机制会话Session会记录测试过程中创建的资源并在结束时统一清理。上述SetupSuite/TearDownSuite中session.NewSession()与p.session.Cleanup()的配对就是这一机制的落地。更细粒度的做法是为单个测试创建子会话sub-session实现测试级隔离见newSubSession。运行测试的两种方式仓库中的 tests/v2/integration/README.md 给出了两条完整运行路径。方式一完整 CI 运行make ci推荐用于验证make ci流程说明在由Dockerfile.runtime构建的 Rancher 运行时容器内执行scripts/testscripts/test会搭建并启动 RancherRancher 启动时用k3s创建 local 集群并部署 CRDRancher 与 local 集群就绪后运行测试套件。该方法理论上开箱即用地支持 Mac 与 Linux。需要注意整个集成测试过程会消耗较多 CPU 与内存——出现意外超时往往意味着计算资源不足出现影响容器调度的 OOM 则意味着内存不足。方式二针对外部 Rancher 实例本地运行适合迭代开发该方式将测试指向一个已经在运行的 Rancher 实例而不是在容器内重新拉起一个适合开发调试。快速上手复制即用# 1. 启动 Rancher如果尚未运行 export RANCHER_IP$(ifconfig | grep inet | grep -v 127.0.0.1 | head -1 | awk {print $2}) docker run -d --name rancher-server --restartunless-stopped \ -p 80:80 -p 443:443 --privileged \ -e CATTLE_SERVER_URLhttps://${RANCHER_IP} \ -e CATTLE_BOOTSTRAP_PASSWORDadmin \ -e CATTLE_DEV_MODEyes \ -e CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head \ rancher/rancher:v2.14-head # 2. 创建 k3d 下游集群并生成 config.yaml export CATTLE_BOOTSTRAP_PASSWORDadmin export CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head make integration-setup # 3. 运行测试 make integration-test-local对应的 Makefile 目标定义在 Makefilemake integration-setup构建 setup 二进制tests/v2/integration/bin/integrationsetup连接 Rancher、创建 k3d 下游集群并将连接信息写入tests/v2/integration/config.yamlmake integration-test-local读取config.yaml并运行完整测试套件CGO_ENABLED0 go test -v -failfast -timeout 30m -p 1 ./tests/v2/integration/...。如果之前已生成过config.yaml可以直接跳过第 2 步执行第 3 步。分步详解Step 1启动 Rancher Serverexport RANCHER_IP$(ifconfig | grep inet | grep -v 127.0.0.1 | head -1 | awk {print $2}) docker run -d --name rancher-server --restartunless-stopped \ -p 80:80 -p 443:443 \ --privileged \ -e CATTLE_SERVER_URLhttps://${RANCHER_IP} \ -e CATTLE_BOOTSTRAP_PASSWORDadmin \ -e CATTLE_DEV_MODEyes \ -e CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head \ rancher/rancher:v2.14-head等待 Rancher 就绪until curl -sk https://${RANCHER_IP}/ping | grep -q pong; do echo waiting for Rancher...; sleep 5; doneStep 2构建并运行 Integration Setupsetup 程序负责连接 Rancher、创建 k3d 下游集群并导入、最后写出测试配置文件# 构建 setup 二进制在仓库根目录执行 cd tests/v2/integration ./scripts/build-integration-setup # 产出: tests/v2/integration/bin/integrationsetup # 运行 setup回到仓库根目录 cd ../../.. export CATTLE_BOOTSTRAP_PASSWORDadmin export CATTLE_AGENT_IMAGErancher/rancher-agent:v2.14-head export CATTLE_TEST_CONFIG$(pwd)/tests/v2/integration/config.yaml ./tests/v2/integration/bin/integrationsetupsetup 程序会自动探测 Rancher 主机 IP、生成 admin Token、创建 k3d 集群、导入 Rancher并把连接信息写入CATTLE_TEST_CONFIG指定的路径。Step 3可选手动创建config.yaml如果已有带导入集群的 Rancher 实例可以跳过 setup 二进制直接创建配置文件字段说明见下文“配置参考”。Step 4运行测试export CATTLE_TEST_CONFIG$(pwd)/tests/v2/integration/config.yaml # 运行全部集成测试 go test -v -timeout 30m -failfast -p 1 ./tests/v2/integration/... # 运行指定测试套件 go test -v -count1 -timeout 30m -run TestChartsTestSuite ./tests/v2/integration/catalogv2/ # 运行套件内的具体测试 go test -v -count1 -run TestRTBTestSuite/TestUserVsUserBaseGlobalRoleVisibility ./tests/v2/integration/rbac/ # 仅运行 Steve API 测试仅 local 集群无需下游集群 go test -v -count1 -run TestSteveLocal ./tests/v2/integration/steveapi/常用go test参数参数示例说明-timeout-timeout 30m整个测试二进制的硬性截止时间。默认10 分钟对需要拉取外部仓库的 catalog 类测试来说太短完整套件建议30m-run-run TestChartsTestSuite只运行匹配正则的测试/套件支持/选择子测试-run Suite/TestName-count-count1禁用测试结果缓存。运行集成测试时应始终加-count1确保是全新执行-v-v详细输出逐个打印测试名与 PASS/FAIL便于定位挂起的测试-failfast-failfast首个测试失败即停止CI 中用于避免失败后继续浪费资源-p-p 1并行构建/运行的测试包数量。集成测试必须为1避免资源冲突配置参考config.yaml测试配置文件的路径由环境变量CATTLE_TEST_CONFIG指定。最小示例rancher: adminToken: token-xxxxx:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy host: 192.168.1.100 # Rancher 主机不含 https://末尾无斜杠 clusterName: my-k3d-cluster # Rancher 中导入的下游集群名称 insecure: true cleanup: true全部支持字段字段类型说明是否必填rancher.adminTokenstring用于 admin API 访问的 Bearer Token。可在 Rancher UI 获取用户头像 → Account API Keys → Create API KeyNo Scope是rancher.hoststringRancher 服务器主机名或 IP不含协议 scheme、末尾无斜杠是rancher.clusterNamestringRancher 中下游集群的名称。下游相关测试必填仅测 local 集群时填local是rancher.insecurebool跳过 TLS 校验适用于自签名证书。默认false否rancher.cleanupbool测试是否删除其创建的资源。默认true否rancher.adminPasswordstringadmin 密码adminToken的替代方案否rancher.caFilestring用于 TLS 校验的 CA 证书文件路径否rancher.caCertsstring内联 PEM 编码的 CA 证书否环境变量变量使用者说明CATTLE_TEST_CONFIG测试 setup必填。config.yaml的绝对路径。运行测试或 setup 二进制前必须导出CATTLE_BOOTSTRAP_PASSWORD仅 setupRancher 首次登录的引导密码。默认adminCATTLE_AGENT_IMAGE仅 setupRancher agent 的完整镜像引用如rancher/rancher-agent:v2.14-head导入 k3d 集群时使用CATTLE_RANCHER_HOST仅 setup覆盖自动探测的 Rancher 主机如192.168.1.100:443或localhost:8443。未设置时setup 二进制通过探测机器出站 IP 确定主机关于主机探测机制tests/v2/integration/setup/main.go 给出了实现细节默认通过向8.8.8.8:80建立 UDP socket 读取本地地址来获取出站 IP并用fmt.Sprintf(%s:443, ip)拼出host当CATTLE_RANCHER_HOST非空时直接使用该值。rancherConfig中的AdminToken、Host、Cleanup、ClusterName、AdminPassword字段均由 setup 程序生成并写入配置。测试套件一览Test Suites仅使用local集群的测试不需要下游集群只需基础config.yaml即可运行标记为“需要下游集群”的测试必须通过rancher.clusterName引用已导入的集群目录测试函数测试内容需要下游集群catalogv2/TestChartsTestSuiteChart 安装、容忍度、pull-through是catalogv2/TestClusterRepoTestSuiteClusterRepo CRUD、OCI 仓库否catalogv2/TestSystemChartsVersionSuite系统 chart 版本约束否catalogv2/TestUIPluginSuiteUI 插件扩展否catalogv2/TestRancherManagedChartsSuiteRancher 托管的 Helm chart否clusters/TestK8sProxy经 Rancher 的 K8s API 代理是projects/TestResourceQuotaTestSuite命名空间资源配额否projects/TestProjectUserTestSuite项目级用户访问否rbac/TestRTBTestSuite角色/ClusterRole 模板绑定、features、impersonation、projects否使用localsteveapi/TestSteveLocalSteve 资源列表 APIlocal 集群否steveapi/TestSteveDownstream下游集群上的 Steve API是当前跳过users/TestUserTestSuite用户 CRUD 操作否authconfigs/TestAuthConfig认证配置管理否serviceaccount/TestSATestSuiteServiceAccount Token 处理否上述目录均位于仓库tests/v2/integration/下例如 tests/v2/integration/catalogv2、tests/v2/integration/rbac。测试环境搭建细节Test Setup Details集成测试的 setup 逻辑分布在scripts/test与 tests/v2/integration/setup/main.go 中。后者主要承担四项职责生成并保存测试配置文件供集成测试使用创建一个用户及对应 Token供测试访问 Rancher在 local 集群中创建新的测试命名空间并以 Secret 形式部署 Docker 容器注册表凭据在default命名空间部署两个注册表。scripts/test中对应流程可参看其build-integration-setup、integrationsetup、go integration tests三段调用。注册表Registry搭建setup 过程中部署的两个注册表各有分工第一个注册表按常规方式配置支持镜像的 push 与 pull第二个注册表配置为pull-through 缓存唯一目的是缓存下游集群创建容器时拉取的镜像以加速测试过程。创建注册表的同时会向上述测试命名空间部署对应的 Secret。随后由scripts/ci本地构建的 cattle cluster agent 镜像会被推送到第一个注册表供下游集群拉取。两个注册表的配置会被合并用于创建集成测试使用的测试集群——合并后的注册表配置正是下游集群能够访问 local 集群内注册表的关键。下游集群的供应方式集成测试 setup 中创建下游集群的方式与 v2 provisioning 测试完全一致通过github.com/rancher/rancher/tests/v2prov/cluster包提供的cluster.New()函数创建。该函数利用 Rancher 的 v2 provisioning 功能在测试命名空间中创建一个运行 machine provisioner 的容器machine provisioner 再创建systemd-node容器由其自建一个内嵌的 Kubernetes 集群。最终的整体形态为一个运行 Rancher 运行时环境的 Docker 容器其中scripts/test正在运行集成测试RancherRancher 的 “local” 集群k3s 集群其中运行若干容器网络相关组件以及 rancher-webhook 等 Rancher 特有组件一个systemd-node容器其中运行“下游集群”一个运行 cluster agent 及其他 Rancher 下游组件的 k3s 集群这一嵌套架构说明一次make ci实际上在同一运行时环境内容纳了 Rancher 服务器、local 集群与下游集群三层结构这也是它对 CPU 与内存要求较高的原因。小结Rancher 测试框架以 Shepherd 为核心将测试划分为 framework、clients、extensions 三个层次并明确区分“快速、无外部依赖”的集成测试与“需要外部服务与配置”的验证测试。编写测试时遵循“Suite 共享客户端与会话、测试名不含/、优先使用框架客户端、测试自行清理资源”的规范即可写出同构、可复用、可清理的测试。运行时既可通过make ci在容器内一键完成端到端验证也可通过make integration-setupmake integration-test-local对已运行的 Rancher 实例做快速迭代config.yaml的字段与CATTLE_*系列环境变量则提供了从 Token、主机、集群名到 TLS 校验、资源清理策略的完整可控项。【免费下载链接】rancherComplete container management platform项目地址: https://gitcode.com/GitHub_Trending/ra/rancher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考