在 VMware vSphere 上管理节点

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

前提条件

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

业务集群已成功创建。请参阅在 VMware vSphere 上创建集群。
工作机器配置池具有足够的可用槽位。
控制平面运行正常且可访问。
您知道当前用于定义工作节点的清单文件。
您知道已安装的 provider 版本。本页面中的行为已针对 VMware vSphere Provider v1.0.17 进行验证。请参阅Provider 要求。

WARNING

Day-2 apply 可能会被拒绝

发布和池规则会在 UPDATE 以及 CREATE 上强制执行，因此本页面进行的每次编辑都会检查这些规则：

重新应用已归档的 MachineDeployment 清单会重新提交整个对象。如果该文件省略了 strategy.rollingUpdate.maxSurge: 0，或者 maxUnavailable 的数量达到 1 个或更多，则应用会被拒绝——包括唯一预期更改为 replicas 的应用。请在应用之前更正该文件。strategy.type: OnDelete 不受这两条规则的限制。
如果槽位的 status.configStatuses[].state 为 InUse 或 Released，则无法将其移除，无法更改其 network.primary.ip 或 .ipv6，也无法从 persistentDisks[] 或 ephemeralDisks[] 中移除磁盘，或更改其中一个磁盘的 sizeGiB、mountPath 或已分配的 unitNumber。添加槽位，或向现有槽位的任一列表添加磁盘，均会被接受。

请将拒绝消息与准入拒绝进行匹配。

步骤

扩展工作节点

添加更多工作节点时，请先更新工作机器配置池，然后再增加从节点数量。

工作节点扩展取决于 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
  ephemeralDisks:
  - name: var-lib-kubelet
    sizeGiB: <worker_var_lib_kubelet_size_gib>
    mountPath: /var/lib/kubelet
    fsFormat: ext4
  - name: var-lib-containerd
    sizeGiB: <worker_var_lib_containerd_size_gib>
    mountPath: /var/lib/containerd
    fsFormat: ext4

此示例使用在 provider v1.0.17 上创建的集群的磁盘布局。在较早 provider 上创建的池没有 ephemeralDisks[]，并在 persistentDisks[] 中声明 /var/cpaas、/var/lib/containerd 和 /var/lib/etcd；请匹配该池已有的槽位，而不要将 ephemeralDisks[] 引入其中。

若要附加其他原始磁盘而不进行格式化或挂载，请省略 mountPath 和 fsFormat：

  persistentDisks:
  # ...standard persistent disks...
  - name: app-data
    sizeGiB: 50

原始磁盘可在来宾 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

第二条命令会替换整个 MachineDeployment 规范，而不仅仅是 replicas。应用之前，请确认归档文件包含 strategy.rollingUpdate.maxSurge: 0，且 maxUnavailable 为 1 或更大值，否则扩展操作会被拒绝。

注意：当扩展或替换必须保留逻辑池时，请保留现有的 VSphereMachineConfigPool.metadata.name。不同名称的池对象之间不会复用槽位和 VMDK。releaseDelayHours 是未使用的 Released 槽位的回收宽限期，而不是同一池重新使用前的延迟时间。

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

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

WARNING

模板不可变

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

常见更改包括：

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

持久化磁盘由 VSphereMachineConfigPool 槽位而非 VSphereMachineTemplate 所有，因此请在开始替换之前更新池槽位。此更改只能添加：您即将在其上替换节点的槽位为 InUse 或 Released，可以接受新磁盘，但会拒绝移除磁盘，或更改现有磁盘的 sizeGiB、mountPath 或已分配的 unitNumber。因此，现有磁盘需要使用不同布局时，必须创建新槽位，而不能编辑当前槽位。请参阅已分配的槽位不可变。

导出现有模板

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>"
          }
        }
      }
    }
  }'

如果还需要更改引导设置，请参阅下面的更新引导模板。

监控滚动更新

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。

更新引导模板

KubeadmConfigTemplate 资源同样不可变。更改现有模板不会触发现有机器的滚动更新。要更新引导配置，请创建新模板并更新 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）
- 更新所需的引导配置字段
- 对于 Kubernetes 1.35 或更高版本，将必需的 kubelet 修补设置添加到 /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 控制器会触发滚动更新。在替换之前，现有机器会继续使用旧的引导配置。

INFO

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

运行时拓扑更改

网络、放置和磁盘拓扑属于机器模板和机器配置池的一部分。应将这些字段的更改视为不可变滚动更新，而不是对 VM 进行就地编辑：

在增加副本数或开始替换之前，将所需的槽定义添加到现有的 VSphereMachineConfigPool。已分配的槽仅接受添加操作；请参阅先决条件中的准入警告。
当不可变的 VM、网络、放置或系统磁盘字段发生更改时，创建新的 VSphereMachineTemplate。
当引导文件或节点配置发生更改时，创建新的 KubeadmConfigTemplate。
仅在新的池容量和模板就绪后，更新 MachineDeployment 引用。
监控替换的 Machine，并确认每个节点都变为 Ready 后，再移除旧模板。

有关确切的第二个 NIC、故障域和持久磁盘字段，请使用在 VMware vSphere 上创建集群中的创建时变体。在 Day-2 更改期间，保持相同的跨资源关系：

NIC 拓扑发生更改时，保持 VSphereMachineConfigPool.spec.configs[].network.additional、VSphereMachineTemplate.spec.template.spec.network.devices 和 VSphereFailureDomain.spec.topology.networks 一致。
启用故障域时，同时配置 VSphereCluster.spec.failureDomainSelector 和 CPI [Labels] 块。
不要移除必需的 var-cpaas 持久磁盘、必需的 var-lib-kubelet 和 var-lib-containerd 临时磁盘，或控制平面的 var-lib-etcd 临时磁盘。
保持新槽的磁盘列表与该池中已有槽的磁盘列表一致。ephemeralDisks[] 来自 provider v1.0.17，但在较早版本 provider 上创建的池会在 persistentDisks[] 中声明 /var/cpaas、/var/lib/containerd 和 /var/lib/etcd；不要转换这些槽，也不要在同一个池中混用布局。
只追加，绝不重塑。InUse 或 Released 槽接受在 persistentDisks[] 和 ephemeralDisks[] 中添加新条目，这些条目会在下一次 VM 重建时生效，但会拒绝移除磁盘或更改其 sizeGiB、mountPath 或 unitNumber。调整大小意味着规划新槽。
不要将 machineNamingStrategy、wipeFilesystem 或 releaseDelayHours 视为可在池之间移动磁盘或加快数据存储清理的开关。

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

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

从两个 NIC 恢复为一个 NIC 时，从这三个字段中移除对应的第二个条目。将 network.additional 保持为空或完全移除该键，并滚动更新新的 VSphereMachineTemplate；不要直接编辑现有 VM。

故障排除

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

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

后续步骤

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

#在 VMware vSphere 上管理节点

#目录

#前提条件

#步骤

#扩展工作节点

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

#验证工作节点状态

#更新引导模板

#运行时拓扑更改

#故障排除

#后续步骤