管理 VMware vSphere 上的节点

本文档说明在基础集群运行后，如何管理 VMware vSphere 上的工作节点。节点生命周期操作通过 VSphereMachineConfigPool、VSphereMachineTemplate、KubeadmConfigTemplate 和 MachineDeployment 资源进行管理。

前提条件

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

业务集群已成功创建。请参阅在 VMware vSphere 上创建集群。
工作节点 machine config pool 有足够的可用槽位。
控制平面运行正常且可访问。
你知道当前定义工作节点的清单文件。

步骤

扩容工作节点

当你添加更多工作节点时，请先更新工作节点 machine config pool，然后再增加 replica 数。

工作节点扩容取决于 MachineDeployment.spec.replicas 与 VSphereMachineConfigPool.spec.configs[] 中可用节点槽位之间的关系。槽位数可以大于 replicas，空闲槽位不会影响正在运行的集群。如果 replicas 超过可用槽位数，CAPV 将无法正确分配新的工作节点。

向 17-vspheremachineconfigpool-worker.yaml 添加一个或多个新的节点槽位。
更新 30-workers-md-0.yaml 中的 replicas。
应用更新后的清单。

以下示例添加了一个带有所需数据磁盘的工作节点槽位：

- hostname: "<worker_node_name_2>"
  datacenter: "<worker_02_datacenter>"
  network:
    primary:
      networkName: "<nic1_network_name>"
      ip: "<worker_02_nic1_ip>/<nic1_prefix>"
      gateway: "<nic1_gateway>"
      dns:
      - "<nic1_dns_1>"
  persistentDisks:
  - name: var-cpaas
    sizeGiB: <worker_var_cpaas_size_gib>
    mountPath: /var/cpaas
    fsFormat: ext4
  - name: var-lib-containerd
    sizeGiB: <worker_var_lib_containerd_size_gib>
    mountPath: /var/lib/containerd
    fsFormat: ext4

若要附加一个额外的原始磁盘，而不进行格式化或挂载，请省略 mountPath 和 fsFormat：

  persistentDisks:
  # ...required disks...
  - name: app-data
    sizeGiB: 50

原始磁盘在 guest OS 中可通过 /dev/disk/by-capv/app-data 访问。在滚动更新期间，同一个 VMDK 会重新附加到替换的 VM 上，并重新创建符号链接。应用仍然负责磁盘内容和运行时挂载。

然后增加工作节点副本数：

replicas: <worker_replicas>

请按以下顺序执行：

kubectl apply -f 17-vspheremachineconfigpool-worker.yaml
kubectl apply -f 30-workers-md-0.yaml

注意： 当扩容或替换需要保留同一个逻辑池时，请保持现有的 VSphereMachineConfigPool.metadata.name 不变。不同名称的 pool 对象之间不会复用槽位和 VMDK。releaseDelayHours 是针对未使用的 Released 槽位的回收宽限期，而不是在同一 pool 内复用前的延迟。

发布更新后的工作节点配置

当你需要更改工作节点 VM 规格时，请创建一个新的 VSphereMachineTemplate，并更新 MachineDeployment 以引用它。这会触发滚动更新，用新配置替换工作节点。

WARNING

模板不可变

VSphereMachineTemplate 资源不能就地修改。你必须创建一个新名称的模板，并更新 MachineDeployment 中的引用。更多信息，请参阅 Cluster API 文档。

常见变更包括：

VM 模板名称（spec.template.spec.template）
CPU 或内存规格（numCPUs、memoryMiB）
系统盘大小（diskGiB）
VM 网络设备（network.devices）

持久化磁盘由 VSphereMachineConfigPool 槽位所有，而不是由 VSphereMachineTemplate 所有。当替换需要变更持久化磁盘布局时，请先更新 pool 槽位。

导出现有模板

kubectl get vspheremachinetemplate <cluster_name>-worker -n <namespace> -o yaml > new-worker-template.yaml

修改模板

编辑 new-worker-template.yaml：
- 将 metadata.name 设置为新的唯一名称（例如，<cluster_name>-worker-v2）
- 更新所需的规格字段
- 删除由服务端生成的字段：metadata.resourceVersion、metadata.uid、metadata.generation、metadata.creationTimestamp、metadata.managedFields、metadata.annotations["kubectl.kubernetes.io/last-applied-configuration"] 和 status

应用新模板

kubectl apply -f new-worker-template.yaml

更新 MachineDeployment 引用

kubectl patch machinedeployment <cluster_name>-md-0 -n <namespace> \
  --type='merge' -p='{
    "spec": {
      "template": {
        "spec": {
          "infrastructureRef": {
            "name": "<new-template-name>"
          }
        }
      }
    }
  }'

如果你还需要更改 bootstrap 设置，请参阅下方的更新 Bootstrap Templates。

监控滚动更新

kubectl -n <namespace> get machinedeployment <cluster_name>-md-0 -w
kubectl -n <namespace> get machine

TIP

回滚失败的更新

如果滚动更新失败（例如，新的 VM 无法启动），请将 MachineDeployment 引用恢复为之前的模板名称。旧模板仍然存在，Cluster API 会回滚到该模板。

验证工作节点状态

运行以下命令，验证管理集群和业务集群的状态：

kubectl -n <namespace> get machinedeployment,machine,vspheremachine,vspherevm
kubectl --kubeconfig=/tmp/<cluster_name>.kubeconfig get nodes -o wide

确认以下结果：

达到目标工作节点副本数。
每个新的工作节点都加入了集群。
节点最终变为 Ready。

更新 Bootstrap Templates

KubeadmConfigTemplate 资源同样是不可变的。对现有模板的更改不会触发现有机器的滚动更新。要更新 bootstrap 配置，请创建一个新模板并更新 MachineDeployment 引用。

导出现有模板

kubectl get kubeadmconfigtemplate <cluster_name>-worker-bootstrap -n <namespace> -o yaml > new-bootstrap-template.yaml

修改模板

编辑 new-bootstrap-template.yaml：
- 将 metadata.name 设置为新的唯一名称（例如，<cluster_name>-worker-bootstrap-v2）
- 更新所需的 bootstrap 配置字段
- 对于 Kubernetes 1.35 或更高版本，将必需的 kubelet patch 设置添加到 /etc/kubernetes/patches/kubeletconfiguration0+strategic.json
- 删除与发布更新后的工作节点配置第 2 步中列出的相同服务端生成字段

应用新模板

kubectl apply -f new-bootstrap-template.yaml

更新 MachineDeployment 引用

kubectl patch machinedeployment <cluster_name>-md-0 -n <namespace> \
  --type='merge' -p='{
    "spec": {
      "template": {
        "spec": {
          "bootstrap": {
            "configRef": {
              "name": "<new-bootstrap-template-name>"
            }
          }
        }
      }
    }
  }'

Cluster API controller 会触发滚动更新。现有机器在被替换之前会继续使用旧的 bootstrap 配置。

INFO

正在升级 Kubernetes 版本？ 请参阅在 VMware vSphere 上升级集群，了解完整的控制平面和工作节点升级流程。

运行期拓扑变更

网络、放置和磁盘拓扑都属于 machine templates 和 machine config pool 的一部分。将这些字段的变更视为不可变的滚动发布，而不是就地修改 VM：

在增加副本或开始替换之前，先在现有的 VSphereMachineConfigPool 中添加或更新所需的槽位定义。
当其不可变的 VM、网络、放置或系统盘字段发生变化时，创建一个新的 VSphereMachineTemplate。
当 bootstrap 文件或节点配置发生变化时，创建一个新的 KubeadmConfigTemplate。
仅在新的 pool 容量和模板已存在后，才更新 MachineDeployment 引用。
监控替换中的 Machines，并在删除旧模板之前确认每个节点都变为 Ready。

对于精确的第二块 NIC、failure domain 和持久化磁盘字段，请使用在 VMware vSphere 上创建集群中的创建时变体。在 Day-2 变更期间，请保留相同的跨资源关系：

当 NIC 拓扑发生变化时，保持 VSphereMachineConfigPool.spec.configs[].network.additional、VSphereMachineTemplate.spec.template.spec.network.devices 和 VSphereFailureDomain.spec.topology.networks 一致。
在启用 failure domains 时，请同时配置 VSphereCluster.spec.failureDomainSelector 和 CPI [Labels] 块。
不要删除必需的 var-cpaas、var-lib-containerd 或 control-plane var-lib-etcd 磁盘。
不要将 machineNamingStrategy、wipeFilesystem 或 releaseDelayHours 视为可将磁盘在 pool 之间迁移或加速 datastore 清理的开关。

当你从一块 NIC 扩展到两块 NIC 时，请同时更新以下所有字段：

将第二个 NIC 条目追加到 VSphereMachineConfigPool.spec.configs[].network.additional；保持 network.primary 不变。
在新的不可变模板中，将第二个设备添加到 VSphereMachineTemplate.spec.template.spec.network.devices。
在启用 failure domains 时，将第二个网络添加到 VSphereFailureDomain.spec.topology.networks。

当你从两块 NIC 回退到一块 NIC 时，请从这三个字段中删除对应的第二个条目。将 network.additional 保持为空，或者直接移除该 key，并发布一个新的 VSphereMachineTemplate；不要直接编辑现有 VM。

故障排查

当工作节点管理失败时，首先执行以下检查：

检查 MachineConfigPoolReady 的 VSphereMachine 条件。如果为 False，其原因会指示槽位分配失败的原因：
- PoolBoundToOtherConsumer：该 pool 已绑定到其他 KubeadmControlPlane 或 MachineDeployment。
- NoAvailableSlots：没有槽位匹配所需的数据中心或 failure domain。
确认工作节点 machine config pool 仍然有空闲槽位。
确认工作节点 IP 地址、网关和 DNS 设置正确。
确认工作节点 VM 模板仍然匹配所需的 Kubernetes 版本和 guest-tools 要求。
当节点正在等待分配 IP 时，检查 VSphereVM.status.addresses。

后续步骤

有关基础设施准备和持久化磁盘诊断，请参阅 VMware vSphere Infrastructure Preparation。有关集群创建清单字段，请参阅在 VMware vSphere 上创建集群。

#管理 VMware vSphere 上的节点

#目录

#前提条件

#步骤

#扩容工作节点

#发布更新后的工作节点配置

#验证工作节点状态

#更新 Bootstrap Templates

#运行期拓扑变更

#故障排查

#后续步骤