#扩展 VMware vSphere 集群部署

本文档说明如何在最小单数据中心工作流成功运行后，扩展基线 VMware vSphere 集群部署。

#场景

在以下场景中使用本文档：

• 您需要在 control plane 或 worker 节点上添加第二个 NIC。
• 您希望将节点分布到多个数据中心或部署区域。
• 您希望添加更多数据盘。
• 您希望扩展 worker 池。

#前提条件

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

• 在 global 集群中创建 VMware vSphere 集群中的基线工作流已成功完成。
• 您已在为 VMware vSphere 集群准备参数中验证了额外参数。
• 您了解部署中的网络、放置和磁盘设置分别由哪些 manifests 管理。

#添加第二个 NIC

当节点需要额外的管理、存储或服务网络时，请扩展以下资源中的 manifests：

• 02-vspheremachineconfigpool-control-plane.yaml
• 03-vspheremachineconfigpool-worker.yaml
• 20-control-plane.yaml
• 30-workers-md-0.yaml
• 如果启用了 failure domains，则还包括 04-failure-domains.yaml

每个节点槽位都在 network.primary 和 network.additional 下声明其 NIC 布局。primary NIC 用于派生 kubelet node-ip，并保持为节点的主标识；additional NIC 会按列出的顺序追加在其后。

在 machine config pools 中，为每个 control plane 节点槽位添加第二个 NIC：

network:
  primary:
    networkName: "<nic1_network_name>"
    deviceName: "<nic1_device_name>"
    ip: "<master_01_nic1_ip>/<nic1_prefix>"
    gateway: "<nic1_gateway>"
    dns:
    - "<nic1_dns_1>"
  additional:
  - networkName: "<nic2_network_name>"
    deviceName: "<nic2_device_name>"
    ip: "<master_01_nic2_ip>/<nic2_prefix>"
    gateway: "<nic2_gateway>"
    dns:
    - "<nic2_dns_1>"

对 worker 节点槽位应用相同模式：

network:
  primary:
    networkName: "<nic1_network_name>"
    deviceName: "<nic1_device_name>"
    ip: "<worker_01_nic1_ip>/<nic1_prefix>"
    gateway: "<nic1_gateway>"
    dns:
    - "<nic1_dns_1>"
  additional:
  - networkName: "<nic2_network_name>"
    deviceName: "<nic2_device_name>"
    ip: "<worker_01_nic2_ip>/<nic2_prefix>"
    gateway: "<nic2_gateway>"
    dns:
    - "<nic2_dns_1>"

在 machine templates 中添加第二个 NIC：

network:
  devices:
  - networkName: "<nic1_network_name>"
  - networkName: "<nic2_network_name>"

如果启用了 failure domains，请更新 VSphereFailureDomain.spec.topology.networks 中的网络列表：

topology:
  networks:
  - <nic1_network_name>
  - <nic2_network_name>

在定义第二个 NIC 的值时，请在 checklist 和 manifests 中准备以下占位符：

• <master_01_nic2_ip>
• <master_02_nic2_ip>
• <master_03_nic2_ip>
• <worker_01_nic2_ip>
• <worker_02_nic2_ip>，当您同时扩展 worker 池时

在单 NIC 和双 NIC 之间切换时，请应用以下规则：

#从单 NIC 扩展为双 NIC

同时更新以下所有字段：

1. VSphereMachineConfigPool.spec.configs[].network.additional（追加第二个 NIC 条目；保持 network.primary 不变）
2. VSphereMachineTemplate.spec.template.spec.network.devices
3. 在启用 failure domains 时更新 VSphereFailureDomain.spec.topology.networks

#从双 NIC 回退为单 NIC

从以下所有字段中移除第二个 NIC 块：

1. VSphereMachineConfigPool.spec.configs[].network.additional 中的第二个 NIC 条目（保留列表为空，或完全移除 additional 键）
2. VSphereMachineTemplate.spec.template.spec.network.devices 中的第二个设备条目
3. VSphereFailureDomain.spec.topology.networks 中的第二个网络名称

#启用多个数据中心和 failure domains

当需要将节点放置到不同的 vCenter 数据中心或计算集群时，请使用多个数据中心和 failure domains。

适用以下原则：

• 一个集群可以定义多个 VSphereFailureDomain 对象。
• 每个 VSphereDeploymentZone 引用一个 VSphereFailureDomain。
• control plane 使用 VSphereCluster.spec.failureDomainSelector。
• 当 worker MachineDeployment 必须定位到特定部署区域时，它使用 spec.template.spec.failureDomain。

为第一个数据中心准备以下占位符：

• <compute_cluster_1>
• <default_datastore_1>
• <resource_pool_path_1>
• <fd_name_1>
• <dz_name_1>

为第二个数据中心准备以下占位符：

• <dc_name_2>
• <fd_name_2>
• <dz_name_2>
• <compute_cluster_2>
• <default_datastore_2>
• <resource_pool_path_2>

如果您添加第三个数据中心，请继续使用相同的占位符模式：

• <dc_name_3>
• <fd_name_3>
• <dz_name_3>
• <compute_cluster_3>
• <default_datastore_3>
• <resource_pool_path_3>

在 04-failure-domains.yaml 中创建 failure-domain 对象。启用 failure domains 时，第一个数据中心也需要一个 VSphereFailureDomain 和 VSphereDeploymentZone：

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereFailureDomain
metadata:
  name: <fd_name_1>
spec:
  region:
    name: region-a
    type: Datacenter
    tagCategory: k8s-region
    autoConfigure: true
  zone:
    name: zone-1
    type: ComputeCluster
    tagCategory: k8s-zone
    autoConfigure: true
  topology:
    datacenter: <default_datacenter>
    computeCluster: <compute_cluster_1>
    datastore: <default_datastore_1>
    networks:
    - <nic1_network_name>
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereDeploymentZone
metadata:
  name: <dz_name_1>
spec:
  server: <vsphere_server>
  failureDomain: <fd_name_1>
  controlPlane: true
  placementConstraint:
    resourcePool: <resource_pool_path_1>
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereFailureDomain
metadata:
  name: <fd_name_2>
spec:
  region:
    name: region-a
    type: Datacenter
    tagCategory: k8s-region
    autoConfigure: true
  zone:
    name: zone-2
    type: ComputeCluster
    tagCategory: k8s-zone
    autoConfigure: true
  topology:
    datacenter: <dc_name_2>
    computeCluster: <compute_cluster_2>
    datastore: <default_datastore_2>
    networks:
    - <nic1_network_name>
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereDeploymentZone
metadata:
  name: <dz_name_2>
spec:
  server: <vsphere_server>
  failureDomain: <fd_name_2>
  controlPlane: true
  placementConstraint:
    resourcePool: <resource_pool_path_2>

通过在 10-cluster.yaml 中的 VSphereCluster spec 添加 failureDomainSelector，启用在可用 failure domains 之间进行 control plane 选择：

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereCluster
metadata:
  name: <cluster_name>
  namespace: <namespace>
spec:
  controlPlaneEndpoint:
    host: "<vip>"
    port: <api_server_port>
  identityRef:
    kind: Secret
    name: <credentials_secret_name>
  server: "<vsphere_server>"
  thumbprint: "<thumbprint>"
  failureDomainSelector: {}

当 worker MachineDeployment 必须固定到某个部署目标时，请设置 worker 部署区域。在 30-workers-md-0.yaml 中为 spec.template.spec 添加 failureDomain：

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: <cluster_name>-md-0
  namespace: <namespace>
spec:
  clusterName: <cluster_name>
  replicas: <worker_replicas>
  template:
    spec:
      clusterName: <cluster_name>
      failureDomain: <worker_failure_domain>
      version: "<k8s_version>"
      # ... rest of spec

对 <worker_failure_domain> 使用 VSphereDeploymentZone 名称，而不是 VSphereFailureDomain 名称。

建议： 在启用多个数据中心之前，请确认 VM template、网络和 datastore 在每个目标数据中心中都可用。

在启用多个数据中心之前，还请确认以下前提条件：

1. 该 template 已同步到每个目标数据中心。
2. 每个目标数据中心都可以解析网络名称。
3. 每个目标数据中心都可以解析 datastore 名称。
4. vSphere CPI 数据中心列表覆盖每个目标数据中心。

#添加数据盘

基线部署包含以下必需数据盘：

• Control plane 节点：var-cpaas、var-lib-containerd 和 var-lib-etcd（每个节点 3 块磁盘）。不要移除其中任何磁盘。var-lib-etcd 磁盘必须设置 wipeFilesystem: true，以便在滚动更新期间允许 kubeadm join。
• Worker 节点：var-cpaas 和 var-lib-containerd（每个节点 2 块磁盘）。不要移除其中任何磁盘。

如果节点除了必需集合之外还需要额外的数据盘，请在相应 VSphereMachineConfigPool 节点槽位中的同一个 persistentDisks 列表中追加更多条目。以下可选字段在此尤为重要：

• mountPath：如果设置，该磁盘会被格式化并挂载到指定路径。如果省略，则磁盘会作为原始设备附加，并在 /dev/disk/by-capv/<name> 处创建符号链接，从而允许外部进程在运行时对其进行管理。
• wipeFilesystem：当值为 true 时，新 VM 首次启动时会清除磁盘内容。正常重启和手动服务重启不受影响。默认值为 false。

#扩展 worker 节点

worker 扩展取决于 MachineDeployment.spec.replicas 与 worker machine config pool 中可用节点槽位 VSphereMachineConfigPool.spec.configs[] 之间的关系。

请应用以下规则：

1. 节点槽位数量可以大于 replicas。
2. 空闲槽位不会影响正在运行的集群。
3. 如果 replicas 超过可用槽位数量，CAPV 无法正确分配新的 worker 节点。

扩展 worker 时，请按以下顺序操作：

1. 在 03-vspheremachineconfigpool-worker.yaml 中添加新的 worker 节点槽位。
2. 在 30-workers-md-0.yaml 中增加 MachineDeployment.spec.replicas。

以下示例添加了一个新的 worker 槽位：

- 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

如果要附加一个不进行格式化或挂载的原始磁盘（例如由某个 application 自行管理磁盘），请省略 mountPath 和 fsFormat：

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

该磁盘在 guest OS 中可通过 /dev/disk/by-capv/app-data 访问。在滚动更新期间，同一个 VMDK 会重新附加到新的 VM，并重新创建符号链接。该磁盘不会自动格式化或挂载——由 application 负责在运行时管理它。

然后更新 worker 副本数：

replicas: <worker_replicas>

#验证

每次扩展后，请使用以下命令验证集群状态：

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

确认以下结果：

• 新的放置、NIC 或磁盘定义已反映到目标资源中。
• 新的 worker 节点进入 Ready 状态。
• 现有节点在变更后保持健康。

#后续步骤

一次只应用一种扩展。在将多项更改组合到同一个集群之前，请先验证结果。