K3s 测试体系全景指南Unit、Integration、Docker、Install、E2E 与性能测试实战【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 是一个面向边缘、开发环境和生产小规模集群的轻量级 Kubernetes 发行版其质量保障依赖一套分层清晰、覆盖从函数级到整集群运维级的完整测试体系。本文基于仓库中的 tests/TESTING.md 测试标准文档结合 tests/integration/README.md、tests/e2e/README.md、tests/perf/README.md 以及真实的测试源码系统讲解 K3s 七类测试的适用场景、框架选型、命名规范与运行方法。读完本文你将掌握 K3s 每种测试何时写、怎么写、怎么跑的完整标准能够为 K3s 贡献新测试或在本地复现其 CI 测试流程。一、K3s 测试体系总览K3s 的测试体系共分七种形式覆盖从单元级白盒验证到大规模集群黑盒运维验证的完整链路测试类型验证层次核心工具典型运行时机单元测试Unit单个包内的函数/组件Go 标准 testing gotestsPR 验证、覆盖率统计集成测试Integration跨多个 Go 包的功能Ginkgo GomegaPR 验证Docker 测试容器化的多节点集群Docker GinkgoDrone CI test 阶段安装测试Install各发行版上的安装与运行Vagrant每晚定时 install.sh 变更时性能测试Performance大规模集群伸缩Terraform clusterloader2专项压测端到端测试E2E多节点集群配置与运维Ginkgo Vagrant每晚 QADistros 测试框架特性级集群验证distros-test-framework验收测试本文之后所有命令均在 k3s 仓库根目录下执行tests/TESTING.md 的原始约定。二、单元测试Unit Tests白盒验证包内逻辑2.1 何时写单元测试当某个**包内package**的组件或函数需要验证时就应当编写单元测试。单元测试用于白盒white box测试即直接调用被测函数、深入其内部实现细节进行验证。2.2 框架Table Driven Test gotests 自动生成K3s 的所有单元测试遵循 Go 社区的 Table Driven Test 风格——用一个结构体切片定义输入与期望输出通过循环驱动同一段断言逻辑。具体生成上K3s 使用 gotests 工具自动生成测试骨架gotests 内置于 VS Code 的 Go 扩展中也支持其他主流编辑器的集成或通过命令行直接运行K3s 提供了一套自定义模板来扩展生成测试的功能位于 contrib/gotests_templates包含header.tmpl、function.tmpl、inputs.tmpl、results.tmpl等用于定制测试文件的包声明、导入、输入输出构造等代码骨架。使用命令行调用自定义模板gotests --template_dirPATH_TO_K3S/contrib/gotests_templates在 VS Code 中则编辑 Go 扩展设置Go: Generate Tests Flags把--template_dirPATH_TO_K3S/contrib/gotests_templates添加为一个 item 即可。为便于单元测试的创建K3s 还提供了 tests/unit.go 辅助函数其中最核心的两个是GenerateDataDir(cnf *config.Control)在/tmp/k3s/随机字符串/创建临时数据目录并把最新目录软链接到/tmp/k3s/latest/从而模拟/var/lib/rancher/k3s的目录结构GenerateRuntime(cnf *config.Control)创建临时数据目录并配置好config.ControlRuntime所需的全部证书密钥调用deps.CreateRuntimeCertFiles与deps.GenServerDeps同时重置 Prometheus 注册器以避免测试覆盖指标注册时发生 panicCleanupDataDir(cnf *config.Control)清理上述临时目录及latest软链接。2.3 格式规范单元测试文件必须放在被测文件所在的包内文件名规则被测文件_test.go函数名规则Test_Unit被测函数或Test_Unit接收者_被测方法。原文档以 pkg/etcd/etcd_test.go 为例当前仓库中 etcd 包的测试实际拆分为 pkg/etcd/etcd_linux_test.go 与 pkg/etcd/resolver_test.go命名即遵循上述规范。在仓库中还可以看到大量遵循Test_Unit...命名的用例例如 pkg/clientaccess/token_test.go、pkg/agent/containerd/config_test.go 等。2.4 运行与覆盖率go test ./pkg/... -run Unit单元测试直接调用函数因此是 K3s代码覆盖率指标的主要驱动者。仓库中的 GitHub Actions 工作流 .github/workflows/unitcoverage.yaml 印证了这一点——它在 push/PR 时于 Ubuntu 24.04 与 Windows 2022 上分别执行go test -coverpkg ./pkg/... -coverprofile coverage.out ./pkg/... -run Unit go tool cover -func coverage.out并把coverage.out上传到 Codecov 进行覆盖率统计。可见单元测试在 K3s 中承担着覆盖率守门员的角色。三、集成测试Integration Tests黑盒验证跨包功能3.1 何时写集成测试当需要验证横跨多个 Go 包的特定功能时——通常通过导出函数调用更多时候通过 CLI 命令——就应当编写集成测试。集成测试用于黑盒black box测试不关心内部实现只验证外部行为。详细说明见 tests/integration/README.md。3.2 框架BDD 风格 Ginkgo GomegaK3s 的集成测试采用**行为驱动开发BDD**风格具体使用 Ginkgo 和 Gomega 驱动。初始化测试时可用ginkgo bootstrap命令生成骨架。为便于 K3s CLI 测试可复用tests/util/cmd.go中的辅助函数仓库当前将其与tests/client.go中的 Kubernetes API 辅助函数合并见下文。3.3 格式规范所有集成测试放在tests/integration/测试名/目录下文件名测试名_int_test.go函数名Test_Integration测试名。以 tests/integration/localstorage/localstorage_int_test.go 为例其结构展示了完整的 BDD 组织方式BeforeSuite中调用testutil.K3sStartServer(--cluster-init)启动带--cluster-init嵌入式 etcd参数的 k3s serverDescribe/When/It三级描述依次验证默认 Deploymentcoredns、local-path-provisioner、metrics-server、traefik就绪 → 创建 PVC → 创建 Pod → 在kubectl get pvc/pv/pod中可见 → 存储目录权限/var/lib/rancher/k3s/storage为 0700、卷目录为 0777、文件为 644→ 非 root Pod 可写卷 → 正确删除AfterSuite中若测试失败则调用K3sSaveLog、K3sCopyPodLogs、K3sDumpResources收集现场随后K3sKillServer杀掉 server 并K3sCleanup清理。该测试引用的tests.CheckDefaultDeployments定义在 tests/client.go 中它检查 kube-system 命名空间下 coredns、local-path-provisioner、metrics-server、traefik 四个默认 Deployment 是否全部达到就绪副本数。同文件还提供了CheckDeployments、NodesReady、AllPodsUp、GetDaemonsetReady、ParseNodes/ParsePods、GetNodeIPs/GetPodIPs支持双栈场景等一系列跨测试框架复用的 Kubernetes API 断言工具函数。3.4 运行方式集成测试无需预先准备 k3s 集群——每个测试会自行拉起并销毁所需的 k3s server。注意集成测试必须以 root 运行sudo 用户需加上sudo -E env PATH$PATH前缀go test ./tests/integration/... -run Integration -ginkgo.v -test.v要生成 JUnit 报告则使用 Ginkgo CLIginkgo --junit-reportresult.xml ./tests/integration/...在已有单节点集群上运行通过编译期标志指定若 server 配置不满足测试要求则自动跳过go test -ldflags -X github.com/k3s-io/k3s/tests/integration.existingServerTrue ./tests/integration/... -run Integration -ginkgo.v -test.v通过 Sonobuoy 插件运行K3s 提供了 Sonobuoy 插件方式在已有单节点集群上执行集成测试./scripts/build-tests-sonobuoy sudo KUBECONFIG/etc/rancher/k3s/k3s.yaml sonobuoy run --plugin ./dist/artifacts/k3s-int-tests.yaml查看状态并取回结果sudo KUBECONFIG/etc/rancher/k3s/k3s.yaml sonobuoy status sudo KUBECONFIG/etc/rancher/k3s/k3s.yaml sonobuoy retrieve sudo KUBECONFIG/etc/rancher/k3s/k3s.yaml sonobuoy results TAR_FILE_FROM_RETRIEVE四、Docker 测试容器化的集群冒烟验证Docker 测试将多个 K3s 节点以容器形式组成集群用于验证基础功能。这类测试在 Drone CI 管道的test阶段运行。从仓库源码可以看到其具体形态以 tests/docker/autoimport/autoimport_test.go 为例测试通过docker.NewTestConfig(rancher/systemd-node)创建容器节点配置tc.ProvisionServers(1)拉起 server 容器然后断言镜像自动导入auto import功能——在/var/lib/rancher/k3s/agent/images/写入镜像列表文件后用k3s ctr images list检查镜像是否被打上io.cattle.k3s.pinnedpinned与io.cri-containerd.pinnedpinned标签。这与 pkg/agent/containerd 及 pkg/spegel 的镜像分发实现相呼应。tests/docker 目录下的测试还包括 basics、bootstraptoken、cacerts、conformance、dualstack、etcd、hardened、lazypull、nixsnapshotter、scale、secretsencryption、selinux、skew、snapshotrestore、svcpoliciesandfirewall、t4、token、upgrade 等覆盖了从基础启动到证书轮换、快照恢复、双栈网络等广泛功能面。五、安装测试Install Tests多发行版安装验证5.1 覆盖范围安装测试是定义在 tests/install 下的一组测试用于验证 K3s 在多种操作系统上的安装与运行。测试本体是描述单节点安装的 Vagrantfile可通过 Vagrant 的libvirt和virtualboxprovider 快速拉起安装脚本tests/install触发的测试每晚定时运行并在 install.sh 变更时额外触发CentOS 9 StreamRocky Linux 8作为 RHEL 8 的替身Rocky Linux 9作为 RHEL 9 的替身Fedora 40Leap 15.6作为 SLES 的替身Ubuntu 24.04仓库中还可见 tests/install/alma-10、tests/install/opensuse-microos 等更多发行版目录。5.2 格式新增安装测试时请复制既有 Vagrantfile 的主流风格。理想情况下用于附加断言的 box 应支持默认的libvirtprovider从而能直接被 GitHub Actions 的 Install Test Workflow 使用。以 tests/install/rocky-9/Vagrantfile 为例其结构展示了完整模式通过ENV[TEST_INSTALL_SH] || ../../../install.sh指定被测安装脚本路径INSTALL_K3S_CHANNEL默认取latestconfig.vm.box bento/rockylinux-9boot_timeout读取TEST_VM_BOOT_TIMEOUT环境变量load ../install_util.rb加载 tests/install/install_util.rb 中定义的辅助函数provisioner 依次执行禁用防火墙 → 添加 bin 路径 → 上传 install.sh → 通过vagrant-k3s插件执行安装配置selinux: true、token: vagrant→ 等待 node 就绪 → 等待 CoreDNS / local-storage / metrics-server / traefik →kubectl get node,all -A -o wide→ 检查进程 → 检查 cgroup v2 → 挂载/卸载目录验证。tests/install/install_util.rb 中的每个辅助函数都是一个具名 provisioner辅助函数provisioner 名称作用waitForNodeReadyk3s-wait-for-node等待 node Ready最多 300s轮询 5swaitForCoreDnsk3s-wait-for-coredns等待 coredns Deployment rollout 完成120s失败时收集 describe/logwaitForLocalStoragek3s-wait-for-local-storage等待 local-path-provisioner 就绪120swaitForMetricsServerk3s-wait-for-metrics-server等待 metrics-server 就绪180s启动最慢waitForTraefikk3s-wait-for-traefik等待 traefik 就绪120skubectlStatusk3s-status输出kubectl get node,all -A -o widecheckK3sProcessesk3s-procps检查 k3s/kube/container 相关进程checkCGroupV2cgroupv2运行k3s check-config验证 cgroups V2mountDirs/checkMountPoint/unmountDirk3s-mount-directory等验证 server 目录挂载、检查挂载点、卸载并清理注意这些 provisioner 都带有run: ENV[CI] true ? never : once逻辑——在 CI 中默认不自动执行而是由 workflow 显式调用以避免慢 runner 上的超时问题下文运行章节会说明。5.3 框架Vagrant 插件与 ProviderVagrant 新手可参考 Hashicorp 官方的入门教程。需要特别注意libvirtprovider 必须先安装vagrant-libvirt插件且宿主机的 libvirtd 服务必须已安装并运行另外还需要vagrant-scp和vagrant-k3s插件。三者可一次性安装vagrant plugin install vagrant-scp vagrant-k3s vagrant-libvirt5.4 环境变量可在 CLI 上设置或导出后再调用 Vagrant变量默认值说明TEST_VM_CPUS2客户机使用的 vCPU 数量TEST_VM_MEMORY2048客户机使用的内存MBTEST_VM_BOOT_TIMEOUT600Vagrant 等待机器启动并可达的秒数5.5 运行安装脚本测试的运行方式是进入对应 fixture 目录执行vagrant up例如cd tests/install/rocky-8 vagrant up # 以下 provisioner 是可选的。GitHub Actions CI 中会显式调用它们 # 以避免慢 runner 上的超时问题 vagrant provision --provision-withk3s-wait-for-node vagrant provision --provision-withk3s-wait-for-coredns vagrant provision --provision-withk3s-wait-for-local-storage vagrant provision --provision-withk3s-wait-for-metrics-server vagrant provision --provision-withk3s-wait-for-traefik vagrant provision --provision-withk3s-status vagrant provision --provision-withk3s-procps仓库中的 .github/workflows/install.yaml 展示了 CI 侧的完整流程它会在 push 到 main/master 或 PR 变更install.sh、tests/install/**、channel.yaml等路径时触发matrix 覆盖 centos-9、alma-10、rocky-9、fedora、opensuse-leap、ubuntu-2404设置INSTALL_K3S_SKIP_DOWNLOAD: binary使用本地构建的二进制并通过vagrant provision --provision-with...显式执行上述各验证步骤同时还有一个单独的 nightly 工作流 .github/workflows/nightly-install.yaml 负责每晚定时运行。六、性能测试Performance TestsTerraform 驱动的大规模压测性能测试使用Terraform在 AWS 上自动化构建和测试大规模 K3s 集群部署支持普通集群与 HA 集群N 个主节点、N 个 worker 节点存储后端支持MySQL RDSPostgres RDSEtcdSQLite脚本分为三个部分server部署存储后端 N 个主节点、agents部署 k3s agent、tests运行 clusterloader2 压测。server 部分还会额外创建用于 Prometheus 部署的 agent 节点clusterloader2 会部署 prometheus 与 grafana。测试部分使用clusterloader2的一个 forkkubernetes/perf-tests 的分支仅修改了日志记录并移除了 etcd 指标探测以 docker 化方式运行报告保存在tests/test_name-random-number。当前可用的测试为load test与density test。完整说明见 tests/perf/README.md。其配置集中在 tests/perf/scripts/config核心变量如下主变量变量说明CLUSTER_NAMEAWS 上的集群名会作为集群各组件的前缀DOMAIN_NAMEk3s 主节点的 Loadbalancer DNS 名称ZONE_IDAWS route53 zone id用于修改 DNS 名称K3S_VERSION集群使用的 K3s 版本EXTRA_SSH_KEYS添加到服务器的公钥PRIVATE_KEY_PATHclusterloader2 用于 SSH 收集指标用的私钥DEBUGk3s server 的调试模式数据库变量变量说明DB_ENGINE数据库类型mysql、postgres或etcdDB_INSTANCE_TYPEmysql/postgres 的 RDS 实例类型etcd 内部解析db.*系列DB_NAME数据库名仅 postgres 和 mysqlDB_USERNAME数据库用户名仅 postgres 和 mysqlDB_PASSWORD数据库密码仅 postgres 和 mysqlDB_VERSION数据库版本K3S Server 变量变量说明SERVER_HA是否启用 HA 模式不启用则使用 sqlite 作为存储后端SERVER_COUNTk3s 主节点数量SERVER_INSTANCE_TYPEk3s server 的 EC2 实例类型K3S Agent 变量变量说明AGENT_NODE_COUNT创建的 k3s agent 数量AGENT_INSTANCE_TYPEk3s agent 的 EC2 实例类型Prometheus server 变量变量说明PROM_WORKER_NODE_COUNT为 prometheus 部署创建的 k3s agent 数量PROM_WORKER_INSTANCE_TYPEk3s prometheus agent 的 EC2 实例类型使用方式tests/perf下的 Makefile 按 section 执行不同任务cd tests/perf make apply # 构建 db、server、agent 三层并部署 kubeconfig 到 tests/kubeconfig.yaml make test # 修改 tests/perf/tests/load/config.yaml 后启动 clusterloader2 压测 make destroy # 销毁集群 make clean # 清理七、端到端测试E2E Tests多节点集群运维验证7.1 定位与覆盖E2E 测试覆盖多节点 K3s 配置与管理集群启动bringup、升级update、拆除teardown等横跨多种操作系统。E2E 测试每晚作为 K3s 质量保证QA的一部分运行。7.2 框架与集成测试相同E2E 使用 Ginkgo 与 Gomega但底层依赖Vagrant提供集群配置。测试包含两部分Vagrantfile描述并配置测试所用的虚拟机TEST_NAME.go调用vagrant up并控制实际集群测试的 Go 测试文件。一个 E2E 测试的构成示例可参考 tests/e2e/validatecluster/validatecluster_test.go。仓库 tests/e2e 目录下还有 dualstack、embeddedmirror、externalip、multus、privateregistry、rootless、rotateca、s3、secretsencryption、splitserver、startup、tailscale、wasm、btrfs 等场景化测试每个均自带 Vagrantfile。7.3 环境搭建Vagrant请从官网下载最新版当前 2.2.19。不要使用发行版内置包——它们往往过旧或不包含使部分插件正常工作所需的 ruby 库扩展。Libvirt按操作系统官方指南安装 libvirt/qemu。例如 Ubuntu 24.04sudo apt install ruby-libvirt qemu-kvm libvirt-daemon-system libvirt-clients ebtables dnsmasq-base libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev libguestfs-toolsUbuntu 20.04 将qemu-kvm换为qemu其他发行版参考 tests/e2e/README.md 中给出的 openSUSE、Debian、Fedora 指南。Vagrant 插件vagrant plugin install vagrant-libvirt vagrant-scp vagrant-k3s vagrant-reloadKubectlLinux 示例curl -LO https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl7.4 运行E2E 测试通常作为每晚的 Jenkins QA 任务运行本地运行也可但可能需要额外配置。默认情况下所有 E2E 测试以libvirt作为底层 VM providerVirtualBox作为备用 provider。全套 E2E 测试go test -timeout15m ./tests/e2e/... -run E2E单个测试go test -timeout15m ./tests/e2e/validatecluster/... -run E2E # 或者 go test -timeout15m ./tests/e2e/... -run E2EClusterValidation生成 JUnit 报告ginkgo --junit-reportresult.xml ./tests/e2e/...注意go test默认超时是 10 分钟因此必须使用-timeout标志而ginkgo默认超时为 1 小时无需额外指定。7.5 调试测试失败时集群和虚拟机会保留在失败现场启动日志保留在vagrant.log中vagrant status查看节点列表vagrant ssh NODESSH 进入节点排查排查结束或准备重跑时用vagrant destroy -f移除故障集群。八、Distros 测试框架distros 测试框架的验收测试acceptance tests是一种可定制的集群创建与验证方式先按需求创建集群再对其执行校验从而验证特定功能和需求的满足情况。该框架由 rancher/distros-test-framework 项目提供适合对 K3s 的具体特性做定制化验收。九、如何贡献新测试K3s 欢迎各类新测试与测试更新。若要新增或修改测试请提交 PR且PR 标题必须包含测试名称 (Created/Updated)字样例如Etcd Snapshot (Updated)以便维护者快速识别变更性质。总结K3s 的测试体系是一个典型的金字塔 多维矩阵结构底层是覆盖pkg/各包逻辑、由 gotests 模板驱动、直接贡献覆盖率指标的单元测试中层是以 Ginkgo/Gomega BDD 风格验证跨包功能的集成测试和容器化的 Docker 测试上层则是以 Vagrant 驱动的多发行版安装测试与 E2E 测试以及以 Terraform clusterloader2 驱动的大规模性能测试。无论你希望为某个包补充单元用例、为某个功能新增集成测试还是参与多发行版安装验证都可以直接以本文给出的规范、命名约定与运行命令为起点向 K3s 提交符合标准的测试贡献。【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考