在 VMware vSphere 上管理节点

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

如需使用 YAML 添加另一个工作节点池，请参阅集群创建页面中的创建工作节点对象。

INFO

如需升级节点的 Kubernetes 版本，请参阅在 VMware vSphere 上升级 Kubernetes。

前提条件

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

业务集群已成功创建。请参阅在 VMware vSphere 上创建集群。
工作节点机器配置池有足够的可用槽位。
控制平面运行正常且可访问。
你知道当前用于定义工作节点的清单文件。
你了解Provider Requirements中的发布和池规则。
如需管理 global 集群本身的节点，必须先在 global 上安装 provider；请参阅在 Alauda OS 集群上管理节点。

WARNING

Day-2 apply 可能会被拒绝

发布和池规则适用于本页面执行的每次编辑：

重新应用归档的 MachineDeployment 清单会重新提交整个对象，包括唯一预期更改为 replicas 的应用操作。在应用之前，请确认文件设置了 strategy.rollingUpdate.maxSurge: 0；示例使用 maxUnavailable: 1。在默认的 maxSurge 为 1 时，发布操作需要一个完整池没有的额外槽位，因此会停滞。strategy.type: OnDelete 不需要 surge 设置。
KubeadmControlPlane 必须将 spec.rolloutStrategy.rollingUpdate.maxSurge: 0 和 spec.replicas 设置为 3 或更高值，否则对其进行编辑会被拒绝。请参阅根据准入规则检查清单。
status.configStatuses[].state 为 InUse 或 Released 的槽位不能移除，不能更改其 network.primary.ip 或 .ipv6，也不能从 persistentDisks[] 中移除磁盘，或更改其 sizeGiB 或 mountPath。添加槽位会被接受。请勿向此类槽位添加磁盘；请参阅已分配槽位限制。

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

步骤

扩展工作节点

添加更多工作节点时，请先更新工作节点机器配置池，再增加副本数。

工作节点扩展取决于 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。

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

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

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

常见更改包括：

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

如果要在 Kubernetes 版本保持不变的情况下将节点迁移到新的 Alauda OS 镜像，请改为按照不更改 Kubernetes 版本的 OS 镜像更新进行操作。如果 Kubernetes 版本也发生更改，请参阅在 VMware vSphere 上升级 Kubernetes。

持久磁盘在 VSphereMachineConfigPool 槽位中声明，而不是在 VSphereMachineTemplate 中声明，因此新模板不会更改这些磁盘。InUse 或 Released 槽位会拒绝更改现有磁盘的 sizeGiB 或 mountPath，因此现有磁盘需要使用不同的几何配置时，应创建新槽位，而不是编辑当前槽位。请参阅已分配槽位限制。

导出现有模板

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

若要更改控制平面节点的机器规格，请使用相同步骤，并改为修补 KubeadmControlPlane.spec.machineTemplate.infrastructureRef.name。

TIP

回滚失败的更新

如果滚动更新失败（例如，新 VM 无法启动），请将 MachineDeployment 引用恢复为之前的模板名称。此操作仅在 Kubernetes 次要版本未发生更改时有效。旧模板仍然存在，Cluster API 将回滚到该模板。

验证工作节点状态

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

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

确认以下结果：

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

更新 Bootstrap 模板

要更新 Bootstrap 配置，请创建新的 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）
- 更新所需的 Bootstrap 配置字段
- 对于 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 控制器会触发滚动更新。在替换现有机器之前，它们会继续使用旧的 Bootstrap 配置。

运行时拓扑更改

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

在增加副本数或开始替换之前，将所需的插槽定义添加到现有的 VSphereMachineConfigPool。已分配的插槽会拒绝某些更改；请参阅前提条件中的警告。
当 VM、网络、放置或系统磁盘字段发生更改时，创建新的 VSphereMachineTemplate。
当 Bootstrap 文件或节点配置发生更改时，创建新的 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 状态的插槽会拒绝移除持久磁盘，或更改其 sizeGiB 或 mountPath。调整大小意味着规划新的插槽。
不要将 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：没有插槽符合所需的数据中心或故障域。
确认业务节点机器配置池仍有可用插槽。
确认业务节点 IP 地址、网关和 DNS 设置正确。
确认业务节点 VM 模板仍符合所需的 Kubernetes 版本和客户机工具要求。
当节点等待分配 IP 时，检查 VSphereVM.status.addresses。

后续步骤

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

#在 VMware vSphere 上管理节点

#目录

#前提条件

#步骤

#扩展工作节点

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

#验证工作节点状态

#更新 Bootstrap 模板

#运行时拓扑更改

#故障排查

#后续步骤