#VMware vSphere 基础设施准备

本文帮助您准备创建 VMware vSphere 业务集群所需的基础设施并收集必要值。在应用在 VMware vSphere 上创建集群中的清单之前，请完成此检查清单。本页中的 provider 行为和字段已根据 VMware vSphere Provider v1.0.17 进行验证。

#场景

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

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

#前提条件

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

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

#如何使用此检查清单

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

1. 收集本文档中列出的部署参数。
2. 将清单模板中的每个占位符替换为此处收集的实际值。
3. 如果某个占位符出现在多个清单中，请在所有位置重复使用相同的值。
4. 如果未启用某项可选功能，请按照创建时拓扑变体中的说明，准确省略相应的 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 环境中失败。

#负载均衡器前提条件

本节介绍基线集群使用的外部 LoadBalancer 端点。请在创建集群之前完成配置，并遵循规划控制平面端点。也可以使用由 provider 管理的 Self-built VIP 创建集群；该方式无需外部 LoadBalancer，且需要 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/ait/cloud-provider-vsphere/tags/list"

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

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

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

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

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

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

#验证本地预加载的镜像

使用准确的候选模板创建并启动一个临时 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 镜像引用进行比较；两者必须完全一致。

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

在业务 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 设置为合计大小，会在数据磁盘之外额外创建一个过大的系统磁盘。

#标准数据磁盘

每个节点角色都需要一组专用数据磁盘。以下列出的磁盘是最低要求的磁盘。如果工作负载需要，您可以向任一列表追加其他磁盘。已分配的槽位仍可接受两个列表中的新条目——这些条目会在下次重新创建 VM 时生效——但绝不接受移除或调整磁盘，因此请在第一个 Machine 使用该槽位之前规划好大小和挂载路径。

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

#持久磁盘字段

#临时磁盘字段

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

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

#持久磁盘生命周期

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

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

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

#重新部署和拆除容量

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

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

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

调查已释放的槽位或数据存储容量告警时，请使用以下字段：

从 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 Kubeadm Provider 和 Alauda Container Platform VMware vSphere Infrastructure Provider。
3. 已启用 ClusterResourceSet=true。
4. 已收集 vCenter 服务器、用户名、密码和 thumbprint。
5. 外部 LoadBalancer 满足第 4 层监听器、后端、健康检查、所有权和可达性约定。如果集群改用 Self-built VIP，则已满足 Self-built VIP 前置条件，并已确定 <vrid> 和 <vip_interface>。
6. Pod CIDR、Service CIDR 和 kube-ovn-join-cidr 不与现有网络重叠。
7. VM template 在每个所需数据中心中均可用。
8. 已确认所需的数据存储和 vCenter 资源池路径。
9. 永久平台 Registry 包含所需的 Kube-OVN、CoreDNS 和 vSphere CPI 标签。
10. VM template 包含所选 Kubernetes 和组件版本所需的、在本地预加载的 etcd 和 kube-apiserver 镜像的确切引用。
11. cpaas.io/registry-address 值计划设置为不带 scheme 或 /v2/ 路径的 <registry_address>。
12. 控制平面和 worker 引导清单均通过 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 上创建集群。