VMware vSphere 的 install-config.yaml 参数

本页面介绍 ac 从 VMware vSphere 业务集群的 install-config.yaml 中渲染的对象、provider 对这些对象实施的规则,以及可选拓扑。有关字段,请参阅编写 install-config.yaml。

渲染的清单

ac 将其应用于 <install-dir>/manifests/ 的对象写入文件,每个对象对应一个文件。所有对象都位于 cpaas-system 命名空间中。无需设置 Kubernetes 或 etcd 版本。ac 安装 VM Template 中描述的版本,并将其输出为 Pinning Kubernetes <version>, etcd <tag>。

对象名称备注
Cluster<cluster-name>
VSphereCluster<cluster-name>vCenter 服务器和指纹、凭证引用以及控制平面端点。对于 internal,其中还包含 controlPlaneLoadBalancer。
ConfigMap、Secret、ConfigMap、ClusterResourceSet<cluster-name>-vsphere-cpi-config、-vsphere-cpi-secret、-vsphere-cpi-manifests、-vsphere-cpiCPI 交付集合。
KubeadmControlPlane、VSphereMachineTemplate、VSphereMachineConfigPool<cluster-name>-control-planemaxSurge: 0,副本数为 3 个或更多。单个副本不使用 rollout 策略。加密配置是 KubeadmControlPlane 中的 kubeadm 文件。
MachineDeployment、VSphereMachineTemplate、VSphereMachineConfigPool<cluster-name>-<group>maxSurge: 0、maxUnavailable: 1。
KubeadmConfigTemplate<cluster-name>-<group>-config

每个 VM 都是链接克隆(cloneMode: linkedClone),除非模板没有快照。在这种情况下,provider 会创建完整克隆。每个 VM 都通过 trySoft 关闭电源。有关 rootDisk.sizeGiB 生效的条件,请参阅编写 install-config.yaml。

Machine Config Pools

hosts 中的每个条目都会成为组的 VSphereMachineConfigPool 中的一个槽位。对于使用默认设置的一个 worker 主机,该槽位渲染如下:

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereMachineConfigPool
metadata:
  name: <cluster-name>-worker
  namespace: cpaas-system
spec:
  clusterRef:
    apiVersion: cluster.x-k8s.io/v1beta1
    kind: Cluster
    name: <cluster-name>
  datacenter: <datacenter>
  releaseDelayHours: 24
  configs:
  - hostname: <worker-0-hostname>
    datacenter: <datacenter>
    network:
      primary:
        networkName: <portgroup-name>
        ip: <worker-0-ip>/<prefix-length>
        gateway: <worker-gateway>
        dns:
        - <dns-ip>
    persistentDisks:           # Kept when the VM is replaced
    - name: var-cpaas
      sizeGiB: 100
      mountPath: /var/cpaas
      fsFormat: xfs
      datastore: <datastore>
    ephemeralDisks:            # Recreated with the VM
    - name: var-lib-containerd
      sizeGiB: 100
      mountPath: /var/lib/containerd
      fsFormat: xfs
      datastore: <datastore>
    - name: var-lib-kubelet
      sizeGiB: 100
      mountPath: /var/lib/kubelet
      fsFormat: xfs
      datastore: <datastore>

provider 根据槽位的 hostname 和主地址派生 Kubernetes 节点名称、kubelet 服务证书名称以及 kubelet node-ip。hostname 必须是有效的 DNS-1123 子域名。绑定到同一 Cluster 的所有池中的主机名和主 IP 地址必须唯一。

已分配槽位限制

槽位的 status.configStatuses[].state 为 InUse 或 Released 后,不能执行以下操作:

  • 删除槽位。
  • 更改其 network.primary.ip 或 .ipv6。
  • 从 persistentDisks[] 中删除磁盘。
  • 更改持久磁盘的 sizeGiB 或 mountPath。

在 install-config.yaml 中,这些设置分别是主机及其持久磁盘和原始磁盘的 ip。

不要向处于 InUse 或 Released 状态的槽位添加磁盘。provider 无法将磁盘附加到正在运行的节点,并且会针对该节点报告错误。添加的持久磁盘在节点被替换之前无法再次移除。在第一个 Machine 接管槽位之前,规划好该槽位的所有磁盘。

有关扩容和运行时更改,请参阅 Manage Nodes on VMware vSphere。

Provider Requirements

ac 会渲染满足以下规则的值。之后手动编辑对象(例如在节点管理期间)时,也必须遵守这些规则。provider 会拒绝对违反规则的 KubeadmControlPlane 和池进行更改。违反规则的 MachineDeployment 会在下一次 rollout 期间停滞。

  • 当 spec.replicas 为 3 或更多时,KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge 为整数 0。如果未设置 maxSurge,则应用 Cluster API 默认值 1,provider 不接受该值。单个副本保留 Cluster API 默认值。只有一个控制平面节点的集群用于测试,无法升级。
  • MachineDeployment.spec.strategy.rollingUpdate.maxSurge 为 0,且 maxUnavailable 至少为 1。不接受未设置的值。strategy.type: OnDelete 两者都不需要。
  • VSphereMachineConfigPool.spec.configs 至少声明一个槽位,并且每个槽位都使用非空的 network.primary.networkName 声明 network。绑定到同一 Cluster 的所有池中的主机名和主 IP 地址必须唯一。
  • 一个池恰好服务一个控制器。控制平面使用一个池,每个 MachineDeployment 使用一个池。
  • provider 会拒绝对已处于 InUse 或 Released 状态的槽位进行某些更改。请参阅已分配槽位限制。
  • 仍拥有 InUse 槽位的池无法删除。

要确认 webhook 已在环境中注册,请使用验证安装中的 webhook 检查。有关拒绝消息,请参阅准入拒绝。

Provider-managed Fields

应用 KubeadmControlPlane 后,provider 会将 CoreDNS 和 kube-proxy 跳过注解设置为 "true"。在 ACP 4.5 平台上,平台管理业务集群中的 CoreDNS 和 Kube-OVN。provider 管理 kube-proxy。从 Kubernetes v1.35 开始,kube-proxy 仓库为 acp/k8s;对于更早的版本,则为 tkestack。该仓库以 Cluster 的 cpaas.io/registry-address 注解作为前缀。

WARNING

不要删除 CoreDNS 和 kube-proxy 跳过注解,也不要重新应用省略这些注解的已存储 KubeadmControlPlane 清单。否则,kubeadm 也会管理这些组件,并且它们的镜像会来回切换。

可选拓扑

编写 install-config.yaml 中的模板为每个节点使用一个数据中心和一个 NIC。要使用某个变体,请在创建集群之前将其添加到 install-config.yaml。一次添加一个变体。组合变体之前,先渲染清单并检查结果。创建集群后,按照验证可选拓扑中的说明检查结果。

自建 VIP

使用此变体可通过 Self-built VIP 而不是外部负载均衡器创建集群。首先按照控制平面端点中的说明确定模式。

在设置 type: internal 之前,满足Self-built VIP 要求,包括 VMware vSphere 规则。provider 会安装用于持有 VIP 的 Alive。Core Package 会携带 Alive,无需自行安装。如果未安装,请参阅Self-built VIP 故障排除。

controlPlaneLoadBalancer 字段

ac 会从 cluster.network.loadBalancer 写入 VSphereCluster.spec.controlPlaneLoadBalancer,且仅适用于 type: internal。对于 external,它会省略该字段,因为不设置该字段就表示使用外部 LoadBalancer。

install-config.yamlVSphereCluster.spec.controlPlaneLoadBalancer描述
type: internaltype: internal安装用于持有 VIP 的 Alive。
addresshost,以及 spec.controlPlaneEndpoint.hostSelf-built VIP,即一个 IPv4 地址。
portport,以及 spec.controlPlaneEndpoint.port通常为 6443。
vridvridKeepalived virtual_router_id,范围为 1-255。在控制平面 Layer 2 域中必须唯一。
interfaceinterface承载 VIP 的主机接口,最多 15 个字符。如果为空,provider 将使用承载节点主 IP 的接口。
controlPlaneLoadBalancer is write-once

provider 仅在创建集群时接受 spec.controlPlaneLoadBalancer。此后:

  • type、host、port、vrid 和 interface 均会被冻结。
  • 不能清除该字段。
  • 不能将该字段添加到创建时未包含该字段的集群。

要纠正错误,必须重建集群。对于多 NIC 节点,请显式设置 interface,因为之后无法修正错误自动检测到的接口。

provider 会设置 ipvs.strictARP: true,并将 <vip>/32 添加到业务集群的 kube-system/kube-proxy 配置中的 ipvs.excludeCIDRs。不要手动还原这些值,因为 provider 会重新应用它们,并再次滚动更新 kube-proxy DaemonSet。

要检查 VIP,请参阅验证 Self-built VIP。

添加第二个 NIC

在每个节点组的 network.additions 中声明 NIC。在 additionalIps 中,按相同顺序为每台主机的每个附加 NIC 提供一个地址:

controlPlane:
  network:
    gateway: <cp-gateway>
    dns: [<dns-ip>]
    mask: <prefix-length>
    additions:
      - mask: <nic2-prefix-length>      # Optional: empty takes network.mask
        vsphere:
          name: <nic2-portgroup-name>   # Optional: empty takes provider.vsphere.network.name
          deviceName: eth1              # Optional
  hosts:
    - hostname: <cp-0-hostname>
      ip: <cp-0-ip>
      additionalIps: [<cp-0-nic2-ip>]

主 NIC 为节点提供其身份。provider 根据该 NIC 派生 kubelet node-ip。附加 NIC 按列出的顺序跟随主 NIC。附加 NIC 具有地址、前缀和节点的 DNS 服务器,但没有网关。

添加数据磁盘

每个节点组都声明标准磁盘,且这些磁盘均为必需磁盘:

  • 控制平面节点(每个节点 4 个磁盘):var-cpaas 位于 persistent 中,此外还有 var-lib-containerd、var-lib-kubelet 和 var-lib-etcd 位于 ephemeral 中。
  • Worker 节点(每个节点 3 个磁盘):var-cpaas 位于 persistent 中,此外还有 var-lib-containerd 和 var-lib-kubelet 位于 ephemeral 中。

ac 会将这些磁盘格式化为 xfs,并挂载到标准路径。

如需更多存储,请添加 rawDisks。每个原始磁盘都会成为没有挂载路径和文件系统的持久磁盘。它会连接到 /dev/disk/by-capv/<name>,供 TopoLVM 或其他使用者使用,如以下示例所示:

disks:
  rawDisks:
    - name: data-001
      sizeGiB: 50
  vsphere:                             # Optional: where the data disks go
    datastore: <data-datastore>        # Default: the group's datastore
    storagePolicy: <storage-policy>

滚动更新时,同一 VMDK 会重新连接到新的 VM,并重新创建符号链接。磁盘不会被自动格式化或挂载。

选择持久磁盘或临时磁盘

ac 会将每个标准磁盘放入其所属的列表,并将每个原始磁盘放入 persistentDisks[]。在一个槽位内,两个列表中的磁盘名称必须各不相同,挂载路径也必须各不相同。两个列表的行为如下:

persistentDisks[]ephemeralDisks[]
删除 VM 时分离并保留,然后在同一槽位重新连接到替代 VM随 VM 一起删除
重新创建 VM 时相同的 VMDK 和相同的内容始终创建新的空磁盘,并从头开始格式化
是否参与回收和槽位释放是。磁盘仍处于连接状态时,会阻止槽位释放和池回收否
观测状态status.persistentDiskStatuses[],包含路径、UUID、单元、阶段和所属机器status.ephemeralDiskStatuses[],仅包含主机名、名称和单元
SCSI 单元首次克隆时由控制器分配,并在重新创建 VM 时复用每次克隆时由控制器分配
Guest 寻址/dev/disk/by-capv/<name>,先通过 VMDK diskUUID 定位,再通过 SCSI 单元定位/dev/disk/by-capv/<name>,仅通过 SCSI 单元定位

/var/cpaas 在 VM 替换后仍然保留。每个新 VM 都会重新创建 /var/lib/kubelet、/var/lib/containerd 和 /var/lib/etcd。

持久磁盘生命周期

持久磁盘属于某个特定 VSphereMachineConfigPool 中的槽位,而不属于生命周期较短的 VM。另一个池中的槽位属于不同的分配,即使它声明了相同的主机名、IP 地址或磁盘名称。生命周期如下:

  1. Machine 使用该槽位期间,status.configStatuses[].state 为 InUse,且 VMDK 已连接到其 VM。
  2. 删除 Machine 和 VM 后,槽位变为 Released。VMDK 仍可供替代对象使用。
  3. 同一池中的替代 Machine 会立即复用 Released 槽位。provider 优先使用已释放的槽位,而不是未使用的槽位,并重新连接其持久 VMDK。releaseDelayHours 不会延迟复用。
  4. 如果在 releaseDelayHours 到期前没有 Machine 占用该槽位,provider 会再次将该槽位设为可用。确认 VMDK 已分离后,provider 会回收该槽位的持久 VMDK。回收进度会显示在 status.persistentDiskStatuses[].phase 中。

新池不会复用早期池的 VMDK,即使新池名称相同。销毁集群并重新创建集群时,请执行以下操作之一:

  • 规划足够的数据存储容量,以容纳两组持久磁盘,直到早期池完成回收。
  • 使用 --reclaim-disks 销毁集群。请参阅删除集群。

池删除是异步的。finalizer 会等待 Machine 删除以及持久磁盘回收完成。不要移除 finalizer,也不要手动删除后端 VMDK 来加快过程。临时 VMDK 会随 VM 一起删除,因此不会在多个池之间累积。

从 status.persistentDiskStatuses[] 读取每个磁盘的状态。其 phase 为 Creating、Attached、Available、Reclaiming、Reclaimed 或 Error 之一。每个条目还会报告 lastError、retryAfter、taskRef 和所属机器。status.configStatuses[].lastReleasedTime 记录槽位进入 Released 的时间。

ac config use-cluster global
ac -n cpaas-system get vspheremachineconfigpool <pool-name> -o yaml
ac -n cpaas-system get events \
  --field-selector involvedObject.kind=VSphereMachineConfigPool,involvedObject.name=<pool-name>
WARNING

当槽位处于 Released 状态,或其 phase 为 Reclaiming 或 Error 时,不要手动删除 VMDK。替代 Machine 可能仍会复用该 VMDK,或者 provider 可能正在重试回收。

Pod 日志目录

当槽位中的磁盘挂载到 /var/lib/containerd 时,guest 中的磁盘协调脚本会将 /var/log/pods 指向该磁盘上的一个目录。之后,Pod 日志会写入该数据磁盘,而不是根文件系统。在标准布局中,该磁盘为临时磁盘,因此迁移后的 Pod 日志会随其所属的 VM 一起销毁。需要保留的日志请发送到平台日志存储。

NOTE

此迁移配置仅在首次启动前写入 guest。现有节点只有在替换节点时才会获得该配置。要替换 Worker 节点,请按照推出更新后的 Worker 节点配置中的说明操作。对于控制平面节点,请对 KubeadmControlPlane 执行相同步骤。