#节点管理

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

#前提条件

#概述

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

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

#工作节点部署

#步骤 1：配置 IP-Hostname 池

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

示例：

创建名为 <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>"

关键参数：

#步骤 2：配置 Machine 模板

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

示例：

创建名为 <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>

关键参数：

* 当父对象存在时必填

#步骤 3：配置 Bootstrap 模板

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

示例：

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/"

#步骤 4：配置 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>

关键参数：

#节点管理操作

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

#扩容工作节点

工作节点扩容允许根据负载需求调整集群容量。Cluster API 通过 MachineDeployment 资源自动管理节点生命周期。

#添加工作节点

增加工作节点数量以应对更高负载或新增容量。

使用场景：扩容集群以增加计算资源

前提条件：

• 确认 IP 池有足够的可用 IP 地址供新增节点使用
• 确保 DCS 平台有足够资源创建新的虚拟机

操作步骤：

1. 查看当前节点状态

   查看集群中现有机器：

   # 列出集群所有机器
   kubectl get machines -n cpaas-system
   
   # 列出指定 MachineDeployment 的机器
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/deployment-name=<worker-machine-deployment-name>

2. 扩展 IP 池

   扩容前需向池中添加新节点的 IP 配置。

   INFO

   IP 池扩容说明 IP 池条目数必须不少于期望的副本数。请为每个新增工作节点添加对应 IP 条目。

   向池中添加 IP 条目：

   首先导出现有池配置，保留已有条目：

   kubectl get dcsiphostnamepool <worker-iphostname-pool-name> -n cpaas-system -o yaml

   然后使用以下命令添加新 IP 配置。pool 数组必须包含所有现有条目及新增条目：

   kubectl patch dcsiphostnamepool <worker-iphostname-pool-name> -n cpaas-system \
     --type='merge' -p='
   {
     "spec": {
       "pool": [
         {
           "ip": "<existing-ip-1>",
           "mask": "<worker-mask>",
           "gateway": "<worker-gateway>",
           "dns": "<worker-dns>",
           "hostname": "<existing-hostname-1>",
           "machineName": "<existing-machine-name-1>"
         },
         {
           "ip": "<existing-ip-2>",
           "mask": "<worker-mask>",
           "gateway": "<worker-gateway>",
           "dns": "<worker-dns>",
           "hostname": "<existing-hostname-2>",
           "machineName": "<existing-machine-name-2>"
         },
         {
           "ip": "<new-worker-ip-1>",
           "mask": "<worker-mask>",
           "gateway": "<worker-gateway>",
           "dns": "<worker-dns>",
           "hostname": "<new-worker-hostname-1>",
           "machineName": "<new-worker-machine-name-1>"
         },
         {
           "ip": "<new-worker-ip-2>",
           "mask": "<worker-mask>",
           "gateway": "<worker-gateway>",
           "dns": "<worker-dns>",
           "hostname": "<new-worker-hostname-2>",
           "machineName": "<new-worker-machine-name-2>"
         }
       ]
     }'
   WARNING

   重要说明

   • pool 数组必须包含所有现有条目及新增条目
   • 请从导出的 YAML 中复制现有条目，避免数据丢失
   • 确保每个新增条目的 ip、hostname 和 machineName 唯一
   • 网络参数（mask、gateway、dns）一般与现有条目保持一致

   示例：为已有 3 个节点的池添加 2 个新节点

   # 当前池含 3 条目（10.0.1.11、10.0.1.12、10.0.1.13）
   # 添加第 4、5 个节点条目
   kubectl patch dcsiphostnamepool worker-pool-1-ippool -n cpaas-system \
     --type='merge' -p='
   {
     "spec": {
       "pool": [
         {
           "ip": "10.0.1.11",
           "mask": "255.255.255.0",
           "gateway": "10.0.1.1",
           "dns": "10.0.0.2",
           "hostname": "worker-node-1",
           "machineName": "worker-vm-1"
         },
         {
           "ip": "10.0.1.12",
           "mask": "255.255.255.0",
           "gateway": "10.0.1.1",
           "dns": "10.0.0.2",
           "hostname": "worker-node-2",
           "machineName": "worker-vm-2"
         },
         {
           "ip": "10.0.1.13",
           "mask": "255.255.255.0",
           "gateway": "10.0.1.1",
           "dns": "10.0.0.2",
           "hostname": "worker-node-3",
           "machineName": "worker-vm-3"
         },
         {
           "ip": "10.0.1.14",
           "mask": "255.255.255.0",
           "gateway": "10.0.1.1",
           "dns": "10.0.0.2",
           "hostname": "worker-node-4",
           "machineName": "worker-vm-4"
         },
         {
           "ip": "10.0.1.15",
           "mask": "255.255.255.0",
           "gateway": "10.0.1.1",
           "dns": "10.0.0.2",
           "hostname": "worker-node-5",
           "machineName": "worker-vm-5"
         }
       ]
     }'

3. 验证 IP 池容量

   扩展 IP 池后，确认池中条目数量满足期望副本数：

   kubectl get dcsiphostnamepool -n cpaas-system <worker-iphostname-pool-name> -o yaml

   确认池中条目不少于期望副本数。

4. 扩容 MachineDeployment

   修改 replicas 字段为期望节点数：

   kubectl patch machinedeployment <worker-machine-deployment-name> -n cpaas-system \
     --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": <new-replica-count>}]'

   示例：从 3 扩容到 5 个节点

   kubectl patch machinedeployment worker-pool-1 -n cpaas-system \
     --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": 5}]'

5. 监控扩容进度

   观察机器创建过程：

   # 监视机器创建
   kubectl get machines -n cpaas-system -w
   
   # 查看 MachineDeployment 状态
   kubectl get machinedeployment <worker-machine-deployment-name> -n cpaas-system

   Cluster API 控制器将根据 MachineDeployment 模板自动创建新机器。

6. 验证节点加入集群

   切换至目标集群上下文，确认新节点状态：

   # 切换上下文
   kubectl config use-context <target-cluster-context>
   
   # 查看所有节点状态
   kubectl get nodes

   新节点应出现在列表中并处于 Ready 状态。

#删除工作节点

减少工作节点数量以缩减集群容量或释放资源。Cluster API 支持两种删除策略：

1. 随机删除：直接减少副本数，平台随机选择并删除机器
2. 指定删除：标记特定机器删除，再减少副本数（推荐用于 IP 回收）

#随机删除

使用场景：缩容时任意节点均可删除，无特定 IP 要求

操作步骤：

1. 查看当前机器状态

   查看指定 MachineDeployment 的机器：

   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/deployment-name=<worker-machine-deployment-name>

2. 缩容 MachineDeployment

   修改 replicas 字段减少节点数：

   kubectl patch machinedeployment <worker-machine-deployment-name> -n cpaas-system \
     --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": <new-replica-count>}]'

   示例：从 5 缩容到 3 个节点

   kubectl patch machinedeployment worker-pool-1 -n cpaas-system \
     --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": 3}]'

   Cluster API 控制器将随机选择机器删除以匹配目标副本数。

3. 监控删除进度

   观察机器删除过程：

   kubectl get machines -n cpaas-system -w

   Cluster API 控制器将：

   • 驱逐选中节点上的 Pod（如可能）
   • 从 DCS 平台删除对应虚拟机
   • 删除机器资源

4. 验证节点已删除

   切换至目标集群上下文：

   kubectl config use-context <target-cluster-context>
   kubectl get nodes

   被删除节点应不再显示。

#指定删除

使用场景：删除特定机器（如 IP 回收、替换异常节点）

操作步骤：

1. 确认待删除机器

   查看当前机器：

   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/deployment-name=<worker-machine-deployment-name>

   记录需要删除的 <machine-name>。

2. 为机器添加删除注解

   标记指定机器删除：

   kubectl patch machine <machine-name> -n cpaas-system \
     --type='merge' -p='{"metadata": {"annotations": {"cluster.x-k8s.io/delete-machine": "true"}}}'

   对每个待删除机器重复此操作。

   示例：删除两个指定机器

   kubectl patch machine worker-pool-1-abc123 -n cpaas-system \
     --type='merge' -p='{"metadata": {"annotations": {"cluster.x-k8s.io/delete-machine": "true"}}}'
   
   kubectl patch machine worker-pool-1-def456 -n cpaas-system \
     --type='merge' -p='{"metadata": {"annotations": {"cluster.x-k8s.io/delete-machine": "true"}}}'

3. 缩容 MachineDeployment

   注解机器后，减少副本数：

   INFO

   副本数必须与注解机器数匹配 减少的副本数应与注解机器数量完全一致。

   • 减少不足，部分注解机器不会被删除
   • 减少过多，额外机器将被随机删除

   kubectl patch machinedeployment <worker-machine-deployment-name> -n cpaas-system \
     --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": <new-replica-count>}]'

   示例：注解了 2 台机器，则副本数减少 2（如从 5 减到 3）

   平台将删除注解的机器，而非随机机器。

4. 监控删除进度

   观察机器删除过程：

   kubectl get machines -n cpaas-system -w

5. 验证节点已删除

   切换至目标集群上下文：

   kubectl config use-context <target-cluster-context>
   kubectl get nodes

   被删除节点应不再显示。

#升级机器基础设施

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

1. 创建新 Machine 模板

   • 复制当前 MachineDeployment 引用的 DCSMachineTemplate
   • 修改所需参数（CPU、内存、磁盘、VM 模板等）
   • 赋予新模板唯一名称
   • 应用新模板到集群

2. 更新 MachineDeployment

   • 修改 MachineDeployment 资源
   • 更新 spec.template.spec.infrastructureRef.name 指向新模板
   • 应用修改

3. 滚动更新

   • 系统自动触发滚动更新
   • 工作节点将逐步替换为新规格节点
   • 通过 MachineDeployment 状态监控更新进度

#更新 Bootstrap 模板

Bootstrap 模板（KubeadmConfigTemplate）被 MachineDeployment 和 MachineSet 使用。修改现有模板不会自动触发已有机器滚动更新，仅新建机器使用新模板。

更新流程：

1. 导出现有模板

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

2. 修改配置

   • 编辑导出 YAML，更新所需字段
   • 修改 metadata.name 为新唯一名称
   • 删除多余元数据字段（如 resourceVersion、uid、creationTimestamp 等）

3. 创建新模板

   kubectl apply -f new-template.yaml

4. 更新 MachineDeployment

   • 修改 MachineDeployment 资源
   • 更新 spec.template.spec.bootstrap.configRef.name 指向新模板
   • 应用修改以触发滚动更新

#升级 Kubernetes 版本

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

升级流程：

1. 更新 Machine 模板

   • 创建新 DCSMachineTemplate，指定支持目标 Kubernetes 版本的 vmTemplateName
   • 确保 VM 模板包含正确的 Kubernetes 二进制文件及依赖

2. 更新 MachineDeployment

   • 修改 MachineDeployment 资源：
     • 更新 spec.template.spec.version 为目标 Kubernetes 版本
     • 更新 spec.template.spec.infrastructureRef.name 指向新模板
     • 如需更改引导配置，可更新 spec.template.spec.bootstrap.configRef.name

3. 监控升级

   • 系统执行工作节点滚动升级
   • 验证新节点成功加入集群且 Kubernetes 版本正确
   • 监控集群健康状态，确保升级过程顺利完成