#在 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 - 节点创建和管理编排

#Worker 节点部署

在准备 worker YAML 之前，请先完成 Infrastructure Resources for Huawei Cloud Stack 中的 HCS 输入清单。特别是，需在 HCSCluster.spec.network.subnets 中列出每个 worker 子网，从规划好的空闲 IP 范围中分配 worker IP，并收集 provider 可识别的 flavorName 和 availabilityZone API 值。如果您为现有的 Ready 集群新增一个 worker 子网，请使用完整的子网对象对 HCSCluster.spec.network.subnets 进行 patch，而不是只添加子网名称。

#步骤 1：配置 Machine Configuration Pool

HCSMachineConfigPool 定义 worker 节点 VM 的网络配置。您必须在部署之前规划并配置 IP 地址、主机名和其他网络参数。

为每个 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: <worker-pool-name>
  namespace: cpaas-system
spec:
  configs:
    - hostname: <worker-1-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-1-ip>
    - hostname: <worker-2-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-2-ip>
    - hostname: <worker-3-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <worker-3-ip>

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

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

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

#步骤 2：配置 Machine Template

HCSMachineTemplate 定义 worker 节点的 VM 规格。

为 worker 节点配置一个系统卷，以及用于 /var/lib/kubelet、/var/lib/containerd 和 /var/cpaas 的数据卷。您可以添加更多数据卷，但请保留这些路径，以便节点引导和平台组件可以使用预期的运行时目录。这些路径并不意味着在节点被替换时数据卷会被保留。

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

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

*当指定 dataVolumes 时必填。

注意： 请勿在 HCSMachineTemplate manifest 中设置 providerID 或 serverId 等运行时身份字段。provider 会在创建 HCS 实例时分配这些值。

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

#步骤 3：配置 Bootstrap Template

KubeadmConfigTemplate 定义 worker 节点的 bootstrap 配置。

apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: <worker-config-template>
  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",
              "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: <worker-machine-deployment>
  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: <worker-config-template>
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: HCSMachineTemplate
        name: <worker-machine-template>

#节点管理操作

本节介绍管理 worker 节点的常见操作任务。

#扩容 Worker 节点

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

#添加 Worker 节点

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

操作步骤：

1. 检查当前节点状态

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

2. 扩展配置池

   为新增节点向 pool 中添加新的 IP 配置。

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

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

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

3. 扩展 MachineDeployment

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

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

4. 监控扩容进度

   # 观察正在创建的 machines
   kubectl get machines -n cpaas-system -w
   
   # 检查 MachineDeployment 状态
   kubectl get machinedeployment <worker-machine-deployment> -n cpaas-system

#删除 Worker 节点

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

操作步骤：

1. 缩减 MachineDeployment

   kubectl patch machinedeployment <worker-machine-deployment> -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 将会：

   • 排空所选节点（如有可能，逐出 pods）
   • 从 HCS 平台删除底层 VM
   • 删除 machine 资源

#升级 Machine 基础设施

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

注意： worker 基础设施升级依赖 Cluster API 滚动替换。当前 HCS provider 在节点替换期间不会保留或重新挂载数据磁盘。当 worker 节点被替换时，旧 VM 及其附加卷可能会一起被删除。请在升级开始前将有状态数据迁移到外部持久化存储，或完成备份和迁移。

1. 创建新的 Machine Template

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

   • imageName - VM 镜像

   • flavorName - 实例规格

   • rootVolume.size - 系统盘大小

   • dataVolumes - 数据盘配置

     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 <worker-machine-deployment> -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. 更新 MachineDeployment

   修改以下字段：

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

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

     kubectl patch machinedeployment <worker-machine-deployment> -n cpaas-system \
       --type='merge' -p='{"spec":{"template":{"spec":{"version":"<kubernetes-version>","infrastructureRef":{"name":"<new-template>"}}}}}'

3. 监控升级

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

   kubectl get nodes

#验证

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

# 检查 machine 状态
kubectl get machines -n cpaas-system

# 验证 nodes 处于 Ready
kubectl get nodes

# 检查 MachineDeployment 状态
kubectl get machinedeployment -n cpaas-system

#故障排查

#查看 Controller 日志

# 查看 HCS controller 日志
kubectl logs -n cpaas-system deployment/hcs-controller-manager

# 查看 machine 详情
kubectl describe hcsmachine <machine-name> -n cpaas-system

#常见问题

节点无法加入集群

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

Machine 卡在 provisioning 状态

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