BKE 安装部署 E2E 测试

概述

本测试套件用于验证 BKE（Bocloud Kubernetes Engine）集群安装部署功能的端到端测试，基于 Ginkgo v2 测试框架实现。测试涵盖了从基础集群创建、扩缩容到高级特性（如节点标签、Addon 亲和性部署）的完整生命周期验证。

重要：BKE 已完成 BKECluster/BKENode CRD 拆分（简称"bc 拆分"）。集群拓扑中的节点信息从 BKECluster 资源中分离到独立的 BKENode 资源，创建集群时需要分别提供集群配置和节点配置两个文件。

测试范围

测试场景	描述	Label
创建 1Master 集群	创建单 Master 节点的集群并验证基础组件	1master
集群扩容	向已有集群添加新节点（创建 BKENode）并验证 Ready 状态	scale
集群缩容	从已有集群移除节点（删除 BKENode）并验证资源回收	scale
节点标签功能	验证 BKENode 上的自定义标签、多标签、非法字符过滤	node-labels
Addon 亲和性	验证 Addon 根据节点标签进行定向调度	node-labels-addon-affinity
NUMA 亲和性组件	验证 NUMA 亲和性扩展组件（Volcano）的安装	numa-affinity
集群删除	验证集群销毁及相关资源的清理	delete
引导节点初始化	验证 bke init 命令初始化引导节点	guide-install
离线引导节点初始化	验证离线模式下 bke init --offline 初始化引导节点	offline-guide-install
离线管理集群安装	验证离线模式下安装带 cluster-api 的管理集群	offline-mgmt-install
管理集群安装	验证创建带 cluster-api 的管理集群	mgmt-1master, mgmt-3master
业务集群单跳升级	业务集群从v26.05升级到v26.06，涉及1m1w和3m1w集群	declarative-upgrade-upgrade, post-init, single-upgrade
管理集群单跳升级	管理集群从v26.05升级到v26.06，涉及1m1w和3m1w集群	declarative-upgrade-mgmt-upgrade, post-init, single-upgrade
业务集群两跳升级	业务集群从v26.05升级到v26.07，涉及1m1w和3m1w集群	declarative-upgrade-upgrade, post-init, multi-upgrade
管理集群两跳升级	管理集群从v26.05升级到v26.07，涉及1m1w和3m1w集群	declarative-upgrade-mgmt-upgrade, post-init, multi-upgrade

目录结构

installation/
├── installation_suite_test.go       # 测试套件入口及全局配置
├── installation_test.go             # 核心测试用例
├── guide_installation_test.go       # 引导节点初始化测试
├── offline_installation_test.go     # 离线安装测试用例
├── management_cluster_test.go       # 管理集群安装测试
├── framework.go                     # SIG 描述函数封装
├── cluster_test_helpers.go          # 测试辅助函数（3M1W 集群等）
├── .env.bke.template                # 环境变量配置模板
├── README.md                        # 本文档
├── bke-config/
│   ├── types.go                     # 类型定义（模板路径、节点信息等）
│   └── cluster_config.go            # 配置加载函数（从环境变量读取）
├── declarative-upgrade/             # 声明式组件架构适配
│   ├── declarative_upgrade_install_helpers.go     # 公共函数
│   ├── declarative_upgrade_install_test.go        # 业务集群安装测试用例
│   ├── declarative_upgrade_mgmt_install_test.go   # 管理集群安装测试用例
│   ├── declarative_upgrade_mgmt_upgrade_test.go   # 管理集群升级测试用例
│   ├── declarative_upgrade_suite_test.go          # 测试套件入口及全局配置
│   ├── declarative_upgrade_upgrade_test.go        # 业务集群升级测试用例
│   └── framework.go                               # SIG 描述函数封装
└── utils/
    ├── yaml_helper.go               # BKECluster + BKENode 配置生成工具
    ├── cluster_checker.go           # 集群状态检查工具
    └── cluster_manager.go           # 集群生命周期管理工具

前置条件

1. 引导集群已部署：需要一个已运行的引导集群（管理集群）。
2. BKE 模板文件就位：引导集群上需要有 BKECluster 模板，如 /bke/cluster/1master-cluster.yaml。BKENode 配置由测试代码动态生成，无需模板。
3. yq 工具已安装：引导节点必须安装 yq (v4+)，用于动态修改集群配置。
4. 测试节点已准备：用于创建业务集群的节点需满足 BKE 部署要求，且 SSH 互通。
5. SSH 访问权限：测试执行机需具备通过 SSH 访问引导节点的权限。

环境配置

1. 复制环境变量模板：

   cp .env.template .env
   

2. 编辑 .env 填写实际环境信息（引导节点信息、测试节点 IP/密码等）。

运行测试

安装依赖

cd e2e/installation
go mod tidy

使用 Ginkgo CLI 运行（推荐）

# 安装 ginkgo CLI
go install github.com/onsi/ginkgo/v2/ginkgo@latest

# 运行全部测试
ginkgo -v ./...

# 运行特定特性的测试
ginkgo -v --label-filter="node-labels" ./...
ginkgo -v --label-filter="numa-affinity" ./...
ginkgo -v --label-filter="install-upgrade-delete-chart-from-oci-repo" ./...
ginkgo -v --label-filter="install-chart-from-https-repo" ./...
ginkgo -v --label-filter="install-chart-from-http-repo" ./...

# 运行引导节点初始化测试
ginkgo -v --label-filter="guide-install" ./...

# 运行离线引导节点初始化测试
ginkgo -v --label-filter="offline-guide-install" ./...

# 运行离线管理集群安装测试
ginkgo -v --label-filter="offline-mgmt-install" ./...

# 运行所有离线测试
ginkgo -v --label-filter="offline-guide-install || offline-mgmt-install" ./...

# 运行管理集群测试
ginkgo -v --label-filter="mgmt-1master || mgmt-3master" ./...

# 增加超时时间运行全量测试（防止大规模集群创建超时）
ginkgo -v --timeout=3h ./...

用例标签说明

安装部署自动化用例会根据以下标签进行筛选用例运行：

场景标签

标签	含义
offline	离线安装场景
custom-repo	自定义仓库场景
online	在线安装场景

运行阶段标签

标签	含义
pre-init	引导节点初始化前
post-init	引导节点已就绪
with-management-cluster	管理集群已就绪
with-workload-cluster	业务集群已就绪

其他标签

标签	含义
skip-temporarily	未就绪用例，临时跳过

核心功能说明

BKECluster / BKENode 资源拆分

集群创建现在涉及两类 CRD 资源：

• BKECluster：集群级别配置（网络、版本、Addon 等），由引导节点上的模板生成。
• BKENode：每个节点对应一个 BKENode 资源，包含 hostname、IP、密码、角色等信息，通过 label cluster.x-k8s.io/cluster-name 关联到所属集群。BKENode 配置由测试代码根据节点列表动态生成。

创建命令变更：

# 旧命令（已废弃）
bke cluster create -f <cluster.yaml>

# 新命令
bke cluster create -f <cluster.yaml> -n <nodes.yaml>

扩缩容变更：

• 扩容：直接创建新的 BKENode 资源（kubectl apply），无需修改 BKECluster。
• 缩容：根据节点 IP 查找对应的 BKENode 资源后删除（kubectl delete）。

节点标签与亲和性验证

测试套件会自动在 BKENode 资源中注入自定义标签，并验证：

• 标签是否正确同步到业务集群的 Node 对象。
• Addon（如 Redis）是否根据 nodeSelector 调度到指定标签的节点。
• 非法标签（含空格等）是否被正确过滤。

NUMA 亲和性组件 (Volcano)

验证 numa-affinity-package Addon 的安装：

• 检查 numa-affinity-package 命名空间下的安装器状态。
• 检查 volcano-system 命名空间下的核心组件（Scheduler, Controller, Admission）是否全部就绪。

离线安装测试

离线安装测试用于验证在断网环境下从本地离线包进行安装的场景：

离线引导节点初始化测试 (offline-guide-install)：

用例	描述	预期结果
指定正确的 oFVersion	使用 --oFVersion v25.10	初始化成功
指定不存在的 oFVersion	使用 --oFVersion v99.99	初始化失败，报错 failed to start cluster API
不指定 oFVersion	使用默认的 latest 版本	初始化成功

离线管理集群安装测试 (offline-mgmt-install)：

用例	描述	预期结果
创建 1Master 管理集群	离线初始化后，使用 bke cluster create 安装带 cluster-api 的管理集群	集群创建成功，状态变为 Healthy

离线测试使用 bke init 命令（与在线一致），镜像从引导节点预装的离线包加载，而非从远程仓库拉取。离线包会在测试环境中提前制备好。

测试流程

1Master 集群创建测试流程

1. 从引导节点读取 BKECluster 模板文件 (/bke/cluster/1master-cluster.yaml)
2. 复制模板到临时文件
3. 使用 yq 修改集群名称（并移除模板中残留的节点信息）
4. 根据节点列表动态生成 BKENode 配置文件（多文档 YAML）
5. 执行 bke cluster create -f <cluster.yaml> -n <nodes.yaml>
6. 轮询检查 BKECluster 资源状态直到 Ready
7. 通过 kubectl 验证业务集群状态：
   - 节点数量和状态
   - 系统组件 Pod 状态
   - CoreDNS 运行状态
   - Calico 网络状态
8. 测试完成后删除集群并清理临时文件（集群配置 + 节点配置）

工具说明

YAMLModifier

用于在引导节点上生成 BKECluster 和 BKENode 配置文件：

modifier := utils.NewYAMLModifier(sshExecutor)

// 生成集群配置 + 节点配置（返回两个文件路径）
clusterConfigPath, nodeConfigPath, err := modifier.GenerateAndUpload(
    "/bke/cluster/1master-cluster.yaml",  // BKECluster 模板路径
    "my-cluster",                          // 集群名称
    nodes,                                 // 节点列表
)

// 为扩容生成单个 BKENode YAML
nodePath, err := modifier.GenerateSingleBKENodeYAML("my-cluster", newNode)

ClusterChecker

用于检查业务集群状态：

checker := utils.NewClusterChecker(sshExecutor, "my-cluster")

// 获取节点数量
nodeCount, _ := checker.GetNodeCount()

// 检查系统 Pod 状态
allRunning, notRunning, _ := checker.CheckSystemPods()

// 获取资源状态概览
status, _ := checker.GetClusterResourceStatus()

ClusterManager

封装集群生命周期管理操作：

manager := utils.NewClusterManager(sshExecutor, dynamicClient)

// 创建集群（需要同时传入集群配置和节点配置路径）
manager.CreateCluster(clusterConfigPath, nodeConfigPath)

// 等待集群就绪
manager.WaitForClusterReady(ctx, "my-cluster", 30*time.Minute)

// 扩容节点（创建 BKENode 资源）
manager.ScaleOutNode("my-cluster", newNode)

// 缩容节点（根据 IP 查找并删除 BKENode 资源）
manager.ScaleInNode("my-cluster", nodeIP)

// 删除集群
manager.DeleteCluster("my-cluster", true)

故障排查

Kubeconfig 获取失败

现象：报错 error loading config file ... no such file or directory。 原因：测试脚本尝试从引导节点获取业务集群的 kubeconfig。 解决：脚本已支持从 Secret (bke-<name>-kubeconfig) 和文件路径 (/root/.bke/...) 多重获取。请确保引导集群的 kubectl 权限正常。

测试套件超时 (Suite Timeout)

现象：[TIMEDOUT] A suite timeout occurred。 原因：全量测试耗时较长（每个集群创建/删除约 15-20 分钟），超过了默认的 1 小时限制。 解决：运行命令时添加 --timeout=3h 参数。

缩容节点失败

现象：节点数量未减少，测试超时。 原因：可能是根据 IP 未找到对应的 BKENode 资源，或 BKE 控制器未触发节点重置。 解决：检查引导集群上的 BKENode 资源是否存在：kubectl get bkenode -A，确认节点 IP 与 BKENode spec 中的 IP 一致。

SSH 连接失败

检查：

• 引导节点 IP 和端口是否正确
• SSH 用户名密码是否正确
• 防火墙是否开放 SSH 端口

yq 命令不存在

在引导节点安装 yq：

# 使用 snap（Ubuntu）
sudo snap install yq

# 或下载二进制
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

集群创建超时

• 检查引导节点日志：journalctl -u bke-controller
• 检查 BKECluster 资源状态：kubectl get bkecluster -A -o yaml
• 检查 BKENode 资源状态：kubectl get bkenode -A -o yaml
• 检查测试节点网络连通性

扩展开发

添加新 Addon 测试

在 installation_test.go 的 Describe("Addon 扩展组件安装", ...) 块中添加新的 It 用例，并使用 checker.CheckNamespacePodsReady 进行状态验证。

添加新的测试用例

1. 在 installation_test.go 中添加新的 Describe 块
2. 使用 Label() 标记测试类别
3. 复用 ClusterManager 和 ClusterChecker 工具

示例：

Describe("创建 3Master 高可用集群", Label("3master", "ha"), func() {
    It("应该成功创建 3 Master 集群", func() {
        // 生成配置
        clusterConfigPath, nodeConfigPath, err := modifier.GenerateAndUpload(
            templatePaths.ThreeMasterClusterTemplate,
            "ha-cluster",
            nodes,
        )
        Expect(err).NotTo(HaveOccurred())

        // 创建集群
        err = manager.CreateCluster(clusterConfigPath, nodeConfigPath)
        Expect(err).NotTo(HaveOccurred())

        // 等待就绪并验证
        manager.WaitForClusterReady(ctx, "ha-cluster", 30*time.Minute)
    })
})