节点管理

本文档介绍如何使用 Cluster API 的 Machine 资源管理工作节点。

前提条件

WARNING

重要前提条件

必须先部署控制平面，才能进行节点操作。请参见创建集群获取部署说明。
确保您拥有访问 DCS 平台的权限及所需的操作权限。

INFO

配置指南 在使用本文档中的配置时：

仅修改用 <> 括起来的值
将占位符替换为您环境中的具体配置
除非明确要求，否则保持其他默认配置不变

概述

工作节点通过 Cluster API 的 Machine 资源进行管理，实现节点生命周期的声明式和自动化管理。部署流程包括：

IP-Hostname 池配置 - 工作节点的网络设置
Machine 模板配置 - 虚拟机规格定义
Bootstrap 配置 - 节点初始化及加入集群设置
Machine 部署 - 节点创建与管理的编排

工作节点部署

第一步：配置 IP-Hostname 池

IP-Hostname 池定义了工作节点虚拟机的网络配置。您需要在部署前规划并配置 IP 地址、主机名、DNS 服务器及其他网络参数。

WARNING

池大小要求 池中条目数量必须不少于计划部署的工作节点数量。条目不足将导致节点无法部署。

示例：

创建一个名为 <worker-iphostname-pool-name> 的 DCSIpHostnamePool：

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DCSIpHostnamePool
metadata:
  name: <worker-iphostname-pool-name>
  namespace: cpaas-system
spec:
  pool:
  - ip: "<worker-ip-1>"
    mask: "<worker-mask>"
    gateway: "<worker-gateway>"
    dns: "<worker-dns>"
    hostname: "<worker-hostname-1>"
    machineName: "<worker-machine-name-1>"
  - ip: "<worker-ip-2>"
    mask: "<worker-mask>"
    gateway: "<worker-gateway>"
    dns: "<worker-dns>"
    hostname: "<worker-hostname-2>"
    machineName: "<worker-machine-name-2>"
  - ip: "<worker-ip-3>"
    mask: "<worker-mask>"
    gateway: "<worker-gateway>"
    dns: "<worker-dns>"
    hostname: "<worker-hostname-3>"
    machineName: "<worker-machine-name-3>"

关键参数：

参数	类型	描述	是否必填
`.spec.pool[].ip`	string	工作虚拟机的 IP 地址	是
`.spec.pool[].mask`	string	网络子网掩码	是
`.spec.pool[].gateway`	string	网关 IP 地址	是
`.spec.pool[].dns`	string	DNS 服务器 IP 地址（多个用逗号分隔）	否
`.spec.pool[].machineName`	string	DCS 平台中的虚拟机名称	否
`.spec.pool[].hostname`	string	虚拟机主机名	否

第二步：配置 Machine 模板

DCSMachineTemplate 定义了工作节点虚拟机的规格，包括 VM 模板、计算资源、存储配置和网络设置。

WARNING

必需的磁盘配置 以下磁盘挂载点为必需，请勿删除：

系统卷（systemVolume: true）
/var/lib/kubelet - Kubelet 数据目录
/var/lib/containerd - 容器运行时数据目录
/var/cpaas - 平台相关数据目录

您可以添加额外磁盘，但必须保留上述关键配置。

示例：

创建一个名为 <worker-dcs-machine-template-name> 的 DCSMachineTemplate：

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DCSMachineTemplate
metadata:
  name: <worker-dcs-machine-template-name>
  namespace: cpaas-system
spec:
  template:
    spec:
      vmTemplateName: <vm-template-name>
      location:
        type: folder
        name: <folder-name>
      resource: # 可选，未指定则使用模板默认
        type: cluster # cluster | host，可选
        name: <cluster-name> # 可选
      vmConfig:
        dvSwitchName: <dv-switch-name> # 可选
        portGroupName: <port-group-name> # 可选
        dcsMachineCpuSpec:
          quantity: <worker-cpu>
        dcsMachineMemorySpec: # MB
          quantity: <worker-memory>
        dcsMachineDiskSpec: # GB
        - quantity: 0
          datastoreClusterName: <datastore-cluster-name>
          systemVolume: true
        - quantity: 100
          datastoreClusterName: <datastore-cluster-name>
          path: /var/lib/kubelet
          format: xfs
        - quantity: 100
          datastoreClusterName: <datastore-cluster-name>
          path: /var/lib/containerd
          format: xfs
        - quantity: 100
          datastoreClusterName: <datastore-cluster-name>
          path: /var/cpaas
          format: xfs
      ipHostPoolRef:
        name: <worker-iphostname-pool-name>

关键参数：

参数	类型	描述	是否必填
`.spec.template.spec.vmTemplateName`	string	DCS 虚拟机模板名称	是
`.spec.template.spec.location`	object	虚拟机创建位置（未指定则自动选择）	否
`.spec.template.spec.location.type`	string	位置类型（当前仅支持 "folder"）	是*
`.spec.template.spec.location.name`	string	虚拟机创建文件夹名称	是*
`.spec.template.spec.resource`	object	计算资源选择（未指定则自动选择）	否
`.spec.template.spec.resource.type`	string	资源类型：`cluster` 或 `host`	是*
`.spec.template.spec.resource.name`	string	计算资源名称	是*
`.spec.template.spec.vmConfig`	object	虚拟机配置	是
`.spec.template.spec.vmConfig.dvSwitchName`	string	虚拟交换机名称（未指定则使用模板默认）	否
`.spec.template.spec.vmConfig.portGroupName`	string	端口组名称（必须属于指定交换机）	否
`.spec.template.spec.vmConfig.dcsMachineCpuSpec.quantity`	int	工作虚拟机 CPU 核数	是
`.spec.template.spec.vmConfig.dcsMachineMemorySpec.quantity`	int	内存大小（MB）	是
`.spec.template.spec.vmConfig.dcsMachineDiskSpec`	[]object	磁盘配置数组	是
`.spec.template.spec.vmConfig.dcsMachineDiskSpec[].quantity`	int	磁盘大小（GB，系统盘为 0 使用模板大小）	是
`.spec.template.spec.vmConfig.dcsMachineDiskSpec[].datastoreClusterName`	string	数据存储集群名称	是
`.spec.template.spec.vmConfig.dcsMachineDiskSpec[].systemVolume`	bool	系统盘标识（仅允许一个磁盘为 true）	否
`.spec.template.spec.vmConfig.dcsMachineDiskSpec[].path`	string	挂载路径（未指定则不挂载）	否
`.spec.template.spec.vmConfig.dcsMachineDiskSpec[].format`	string	文件系统格式（如 xfs、ext4）	否
`.spec.template.spec.ipHostPoolRef.name`	string	引用的 DCSIpHostnamePool 名称	是

*当父对象存在时必填

第三步：配置 Bootstrap 模板

KubeadmConfigTemplate 定义了工作节点的引导配置，包括用户账户、SSH 密钥、系统文件及 kubeadm 加入集群的设置。

INFO

模板优化 模板包含预先优化的安全和性能配置。仅修改需要针对您环境定制的参数。

示例：

apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: <worker-kubeadm-config-template>
  namespace: cpaas-system
spec:
  template:
    spec:
      format: ignition
      users:
      - name: boot
        sshAuthorizedKeys:
        - "<ssh-authorized-keys>"
      files:
      - path: /etc/kubernetes/patches/kubeletconfiguration0+strategic.json
        owner: "root:root"
        permissions: "0644"
        content: |
          {
            "apiVersion": "kubelet.config.k8s.io/v1beta1",
            "kind": "KubeletConfiguration",
            "protectKernelDefaults": true,
            "staticPodPath": null,
            "tlsCertFile": "/etc/kubernetes/pki/kubelet.crt",
            "tlsPrivateKeyFile": "/etc/kubernetes/pki/kubelet.key",
            "streamingConnectionIdleTimeout": "5m",
            "clientCAFile": "/etc/kubernetes/pki/ca.crt"
          }
      preKubeadmCommands:
      - while ! ip route | grep -q "default via"; do sleep 1; done; echo "NetworkManager started"
      - mkdir -p /run/cluster-api && restorecon -Rv /run/cluster-api
      - if [ -f /etc/disk-setup.sh ]; then bash /etc/disk-setup.sh; fi
      postKubeadmCommands:
      - chmod 600 /var/lib/kubelet/config.yaml
      joinConfiguration:
        patches:
          directory: /etc/kubernetes/patches
        nodeRegistration:
          kubeletExtraArgs:
            provider-id: PROVIDER_ID
            volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

第四步：配置 Machine 部署

MachineDeployment 通过引用之前配置的 DCSMachineTemplate 和 KubeadmConfigTemplate 资源，编排工作节点的创建和管理。它负责管理期望节点数并支持滚动更新。

示例：

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: <worker-machine-deployment-name>
  namespace: cpaas-system
spec:
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  clusterName: <cluster-name>
  replicas: 3
  selector:
    matchLabels: null
  template:
    spec:
      nodeDrainTimeout: 1m
      nodeDeletionTimeout: 5m
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: <worker-kubeadm-config-template-name>
          namespace: cpaas-system
      clusterName: <cluster-name>
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: DCSMachineTemplate
        name: <worker-dcs-machine-template-name>
        namespace: cpaas-system
      version: <worker-kubernetes-version>

关键参数：

参数	类型	描述	是否必填
`.spec.clusterName`	string	节点部署的目标集群名称	是
`.spec.replicas`	int	工作节点数量（不得超过 IP 池大小）	是
`.spec.template.spec.bootstrap.configRef`	object	引用的 KubeadmConfigTemplate	是
`.spec.template.spec.infrastructureRef`	object	引用的 DCSMachineTemplate	是
`.spec.template.spec.version`	string	Kubernetes 版本（必须与 VM 模板匹配）	是
`.spec.strategy.rollingUpdate.maxSurge`	int	更新时允许超出期望节点数的最大数量	否
`.spec.strategy.rollingUpdate.maxUnavailable`	int	更新时允许不可用节点的最大数量	否

节点管理操作

本节介绍常见的工作节点管理操作，包括更新、升级及模板修改。

INFO

Cluster API 框架 节点管理操作基于 Cluster API 框架。详细信息请参阅官方 Cluster API 文档。

升级机器基础设施

升级工作节点机器规格（CPU、内存、磁盘、VM 模板）步骤如下：

创建新的 Machine 模板
- 复制当前 MachineDeployment 引用的 DCSMachineTemplate
- 修改所需的 CPU、内存、磁盘、VM 模板等参数
- 为新模板指定唯一名称
- 将新的 DCSMachineTemplate 应用到集群
更新 MachineDeployment
- 修改 MachineDeployment 资源
- 更新 spec.template.spec.infrastructureRef.name 字段，引用新的模板名称
- 应用变更
滚动更新
- 系统自动触发滚动更新
- 工作节点将逐步替换为新规格
- 通过 MachineDeployment 状态监控更新进度

更新 Bootstrap 模板

Bootstrap 模板（KubeadmConfigTemplate）由 MachineDeployment 和 MachineSet 资源使用。修改现有模板不会自动触发现有机器的滚动更新，只有新创建的机器会使用更新后的模板。

更新流程：

导出现有模板

kubectl get KubeadmConfigTemplate <template-name> -o yaml > new-template.yaml

修改配置
- 在导出的 YAML 中更新所需字段
- 修改 metadata.name 为新的唯一名称
- 删除多余的元数据字段（如 resourceVersion、uid、creationTimestamp 等）
创建新模板
```
kubectl apply -f new-template.yaml
```
更新 MachineDeployment
- 修改 MachineDeployment 资源
- 更新 spec.template.spec.bootstrap.configRef.name 引用新的模板名称
- 应用变更以触发滚动更新

WARNING

模板滚动更新行为 现有机器继续使用旧的 bootstrap 配置，只有新创建的机器（扩容或滚动更新时）会使用新的模板。

升级 Kubernetes 版本

Kubernetes 版本升级需要协调更新 MachineDeployment 和底层 VM 模板，确保兼容性。

升级流程：

更新 Machine 模板
- 创建新的 DCSMachineTemplate，指定支持目标 Kubernetes 版本的 vmTemplateName
- 确保 VM 模板包含正确的 Kubernetes 二进制文件和依赖
更新 MachineDeployment
- 修改 MachineDeployment 资源：
  - 更新 spec.template.spec.version 为目标 Kubernetes 版本
  - 更新 spec.template.spec.infrastructureRef.name 引用新的机器模板
  - 如需更改 bootstrap 配置，可更新 spec.template.spec.bootstrap.configRef.name
监控升级
- 系统将执行工作节点的滚动升级
- 验证新节点是否成功加入集群且 Kubernetes 版本正确
- 监控升级过程中的集群健康状态

WARNING

版本兼容性 确保 VM 模板中的 Kubernetes 版本与 MachineDeployment 中指定的版本一致。版本不匹配将导致节点加入失败。

#节点管理

#目录

#前提条件

#概述

#工作节点部署

#第一步：配置 IP-Hostname 池

#第二步：配置 Machine 模板

#第三步：配置 Bootstrap 模板

#第四步：配置 Machine 部署

#节点管理操作

#升级机器基础设施

#更新 Bootstrap 模板

#升级 Kubernetes 版本

节点管理

目录

前提条件

概述

工作节点部署

第一步：配置 IP-Hostname 池

第二步：配置 Machine 模板

第三步：配置 Bootstrap 模板

第四步：配置 Machine 部署

节点管理操作

升级机器基础设施

更新 Bootstrap 模板

升级 Kubernetes 版本