#VMware vSphere 基础设施准备

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

#场景

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

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

#前提条件

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

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

#如何使用此检查表

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

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

#参数来源与安全收集

将参数收集分为以下三类来源。能够从 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：datacenter
• c：compute cluster
• p：resource pool
• n：network 或 distributed port group
• s：datastore
• m：VM 和 template；请确认所选对象是 template

使用 Thumbprint 中的 openssl 命令获取证书指纹，而不要打印 vCenter 凭证。

#术语

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

#machine config pool

machine config pool 是 VSphereMachineConfigPool 自定义资源。它预定义了 node 插槽。每个插槽可以包含：

• 一个 node 主机名
• 一个目标 datacenter
• 每个 NIC 的静态 IP 配置
• 持久磁盘定义

#Node slot

node slot 是 VSphereMachineConfigPool.spec.configs[] 下的一项条目。单个 slot 通常映射到一个 node，例如 cp-01 或 worker-01。slot 的 hostname 会驱动 Kubernetes node 名称、kubelet serving certificate DNS SAN，以及（结合解析后的主 NIC 地址）kubelet node-ip；它必须是有效的 DNS-1123 subdomain。

#Slot network layout

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

• network.primary 是必需的。其 networkName 必须设置，并作为 kubelet 的 node-ip 来源。
• network.additional 是一个可选列表，表示在主 NIC 之后按列出的顺序合并的额外 NIC。

VSphereMachineConfigPool.spec.configs[].network 中的 dns 值描述了每个 slot 的静态网络元数据。在受影响的 VMware 部署中，这些值可能无法可靠地更新 guest operating system 的 /etc/resolv.conf。因此，部署 manifest 还会通过 KubeadmControlPlane.spec.kubeadmConfigSpec.files 和 KubeadmConfigTemplate.spec.template.spec.files 两处写入 /etc/resolv.conf。

#deviceName

deviceName 是 VSphereMachineConfigPool 网络配置中的可选字段。它用于控制 guest operating system 中看到的 NIC 名称，例如 eth0 或 eth1。

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

• networkName 是 vCenter network 或 port group 名称。
• deviceName 是 guest operating system 内部的 NIC 名称。
• 如果省略 deviceName，CAPV 通常会按 NIC 顺序分配名称，例如 eth0、eth1 和 eth2。

#vCenter resource pool

vCenter resource pool 是原生 vCenter 清单对象，例如：

/Datacenter1/host/cluster1/Resources

当启用 failure-domain 创建变体时，此路径会被 VSphereDeploymentZone.spec.placementConstraint.resourcePool 使用。

#Compute cluster

compute cluster 是目标 vCenter compute-cluster 名称。在这些文档中，它主要用于将 VSphereFailureDomain 映射到特定的部署目标。

#Datastore

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

#VM template

VM template 是用于创建 node 虚拟机的源模板。当你启用多个 datacenter 时，同一个 template 必须已经存在于每个目标 datacenter 中，并且可以通过相同的 template 名称解析。

#Thumbprint

thumbprint 是 vCenter server certificate 的 SHA-1 指纹。CAPV 使用它来验证目标 vCenter server。

使用以下命令获取它：

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 template 要求

模板还应满足以下要求：

• 使用平台镜像策略支持的操作系统。
• 包含 cloud-init。
• 包含 VMware Tools 或 open-vm-tools。
• 包含 containerd。
• 包含 kubeadm bootstrap 所需的基础组件。
• 在 /root/images/ 下包含预导出的 container image tar 文件。这些文件会在 kubeadm 运行前由 capv-load-local-images.sh 导入到 containerd 中，因此节点引导不依赖从远程 Registry 拉取镜像。
• tar 文件应包含 OS template 提供的 kubeadm control-plane 镜像，包括 etcd 和 kube-apiserver，且其镜像引用必须严格与 clusterConfiguration.imageRepository、Kubernetes 版本以及组件镜像 tag 生成的结果一致。尽管 etcd 和 kube-apiserver 以 static Pod 形式运行，但它们仍然需要 container image。缺失或不匹配的本地引用会导致 runtime 转而尝试访问已配置的 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 环境中失败。

#负载均衡器前提条件

VMware vSphere Provider v1.0.16 使用外部 LoadBalancer。该 provider 不会部署自建 VIP 组件。请在创建集群之前准备好 endpoint，并遵循 Plan the Control Plane Endpoint。

#集群基础参数

#Registry tag 验证

首先从 global 集群中读取永久 Registry 地址，或者向平台 administrator 确认等效地址：

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 命令仅验证存在性，不会打印凭据信息。导出已确认的 Cluster Registry 地址，以及 CPI 和 kubeadm manifest 使用的镜像 Registry。如果两个占位符指向同一个 Registry，请对两个变量使用相同的值。

export CLUSTER_REGISTRY_ADDRESS="<registry_address>"
export IMAGE_REGISTRY_ADDRESS="<image_registry>"
curl -sk "https://${CLUSTER_REGISTRY_ADDRESS}/v2/acp/chart-cpaas-kube-ovn/tags/list"
curl -sk "https://${IMAGE_REGISTRY_ADDRESS}/v2/tkestack/coredns/tags/list"
curl -sk "https://${IMAGE_REGISTRY_ADDRESS}/v2/ait/cloud-provider-vsphere/tags/list"

/v2/ 段仅属于这些 Registry HTTP API URL。镜像引用使用 <registry>/<repository>:<tag>，而 Cluster 注解使用 <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 发生变化时，请务必验证本地镜像。

#验证本地预加载的镜像

基于精确的候选模板创建并启动一台临时 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 注解中的 cpaas.io/registry-address 设置为 <registry_address>。

#最小单 Datacenter 参数

#Datacenter 和资源放置

#Primary NIC 参数

#控制平面 machine config pool

#Worker machine config pool

#计算规格

#磁盘大小模型

VSphereMachineTemplate.spec.template.spec.diskGiB 和 VSphereMachineConfigPool.spec.configs[].persistentDisks[] 定义的是不同磁盘。

不要将持久磁盘大小加到 diskGiB 中。例如，如果 OS image 有一个 100 GiB 的系统磁盘，而节点还需要三个 100 GiB 的持久磁盘，请使用至少 100 GiB 的系统磁盘值，并在 persistentDisks 下定义这三个 100 GiB 的数据磁盘。将 diskGiB 设置为 400 GiB 会创建一个 400 GiB 的系统磁盘，此外还会再创建这三个数据磁盘。

#标准数据磁盘

每个 node 角色都需要一组专用数据磁盘。以下列出的磁盘是最低必需磁盘。如果你的 workload 需要更多磁盘，可以将其追加到 persistentDisks 列表中。

#持久磁盘字段

#持久磁盘生命周期

持久磁盘由特定 VSphereMachineConfigPool 中的某个 slot 拥有，而不是由短生命周期的 VM 拥有。另一个 pool 中的 slot 即使声明了相同的主机名、IP 地址或磁盘名称，也属于不同的分配。对于 vSphere Provider v1.0.16，预期的替换生命周期如下：

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 不再附加后回收它们。异步进度会显示在 status.configStatuses[].reclaimStatus 中。

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

#重新部署与拆除容量

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

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

• 对于同一集群内的 Machine 替换或滚动更新，请让每个 VSphereMachineTemplate.spec.template.spec.machineConfigPoolRef.name 都指向相同的现有 pool。更改 KubeadmControlPlane.spec.machineNamingStrategy 不会在 pool 之间转移磁盘，也不是 datastore 清理控制。
• 如果新的部署有意使用新的 pool 名称，请在 datastore 容量规划中包含新 pool 的完整持久磁盘分配。不要假设相同的主机名或磁盘名可以跨 pool 复用。
• 在对容量受限的 datastore 启动另一项部署之前，请确认早期 pool 对象已完成删除，并且其 VMDK 已被回收。pool 删除是异步的，因为 finalizer 会等待 Machines 被移除并等待持久磁盘回收完成。
• 不要移除 pool finalizer，也不要手动删除后端 VMDK 以加快拆除速度。如果回收没有进展，请先收集 pool 状态、Events、provider-controller logs 和 vCenter 附加状态，再将其视为 provider 缺陷。

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

在不读取凭证的情况下检查 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>

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

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

#大小参数

#vSphere CPI 参数

#可选的创建时拓扑参数

#多个 datacenter 和多个 failure domain

#第二个 NIC 参数

#最终就绪检查

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

1. global 集群可访问。
2. 两个 cluster 插件已安装：Alauda Container Platform Kubeadm Provider 和 Alauda Container Platform VMware vSphere Infrastructure Provider。
3. 已启用 ClusterResourceSet=true。
4. 已收集 vCenter server、username、password 和 thumbprint。
5. 外部 LoadBalancer 满足第 4 层监听、后端、健康检查、责任归属和可达性要求。
6. Pod CIDR、Service CIDR 和 kube-ovn-join-cidr 与现有网络不重叠。
7. VM template 已存在于每个必需的 datacenter 中。
8. 已确认所需 datastore 和 vCenter resource pool 路径。
9. 永久平台 Registry 包含所需的 Kube-OVN、CoreDNS 和 vSphere CPI tag。
10. VM template 包含所选 Kubernetes 和 component 版本所需的精确本地预加载 etcd 和 kube-apiserver 镜像引用。
11. cpaas.io/registry-address 的值已规划为 <registry_address>，且不包含 scheme 或 /v2/ 路径。
12. 控制平面和 worker 引导 manifest 都通过 kubeadm files 写入 /etc/resolv.conf。
13. 最小单 datacenter 拓扑所需的 machine config pool 值已完整填写。
14. 已确认基础系统磁盘和数据磁盘大小，且未将持久磁盘大小加入 diskGiB。
15. 在分配 datastore 容量前，已理解 releaseDelayHours、同 pool 持久磁盘复用、新 pool 容量分配以及 provider 管理的拆除回收机制。
16. 每个必需参数都已填入实际值。

#下一步

完成此检查表后，请继续阅读 Creating Clusters on VMware vSphere。