#在 Huawei Cloud Stack 上管理节点

本文档说明如何在 Huawei Cloud Stack 平台上使用 Cluster API Machine 资源管理 worker 节点。

#前提条件

使用本文档中的 YAML 示例时，仅替换 <> 中的值为环境相关的值。除非集群策略要求使用不同的值，否则请保留其余字段不变。

#概述

worker 节点通过 Cluster API Machine 资源进行管理，从而提供声明式和自动化的节点生命周期管理。部署过程包括：

1. Machine Configuration Pool - worker 节点的网络设置
2. Machine Template - VM 规格
3. Bootstrap Configuration - 节点初始化设置
4. Machine Deployment - 节点创建和管理编排

您可以通过 Web UI 或 YAML manifest 管理这些资源。Web UI 提供引导式体验，并且在满足以下版本要求时可用；YAML 适用于所有受支持的提供程序版本。

#使用 Web UI

版本要求：此工作流需要 Fleet Essentials 1.0.2 或更高版本，以及 Alauda Container Platform HCS Infrastructure Provider v1.0.3 或更高版本。在更早的提供程序版本中，请使用 Using YAML 部分中的 YAML 工作流管理 node pool。

Node Pools 选项卡允许您查看控制平面和 worker node pool，添加或删除 worker node pool，以及编辑现有 pool 的保留 IP 地址。

#查看 Node Pools

Node Pools 选项卡会将 Control Plane Node Pool 和每个 Worker Node Pool 以卡片形式展示。两种卡片类型共享相同字段：

#添加 Worker Node Pool

单击 Add Worker Node Pool 并完成对话框。各字段与 创建向导 的第 5 步一致：pool 名称（以 <cluster-name>- 为前缀）、Flavor、Availability Zone、Machine Configs（hostname、networks、persistent disks）、System Disk、Data Volumes、Replicas、Rollout Strategy 以及 SSH Authorized Keys。创建 pool 后，新节点会显示在 Nodes 选项卡中。

#管理节点 IP 地址

HCS pool 中的每个节点都使用其子网中的一个保留静态 IP 地址。若要更改 pool 保留的地址，例如在扩容前预留容量，请打开 pool 卡片的操作菜单并选择 Update Config Pool，以打开 Manage IPs 对话框。

该对话框用于编辑 pool 的 HCSMachineConfigPool 中的 machine 配置。对于每个节点，您可以设置 hostname、networks（每个网络包含从其子网中选择的一个 IP 地址以及子网本身）和 persistent disks。IP 选择规则与创建向导相同：先选择子网，再从列表中选择一个可分配地址；已被占用的地址不会显示。

#删除 Worker Node Pool

打开 Worker Node Pool 卡片的操作菜单，选择 Delete，然后确认。

#使用 YAML

使用 Cluster API manifest 管理 worker 节点。此工作流适用于所有受支持的提供程序版本。

#部署 Worker 节点

在准备 worker YAML 之前，请先完成 Huawei Cloud Stack 的基础设施资源 中的 HCS 输入检查清单。特别是，在 HCSCluster.spec.network.subnets 中列出所有 worker 子网，从规划好的空闲 IP 范围中分配 worker IP，并收集提供程序可识别的 flavorName 和 availabilityZone API 值。如果您要向现有 Ready 集群添加新的 worker 子网，请使用完整的子网对象补丁更新 HCSCluster.spec.network.subnets，而不是仅添加子网名称。

#步骤 1：配置 Machine Configuration Pool

HCSMachineConfigPool 定义了 worker 节点 VM 的网络配置以及由 pool 管理的持久磁盘。在部署之前，必须规划并配置 IP 地址、hostname、persistent disk 插槽以及其他参数。

为每个 networks[] 条目使用一个子网选择器。对于新 manifest，请仅设置 subnetName 或 subnetId 之一，不要同时设置两者。现有 manifest 可以保留已弃用的 subenetName 字段；如果您在更新该 manifest 时同时添加 subnetName，其值必须与 subenetName 完全一致。不要在 subenetName、subnetName 和 subnetId 之间提供冲突值。

如果您在 worker 节点中使用 subnetName，请在创建或扩容 worker pool 之前，将相同的子网名称包含在父级 HCSCluster.spec.network.subnets 列表中。对于现有的 Ready 集群，请追加完整的子网对象（包括子网 ID），而不是仅添加子网名称。

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineConfigPool
metadata:
  name: <cluster-name>-worker-pool
  namespace: cpaas-system
  labels:
    cluster.x-k8s.io/cluster-name: <cluster-name>
spec:
  configs:
    - hostname: <worker-1-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-1-ip>
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs
    - hostname: <worker-2-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-2-ip>
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs
    - hostname: <worker-3-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-3-ip>
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs

*对于新 manifest，请设置 subnetName 或 subnetId 之一。现有 manifest 可以继续使用 subenetName，并且仅当两个字段使用相同值时才可以添加 subnetName。不要提供冲突的子网选择器值。

当指定 persistentDisks 时，persistent disk 字段为必填。

对于必须在 worker 替换后仍然保留的节点本地状态，请使用 persistentDisks[]。不要在 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中声明相同的挂载路径。

注意： CRD schema 将 subnetName、subenetName 和 subnetId 列为可选字段，但未表达它们允许的组合。编写 manifest 时，请遵循上述提供程序级别规则。

注意： 当 worker 节点需要多个 NIC 时，networks[] 可以包含多个条目。当前提供程序仅使用每个条目为一个带有子网选择器和静态 IP 的 NIC 执行挂载。它不支持按 NIC 声明角色、选择默认网关、静态路由、路由度量，或按 NIC 配置 DNS 设置。

#Worker 的 Pool 管理持久磁盘

将必须在替换后仍保留的 worker 节点磁盘声明在匹配的 HCSMachineConfigPool.spec.configs[].persistentDisks[] 条目中。对于 /var/cpaas 以及在滚动替换期间必须保留的任何其他节点本地状态，请使用此模型。

• 将 HCSMachineTemplate.spec.template.spec.dataVolumes[] 保留给可能随每个 ECS 重新创建的临时磁盘。
• 对于每个 hostname，保持插槽从 0 开始唯一且连续。提供程序使用 (hostname, slot) 作为 persistent disk 标识。
• 在提供程序接受该条目后，将 slot、size、type、format 和 mountPath 视为不可变字段。
• 您可以更新 mountOptions。该更改会在 worker 被替换后生效。
• 您可以追加新的 persistentDisks[] 条目。提供程序会创建或认领 EVS 磁盘，但不会将该磁盘热挂载到正在运行的 ECS 中。在期望新磁盘在客户机操作系统中完成格式化和挂载之前，请通过设置 MachineDeployment.spec.strategy.rollingUpdate.maxSurge: 0 触发滚动替换。

要在 worker 操作期间检查 persistent disk 的运行时状态，请查看 pool 状态：

kubectl get hcsmachineconfigpool <cluster-name>-worker-pool -n cpaas-system -o yaml

#步骤 2：配置 Machine Template

HCSMachineTemplate 定义了 worker 节点的 VM 规格。

为 worker 节点配置系统盘和临时数据盘，用于可能在每个 ECS 中重新创建的路径，例如 /var/lib/kubelet 和 /var/lib/containerd。当平台状态必须在 worker 替换后仍然保留时，请将 /var/cpaas 放入 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中。

在准备 worker template 时，请使用提供程序可识别的 flavorName 和 availabilityZone API 值。这些值不是租户 UI 中显示的名称。

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineTemplate
metadata:
  name: <cluster-name>-worker-template
  namespace: cpaas-system
spec:
  template:
    spec:
      imageName: <vm-image-name>
      flavorName: <instance-flavor>
      availabilityZone: <availability-zone>
      rootVolume:
        type: SSD
        size: 100
      configPoolRef:
        name: <cluster-name>-worker-pool
      dataVolumes:
        - size: 20
          type: SSD
          mountPath: /var/lib/kubelet
          format: xfs
        - size: 20
          type: SSD
          mountPath: /var/lib/containerd
          format: xfs

*在指定 dataVolumes 时必填。

dataVolumes[] 会随 ECS 一起重新创建。不要将它们用于 /var/cpaas 或任何必须在滚动替换后仍然保留的路径。

注意： 不要在 HCSMachineTemplate manifest 中设置诸如 providerID 或 serverId 之类的运行时标识字段。提供程序在创建 HCS 实例时会分配这些值。

注意： 租户管理员无法从 HCS UI 中检索提供程序可识别的 flavorName 和 availabilityZone 值。请在应用 manifest 之前向 HCS 管理员获取准确值。

#步骤 3：配置 Bootstrap Template

KubeadmConfigTemplate 定义了 worker 节点的 bootstrap 配置。

imagePullCredentialsVerificationPolicy: NeverVerify 仅从 Kubernetes 1.35 开始才是必需的。在使用 Kubernetes 1.34 或更早版本创建 worker 时，请省略此参数。

apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: <cluster-name>-worker-kct
  namespace: cpaas-system
spec:
  template:
    spec:
      files:
        - path: /etc/kubernetes/patches/kubeletconfiguration0+strategic.json
          owner: root:root
          permissions: "0644"
          content: |
            {
              "apiVersion": "kubelet.config.k8s.io/v1beta1",
              "kind": "KubeletConfiguration",
              "imagePullCredentialsVerificationPolicy": "NeverVerify",
              "protectKernelDefaults": true,
              "staticPodPath": null,
              "tlsCertFile": "/etc/kubernetes/pki/kubelet.crt",
              "tlsPrivateKeyFile": "/etc/kubernetes/pki/kubelet.key",
              "streamingConnectionIdleTimeout": "5m",
              "clientCAFile": "/etc/kubernetes/pki/ca.crt"
            }
      postKubeadmCommands:
        - chmod 600 /var/lib/kubelet/config.yaml
      joinConfiguration:
        patches:
          directory: /etc/kubernetes/patches
        nodeRegistration:
          kubeletExtraArgs:
            volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

HCS controller 在解析 worker cloud-init 数据时会注入 /etc/kubernetes/pki/kubelet.crt 和 /etc/kubernetes/pki/kubelet.key。上面的 kubelet patch 将 kubelet 配置为使用这些由 controller 提供的证书文件。

#步骤 4：配置 Machine Deployment

MachineDeployment 负责 worker 节点的创建和管理编排。

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: <cluster-name>-md-0
  namespace: cpaas-system
spec:
  clusterName: <cluster-name>
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
  template:
    spec:
      clusterName: <cluster-name>
      version: <kubernetes-version>
      nodeDrainTimeout: 1m
      nodeDeletionTimeout: 5m
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: <cluster-name>-worker-kct
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: HCSMachineTemplate
        name: <cluster-name>-worker-template

#扩容 Worker 节点

worker 节点扩容允许您根据工作负载需求调整集群容量。

#添加 Worker 节点

增加 worker 节点数量以处理更高的工作负载。

操作步骤：

1. 检查当前节点状态

   # List all machines in the cluster
   kubectl get machines -n cpaas-system
   
   # List machines for a specific MachineDeployment
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/deployment-name=<cluster-name>-md-0

2. 扩展配置池

   为新增节点向 pool 添加新的 machine 配置。如果新 worker 需要保留节点本地状态，例如 /var/cpaas，请在每个新配置中包含相应的 persistentDisks[] 条目。

   kubectl get hcsmachineconfigpool <cluster-name>-worker-pool -n cpaas-system -o yaml

   修改 pool 以包含新的 IP 条目，然后应用：

   kubectl apply -f <updated-pool-config.yaml>

   编辑 pool 时，除非您有意追加新的磁盘插槽，否则请保持所有现有的 configs[] 条目及其已接受的 persistentDisks[] 条目不变。

3. 扩容 MachineDeployment

   将 replicas 字段更新为所需的节点数量：

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

4. 监控扩容进度

   # Watch machines being created
   kubectl get machines -n cpaas-system -w
   
   # Check MachineDeployment status
   kubectl get machinedeployment <cluster-name>-md-0 -n cpaas-system

#删除 Worker 节点

减少 worker 节点数量以降低集群容量。

操作步骤：

1. 缩容 MachineDeployment

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

2. 监控移除进度

   kubectl get machines -n cpaas-system -w

   Cluster API controller 将会：

   • 清空所选节点上的资源（如果可能则逐出 pod）
   • 从 HCS 平台删除底层 VM
   • 移除 machine 资源

#升级 Machine 基础设施

要升级 worker machine 规格（CPU、内存、磁盘、VM image），请按照以下步骤操作：

注意： worker 基础设施升级依赖 Cluster API 的滚动替换。HCS dataVolumes[] 在替换过程中不会保留。若要保留诸如 /var/cpaas 之类的节点本地状态，请在发布之前将其声明在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中，并保持 MachineDeployment.spec.strategy.rollingUpdate.maxSurge: 0。

1. 创建新的 Machine Template

   复制现有的 HCSMachineTemplate 并修改所需值：

   • imageName - VM image
   • flavorName - 实例类型
   • rootVolume.size - 系统盘大小
   • dataVolumes - 临时数据盘配置

   如果您需要添加新的由 pool 管理的 persistent disk，请先将其追加到 worker 的 HCSMachineConfigPool 中。提供程序会创建或认领该 EVS 磁盘，但运行中的 ECS 不会挂载它，直到此滚动替换创建出替代 worker 为止。

   kubectl get hcsmachinetemplate <current-template> -n cpaas-system -o yaml > new-template.yaml

   然后在应用前编辑 new-template.yaml：

   • 将 metadata.name 更改为 <new-template>
   • 保留运行时标识字段为空，包括 spec.template.spec.providerID 和 spec.template.spec.serverId
   • 删除服务器生成的字段，例如：
     • metadata.resourceVersion
     • metadata.uid
     • metadata.creationTimestamp
     • metadata.managedFields
     • status

2. 部署新的 Template

   kubectl apply -f new-template.yaml -n cpaas-system

3. 更新 Machine Deployment

   修改 MachineDeployment 以引用新的 template：

   kubectl patch machinedeployment <cluster-name>-md-0 -n cpaas-system \
     --type='merge' -p='{"spec":{"template":{"spec":{"infrastructureRef":{"name":"<new-template>"}}}}}'

4. 监控滚动更新

   kubectl get machines -n cpaas-system -w

#升级 Kubernetes 版本

Kubernetes 版本升级需要同时协调更新 MachineDeployment 和底层 VM template。

注意： 确保 VM template 的 Kubernetes 版本与 MachineDeployment 中指定的版本一致。版本不匹配会导致节点加入失败。

操作步骤：

1. 更新 Machine Template

   创建一个新的 HCSMachineTemplate，并使用支持目标 Kubernetes 版本的更新后 imageName。

2. 为 Kubernetes 1.35 或更高版本创建新的 bootstrap template

   如果目标版本是 Kubernetes 1.35 或更高版本，请以新名称克隆当前的 KubeadmConfigTemplate，并将 所需的 kubelet patch 设置 添加到 /etc/kubernetes/patches/kubeletconfiguration0+strategic.json。KubeadmConfigTemplate 是不可变的，因此不要原地编辑所引用的 template。对于更早的版本，除非该 release 还有其他 bootstrap 更改，否则请跳过此步骤。

3. 更新 MachineDeployment

   修改以下字段：

   • spec.template.spec.version - 目标 Kubernetes 版本

   • spec.template.spec.infrastructureRef.name - 新的 machine template 名称

   • spec.template.spec.bootstrap.configRef.name - 新的 bootstrap template 名称；Kubernetes 1.35 或更高版本必需

     kubectl patch machinedeployment <cluster-name>-md-0 -n cpaas-system \
       --type='merge' -p='{"spec":{"template":{"spec":{"version":"<kubernetes-version>","infrastructureRef":{"name":"<new-template>"},"bootstrap":{"configRef":{"name":"<new-bootstrap-template>"}}}}}}'

   该命令包含 Kubernetes 1.35 或更高版本所需的 bootstrap 引用。对于没有 bootstrap 变更的更早目标版本，请省略 bootstrap 对象。

4. 监控升级

   验证新节点是否以正确的 Kubernetes 版本加入集群：

   kubectl get nodes

#验证

部署 worker 节点后，请验证部署结果：

# Check machine status
kubectl get machines -n cpaas-system

# Verify nodes are Ready
kubectl get nodes

# Check MachineDeployment status
kubectl get machinedeployment -n cpaas-system

#故障排查

#查看 Controller 日志

# View HCS controller logs
kubectl logs -n cpaas-system deployment/hcs-controller-manager

# View machine details
kubectl describe hcsmachine <machine-name> -n cpaas-system

#常见问题

节点加入集群失败

• 验证 VM template 是否与 Kubernetes 版本匹配
• 检查节点之间的网络连通性
• 确保配置池中有可用条目

Machine 卡在 provisioning 状态

• 检查 HCS 平台资源是否可用
• 验证凭据和权限
• 查看 controller 日志中的错误消息