#VMware vSphere 基础设施准备

本文档将帮助你准备基础设施，并收集创建 VMware vSphere 业务集群所需的值。在应用 Create a Cluster on VMware vSphere 中的清单之前，请先完成此检查清单。

#场景

在以下场景中使用此检查清单：

• 你正在准备新的 VMware vSphere 集群部署。
• 你希望在开始部署之前验证外部依赖项。
• 你计划启用可选的创建时拓扑变体，例如多个数据中心、多个 NIC 或额外的工作节点。

#先决条件

开始之前，请确保满足以下条件：

• 你可以使用 global 访问 kubectl 集群。
• 业务集群对象必须存储在 cpaas-system 命名空间中。
• 你可以访问目标 vCenter 清单、网络、数据存储和模板。

#如何使用此检查清单

请按以下顺序使用此检查清单：

1. 收集本文档中列出的部署参数。
2. 将清单模板中的每个占位符替换为此处收集的实际值。
3. 如果某个值在多个清单中以占位符形式出现，请始终使用相同的值。
4. 如果未启用某项可选功能，请按照 Creation-Time Topology Variants 中的说明，准确省略相应的 YAML 块。
5. 如果不需要某个可选字段（例如 deviceName），请从 YAML 清单中删除整行。

#参数来源与安全收集

将参数收集分为以下三个来源。可以从 vCenter 发现某个值，并不意味着该值就是产品支持的版本；同样，产品提供的值也不能替代网络或容量方面的决策。

#使用 govc 可选地发现 vCenter 信息

如果 govc 已通过受保护的本地环境完成身份验证，请使用如下只读清单命令：

govc find / -type d
govc find / -type c
govc find / -type p
govc find / -type n
govc find / -type s
govc find / -type m

请将结果视为候选项，而非自动选择的对象：

• d：数据中心
• c：计算集群
• p：资源池
• n：网络或分布式端口组
• s：数据存储
• m：VM 和模板；请确认所选对象是模板

使用 Thumbprint 中的 openssl 命令检索证书指纹，而不显示 vCenter 凭证。

#术语

以下术语在 VMware vSphere 集群创建文档中保持一致。

#机器配置池

机器配置池是 VSphereMachineConfigPool 自定义资源。它预定义节点槽位。每个槽位可以包含：

• 节点主机名
• 目标数据中心
• 每个 NIC 的静态 IP 配置
• 持久磁盘定义

#节点槽位

节点槽位是 VSphereMachineConfigPool.spec.configs[] 下的一项。单个槽位通常映射到一个节点，例如 cp-01 或 worker-01。槽位 hostname 会驱动 Kubernetes 节点名称、kubelet 服务证书 DNS SAN，以及（与解析后的主 NIC 地址结合）kubelet 的 node-ip；它必须是有效的 DNS-1123 子域名。

#槽位网络布局

每个槽位都在 network.primary 和 network.additional 下声明其 NIC 布局：

• network.primary 为必需项。必须设置其 networkName，该值用作 kubelet 的 node-ip 来源。
• network.additional 是可选的额外 NIC 列表，会按照列出的顺序合并到主 NIC 之后。

VSphereMachineConfigPool.spec.configs[].network 中的 dns 值描述每个槽位的静态网络元数据。在受影响的 VMware 部署中，这些值可能无法可靠地更新来宾操作系统的 /etc/resolv.conf。因此，部署清单还会通过 KubeadmControlPlane.spec.kubeadmConfigSpec.files 和 KubeadmConfigTemplate.spec.template.spec.files 同时写入 /etc/resolv.conf。

#deviceName

deviceName 是 VSphereMachineConfigPool 网络配置中的可选字段。它用于控制来宾操作系统内部看到的 NIC 名称，例如 eth0 或 eth1。

填充值时请使用以下区分：

• networkName 是 vCenter 网络或端口组名称。
• deviceName 是来宾操作系统内部的 NIC 名称。
• 如果省略 deviceName，CAPV 通常会根据 NIC 顺序分配类似 eth0、eth1 和 eth2 的名称。

#vCenter 资源池

vCenter 资源池是 vCenter 原生清单对象，例如：

/Datacenter1/host/cluster1/Resources

启用故障域创建变体时，VSphereDeploymentZone.spec.placementConstraint.resourcePool 会使用此路径。

#计算集群

计算集群是目标 vCenter 计算集群名称。在本文档中，当 VSphereFailureDomain 映射到特定部署目标时，主要使用此名称。

#数据存储

数据存储是用于存储 VM 磁盘的 vSphere 存储位置。系统磁盘和数据磁盘都必须置于具体的数据存储上。

#VM 模板

VM 模板是用于创建节点虚拟机的源模板。启用多个数据中心时，同一模板必须已存在于每个目标数据中心中，并且必须能够通过相同的模板名称解析。

#指纹

指纹是 vCenter 服务器证书的 SHA-1 指纹。CAPV 使用它来验证目标 vCenter 服务器。

使用以下命令检索该指纹：

openssl s_client -connect <vsphere_server>:443 -servername <vsphere_server> </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha1

#管理集群先决条件

使用下表记录所需值和验证结果。

#vCenter 和模板先决条件

#vCenter 连接信息

注意：这些文档假设使用默认的 vCenter HTTPS 端口 443。

#VM 模板要求

模板还应满足以下要求：

• 使用平台镜像策略支持的操作系统。
• 包含 cloud-init。
• 包含 VMware Tools 或 open-vm-tools。
• 包含 containerd。
• 包含 kubeadm 引导所需的基线组件。
• 在 /root/images/ 下包含预先导出的容器镜像 tar 文件。这些文件会在运行 kubeadm 之前由 capv-load-local-images.sh 导入 containerd，因此节点引导不依赖于从远程 Registry 拉取镜像。
• tar 文件包含随 OS 模板提供的 kubeadm 控制平面镜像，包括 etcd 和 kube-apiserver，并且这些镜像使用根据 clusterConfiguration.imageRepository、Kubernetes 版本和组件镜像标签生成的确切镜像引用。尽管 etcd 和 kube-apiserver 作为静态 Pod 运行，但仍需要容器镜像。缺失或不匹配的本地引用会导致运行时改为尝试从配置的 Registry 获取镜像。
• /root/images/*.tar 文件必须包含 sandbox（pause）镜像，并且其引用必须与 /etc/containerd/config.toml 中配置的 sandbox_image 值（containerd v1）或 sandbox 值（containerd v2）完全匹配。例如，如果 containerd 配置为 sandbox_image = "registry.example.com/tkestack/pause:3.10"，则其中一个 tar 文件必须包含该确切的镜像引用。不匹配会导致 containerd 从网络拉取 sandbox 镜像，从而违背本地预加载的目的，并在 air-gapped 环境中失败。

#负载均衡器前提条件

本节介绍基线集群使用的外部负载均衡器端点。请在创建集群之前完成配置，并遵循规划控制平面端点。也可以使用 provider 管理的 Self-built VIP 创建集群，此方式无需外部负载均衡器，并且要求 ACP v4.4 或更高版本；请参阅控制平面端点模式。

#集群基线参数

#Registry tag 验证

首先从 global 集群读取永久 Registry 地址，或向平台管理员确认等效地址：

kubectl -n cpaas-system get cluster global \
  -o jsonpath='{.metadata.annotations.cpaas\.io/registry-address}{"\n"}'
kubectl -n cpaas-system get secret public-registry-credential -o name

Secret 命令仅验证是否存在，不会打印凭证数据。导出已确认的集群 Registry 地址，以及 CPI 和 kubeadm manifest 使用的镜像 Registry。如果两个占位符指向同一个 Registry，则对两个变量使用相同的值。

export CLUSTER_REGISTRY_ADDRESS="<registry_address>"
export IMAGE_REGISTRY_ADDRESS="<image_registry>"
# Repository names depend on the target version. The values below are the
# ACP v4.4 and later ones; for an earlier target, change them to:
#   Kube-OVN chart -> acp/chart-cpaas-kube-ovn
#   CoreDNS        -> tkestack/coredns
export KUBE_OVN_CHART_REPO="acp/chart-kube-ovn"
export COREDNS_REPO="acp/coredns"

curl -sk "https://${CLUSTER_REGISTRY_ADDRESS}/v2/${KUBE_OVN_CHART_REPO}/tags/list"
curl -sk "https://${IMAGE_REGISTRY_ADDRESS}/v2/${COREDNS_REPO}/tags/list"
curl -sk "https://${IMAGE_REGISTRY_ADDRESS}/v2/acp/cloud-provider-vsphere/tags/list"

NAME_UNKNOWN 响应表示仓库名称与目标版本不匹配；请根据上面的映射修正 KUBE_OVN_CHART_REPO 或 COREDNS_REPO 并重试，而不要将其解读为缺少 tag。

权威的 chart-name 边界位于控制平面之前升级 Kube-OVN。

/v2/ 片段仅属于这些 Registry HTTP API URL。镜像引用使用 <registry>/<repository>:<tag>，而 Cluster annotation 使用 <host>:<port>。

确认响应包含计划使用的以下值：

• <kube_ovn_version>
• <dns_image_tag>
• <cpi_image_tag>

当 VM template 包含 etcd 或 kube-apiserver 镜像的精确镜像引用，并且 capv-load-local-images.sh 在 kubeadm 运行前导入这些镜像时，Registry 无需提供这些镜像。仅部署 Static Pod 并不足够：每当 OS template、Kubernetes 版本、imageRepository 或组件 tag 发生变化时，都要验证本地镜像。

#验证本地预加载的镜像

使用确切的候选 template 创建并启动一个临时 VM。在该 VM 中运行以下命令，以执行 kubeadm 之前使用的相同导入路径，并列出 containerd 实际可用的镜像引用：

sudo bash -euo pipefail <<'EOF'
shopt -s nullglob
image_files=(/root/images/*.tar)
if (( ${#image_files[@]} == 0 )); then
  echo "ERROR: no tar files found in /root/images" >&2
  exit 1
fi

systemctl restart containerd
for image_file in "${image_files[@]}"; do
  ctr -n k8s.io images import "${image_file}"
done
ctr -n k8s.io images list -q | sort -u
EOF

sudo grep -nE '^[[:space:]]*(sandbox_image|sandbox)[[:space:]]*=' \
  /etc/containerd/config.toml

将第一条命令的输出与所选 Kubernetes 版本和 manifest 值所需的完整引用进行比较。确认每个必需的 kubeadm 镜像都已存在，包括根据 <image_registry>/tkestack、<k8s_version> 和组件 tag 生成的精确 etcd 与 kube-apiserver 引用。将第二条命令的 sandbox 引用与导入的 pause 镜像引用进行比较；两者必须完全一致。

每当 template、Kubernetes 版本、imageRepository、etcd tag 或 containerd sandbox 设置发生变化时，都要重新执行此验证。之后销毁验证 VM；不要将其转换回源 template。

在业务 Cluster annotation 中将 cpaas.io/registry-address 设置为 <registry_address>。

#最低单数据中心参数

#数据中心和资源放置

#主 NIC 参数

#控制平面 machine config pool

#Worker machine config pool

#计算资源规格

#磁盘大小模型

VSphereMachineTemplate.spec.template.spec.diskGiB 和 VSphereMachineConfigPool.spec.configs[] 下的两个磁盘列表定义不同的磁盘。

不要将数据磁盘大小加到 diskGiB 中。例如，如果 OS 镜像具有 100 GiB 系统磁盘，并且节点还需要一个 100 GiB 持久磁盘和三个临时磁盘，请使用至少为 100 GiB 的系统磁盘值，并在 persistentDisks 和 ephemeralDisks 中声明数据磁盘。将 diskGiB 设置为合并大小，会在数据磁盘之外创建一个过大的系统磁盘。

#标准数据磁盘

每个节点角色都需要一组专用数据磁盘。下面列出的磁盘是所需的最少磁盘数。如果工作负载需要，您可以向任一列表追加其他磁盘。在第一个 Machine 占用 slot 之前，规划好磁盘、磁盘大小和挂载路径：处于 InUse 或 Released 状态的 slot 会拒绝移除持久磁盘，或更改其 sizeGiB 或 mountPath。

这种划分遵循 Huawei Cloud Stack 和 Huawei DCS provider 使用的相同模型：只有必须在 VM 替换后保留的平台状态（/var/cpaas）才使用持久磁盘，而可重建的运行时目录（/var/lib/kubelet、/var/lib/containerd、/var/lib/etcd）会随每个 VM 重新创建。

#持久磁盘字段

#临时磁盘字段

ephemeralDisks[] 镜像持久磁盘面向 guest 的字段——name、sizeGiB、mountPath、mountOptions、fsFormat、datastore 和 storagePolicy——并省略持久性字段。不存在 wipeFilesystem，因为后端 VMDK 始终会新建，并从头开始格式化；也不存在 unitNumber，因为 controller 会在克隆时分配 SCSI 单元，并在 status.ephemeralDiskStatuses[] 中报告该单元。

在一个 slot 内，两个列表中的磁盘名称和挂载路径共享同一命名空间。有关逐字段比较以及应使用哪个列表的指导，请参阅选择持久磁盘或临时磁盘。

#持久磁盘生命周期

持久磁盘归属于特定 VSphereMachineConfigPool 中的 slot，而不属于生命周期短暂的 VM。即使另一个 pool 声明了相同的主机名、IP 地址或磁盘名称，其中的 slot 仍属于不同的分配。预期的替换生命周期如下：

1. 当 Machine 使用该 slot 时，status.configStatuses[].state 为 InUse，VMDK 会附加到其 VM。
2. 当 Machine 和 VM 被删除时，slot 变为 Released。VMDK 仍可供替换使用，不会成为永久孤立的磁盘。
3. 引用同一现有 pool 的替换 Machine 可以立即重新使用 Released slot。provider 会优先选择已释放的 slot，而不是未使用的 slot，并将声明的持久 VMDK 重新附加到替换 VM。releaseDelayHours 不是重新使用前的等待时间。
4. 如果 slot 在 releaseDelayHours 到期前一直未使用，controller 可以使其重新可用，并且只有在确认 VMDK 不再附加后才回收持久 VMDK。异步进度会显示在 status.persistentDiskStatuses[].phase 中。

wipeFilesystem 控制持久磁盘附加到新 VM 后的数据处理；它不控制 slot 选择或 datastore 回收。false 保留现有文件系统内容。true 会在新 VM 首次启动期间删除已挂载的内容；它不会加快 VMDK 回收速度，也不得将其视为 datastore 容量设置。

#重新部署和拆除容量

使用不同的 metadata.name 创建新的 VSphereMachineConfigPool 会创建一组独立的 slot。这些 slot 不会重新使用早期 pool 所拥有的 VMDK。因此，使用不同 pool 名称反复拆除和重新部署，可能会暂时消耗多组完整的持久磁盘，直到所有早期 pool 完成 provider 管理的回收。

重试或拆除部署时，请遵循以下规则：

• 对于同一集群内的 Machine 替换或滚动更新，请让每个 VSphereMachineTemplate.spec.template.spec.machineConfigPoolRef.name 始终指向同一现有 pool。更改 KubeadmControlPlane.spec.machineNamingStrategy 不会在 pool 之间转移磁盘，也不是 datastore 清理控制项。
• 如果新部署有意使用新的 pool 名称，请将新 pool 的完整持久磁盘分配纳入 datastore 容量规划。不要假设相匹配的主机名或磁盘名称可以支持跨 pool 重用。
• 在容量受限的 datastore 上开始另一次部署之前，请确认早期 pool 对象已完成删除，并且其 VMDK 已被回收。pool 删除是异步的，因为 finalizer 会等待 Machine 被移除并等待持久磁盘回收完成。
• 不要移除 pool finalizer，也不要手动删除后端 VMDK 来加速拆除。如果回收没有进展，请先收集 pool 状态、Events、provider-controller 日志和 vCenter 附加状态，再将该情况视为 provider 缺陷。
• 为两个列表都规划 datastore 容量。临时 VMDK 会在其 VM 存在期间占用 datastore 空间，但会随 VM 一起删除，因此不会跨 pool 累积，也不会阻止 slot 释放。只有持久 VMDK 会在拆除后保留，并等待 provider 管理的回收。

调查已释放的 slot 或 datastore 容量告警时，请使用以下字段：

从 status.persistentDiskStatuses[] 读取每个磁盘的状态。其 phase 字段包含 Creating、Attached、Available、Reclaiming、Reclaimed 或 Error，并且每个条目还会报告 lastError、retryAfter、taskRef 以及所属 machine。status.configStatuses[].reclaimStatus 子树以及 spec.configs[].persistentDisks[].volumePath 和 .diskUUID 字段已弃用、冻结，并计划移除。现有 pool 会由 provider 自身迁移到 persistentDiskStatuses[]；请参阅升级 Provider。

检查 pool 和相关 Events，而无需读取凭证：

kubectl -n <namespace> get vspheremachineconfigpool <pool_name> -o yaml
kubectl -n <namespace> describe vspheremachineconfigpool <pool_name>
kubectl -n <namespace> get events \
  --field-selector involvedObject.kind=VSphereMachineConfigPool,involvedObject.name=<pool_name>

#控制平面节点（每个节点 4 个磁盘）

#Worker 节点（每个节点 3 个磁盘）

#大小参数

#vSphere CPI 参数

#创建时可选的拓扑参数

#多个数据中心和多个故障域

#第二个 NIC 参数

#最终就绪检查

开始部署前，请确认以下所有项目：

1. global 集群可访问。
2. 两个集群插件均已安装：Alauda Container Platform Cluster Bootstrap Provider 和适用于 Virtualization Platform 的 Alauda Container Platform Infrastructure Provider。
3. ClusterResourceSet=true 已启用。
4. 已收集 vCenter 服务器、用户名、密码和 thumbprint。
5. 外部 LoadBalancer 满足 Layer 4 监听器、后端、运行状况检查、所有权和可访问性要求。如果集群改用 Self-built VIP，则已满足 Self-built VIP 前提条件，并已确定 <vrid> 和 <vip_interface>。
6. Pod CIDR、Service CIDR 和 kube-ovn-join-cidr 不与现有网络重叠。
7. VM 模板在每个所需的数据中心中均可用。
8. 所需的数据存储和 vCenter 资源池路径已确认。
9. 永久平台 Registry 包含所需的 Kube-OVN、CoreDNS 和 vSphere CPI 标签。
10. VM 模板包含所选 Kubernetes 和组件版本所需的、预加载到本地的 etcd 和 kube-apiserver 镜像的准确引用。
11. cpaas.io/registry-address 的值规划为不带 scheme 的 <registry_address>，或规划为 /v2/ 路径。
12. 控制平面和 Worker 的 bootstrap manifest 均通过 kubeadm files 写入 /etc/resolv.conf。
13. 最小单数据中心拓扑的 machine config pool 值均已填写完整。
14. 基准系统磁盘和数据磁盘大小已确认，每个所需磁盘均已声明在正确的列表中（/var/cpaas 为持久磁盘；/var/lib/kubelet、/var/lib/containerd 和 /var/lib/etcd 为临时磁盘），且数据磁盘大小未计入 diskGiB。
15. 在分配数据存储容量前，已了解 releaseDelayHours、同池持久磁盘复用、新池容量分配以及由 provider 管理的拆除回收。
16. 每个所需参数均具有实际值。

#后续步骤

完成此检查清单后，继续阅读在 VMware vSphere 上创建集群。