#在 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 清单管理这些资源。Web UI 提供引导式体验，并且仅在满足以下版本要求时可用；YAML 适用于所有受支持的 provider 版本。

#使用 Web UI

版本要求：此工作流需要 Fleet Essentials 1.0.2 或更高版本，以及 Alauda Container Platform HCS Infrastructure Provider v1.0.3 或更高版本。在较早的 provider 版本中，请使用 使用 YAML 部分中的 YAML 工作流管理节点池。

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

#查看 Node Pools

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

#添加 Worker Node Pool

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

所选的 Availability Zone 会应用于新 worker 池中的每个节点。若要将 worker 节点放置到其他区域，请创建单独的 worker 池并选择该区域；一个池不会自动将其副本分散到多个区域。下拉菜单会禁用 HCS 报告为不可用的区域。有关自动选择、persistent disk 和控制平面放置约束，请参见 Availability Zone Placement。

#管理节点 IP 地址

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

该对话框用于编辑池的 HCSMachineConfigPool 的 machine 配置。对于每个节点，你可以设置 hostname、网络（每个网络由从其子网中选择的 IP 地址以及子网组成）以及 persistent disks。IP 选择规则与创建向导相同：先选择子网，再从列表中选择可分配的地址；已经在使用中的地址不会显示。

#删除 Worker Node Pool

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

#使用 YAML

使用 Cluster API 清单管理 worker 节点。此工作流适用于所有受支持的 provider 版本。

#部署 Worker 节点

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

#步骤 1：配置 Machine Configuration Pool

HCSMachineConfigPool 定义 worker 节点 VM 的网络配置以及任何由池管理的 persistent disks。在部署之前，你必须先规划并配置 IP 地址、hostname、persistent disk 位置以及其他参数。

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

如果你为 worker 节点使用 subnetName, 请在创建或扩容 worker 池之前，将相同的子网名称包含在父级 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

*对于新清单，请设置 subnetName 或 subnetId 其一。现有清单可以继续使用 subenetName，并且只有在两个字段值相同的情况下才可以添加 subnetName。不要提供冲突的子网选择器值。

当指定 persistentDisks 时，persistent disk 字段是必需的。

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

注意： CRD schema 将 subnetName、subenetName 和 subnetId 列为可选字段，并且不会表达它们允许的组合。在编写清单时，请遵循上述 provider 级别规则。

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

#worker 的池管理 persistent disks

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

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

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

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

#步骤 2：配置 Machine Template

HCSMachineTemplate 定义 worker 节点的 VM 规格。

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

在准备 worker 模板时，请使用 provider 可识别的 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 清单中设置诸如 providerID 或 serverId 之类的运行时标识字段。provider 在创建 HCS 实例时会分配这些值。

注意： ACP web UI 会通过所选的 HCS 凭证加载 flavor 和 availability zone。编写 YAML 时，请向 HCS 管理员获取精确的、provider 可识别的 Flavor.Name 和 ZoneName 值，因为原生 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. 扩展配置池

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

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

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

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

   编辑池时，除非你有意追加新的磁盘槽位，否则请保持所有现有的 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 Infrastructure

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

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

1. 创建新的 Machine Template

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

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

   如果你需要添加新的池管理 persistent disk，请先将其追加到 worker HCSMachineConfigPool 中。provider 会创建或认领 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. 部署新模板

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

3. 更新 Machine Deployment

   修改 MachineDeployment 以引用新模板：

   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 模板。

注意： 确保 VM 模板中的 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 是不可变的，因此不要直接修改已引用的模板。对于更早的版本，如果该版本没有其他 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 模板是否与 Kubernetes 版本匹配
• 检查节点之间的网络连通性
• 确保配置池中有可用条目

Machine 卡在 provisioning 状态

• 检查 HCS 平台的资源可用性
• 验证凭证和权限
• 查看 controller 日志以获取错误消息