#将现有 Huawei Cloud Stack 集群迁移到由池管理的持久磁盘

当您将现有 Huawei Cloud Stack (HCS) 集群从旧版 HCSMachineTemplate 数据卷布局升级到由池管理的持久磁盘模型时，请使用本指南。

必须在节点替换后保留的磁盘在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明。其中包括平台所需的 /var/cpaas 磁盘。

#概述

旧版 HCS 集群通常会将 /var/cpaas 放置在 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中。该布局会随 ECS 一同创建数据卷。在滚动替换期间，旧 ECS 及其模板拥有的数据卷可能会一并删除。

由池管理的模型会将升级期间需保留的磁盘移至 HCSMachineConfigPool.spec.configs[].persistentDisks[]。每个持久磁盘都绑定到固定的 (hostname, slot) 标识。在滚动替换期间，提供程序会：

1. 当旧 ECS 上的现有 EVS 磁盘与池声明匹配时，认领该磁盘。
2. 停止旧 ECS。
3. 分离 EVS 磁盘，并等待其变为可用状态。
4. 删除旧 ECS。
5. 创建替换 ECS，并在其首次启动前挂载相同的 EVS 磁盘。
6. 启动替换 ECS，替换 ECS 会挂载现有文件系统，而不会对其重新格式化。

#开始之前

开始前，请验证以下所有事项：

• HCS provider 已安装在管理集群上。
• 业务集群运行正常，并且所有节点均为 Ready。
• 集群使用 HCSMachineConfigPool 分配固定的主机名和 IP 地址。
• 需保留的磁盘在旧版 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中具有非空的挂载路径。
• 相关的滚动更新策略使用 maxSurge: 0。
• 您已为逐个节点替换安排维护窗口。
• 您拥有一份已验证的 etcd 和平台配置备份。

#检查当前磁盘布局

识别用于控制集群的管理集群对象：

kubectl get cluster -n cpaas-system
kubectl get kubeadmcontrolplane -n cpaas-system
kubectl get machinedeployment -n cpaas-system
kubectl get hcsmachinetemplate -n cpaas-system
kubectl get hcsmachineconfigpool -n cpaas-system
kubectl get hcsmachine -n cpaas-system

检查当前机器模板：

kubectl get hcsmachinetemplate <template-name> -n cpaas-system -o yaml

记录所有必须保留的 dataVolumes[] 条目。对于每个磁盘，请记录：

#决定要保留哪些磁盘

仅将节点替换后必须保留的磁盘迁移到由池管理的模型。

按以下方式划分：

对于自动迁移，provider 会通过匹配 mountPath 来认领现有数据卷。如果要保留的磁盘没有 mountPath，则无法自动认领。请使用受支持的运维操作步骤，将现有 EVS volumeID 记录到 status.persistentDiskStatus[] 中，或者在触发替换前将数据迁移到声明了挂载路径的磁盘。

#创建新的机器模板

为替换节点创建新的 HCSMachineTemplate 资源。不要直接修改现有模板。

复制当前模板：

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

编辑 new-template.yaml：

1. 将 metadata.name 设置为新的模板名称。
2. 删除服务器生成的元数据，例如 resourceVersion、uid、creationTimestamp、managedFields 和 status。
3. 保持运行时身份字段未设置，包括 spec.template.spec.providerID 和 spec.template.spec.serverId。
4. 从 spec.template.spec.dataVolumes[] 中删除要保留的路径。
5. 仅保留可随每个 ECS 重新创建的临时数据卷。
6. 当此迁移属于 Kubernetes 或镜像升级的一部分时，更新 spec.template.spec.imageName 和其他升级字段。

例如，在 /var/cpaas 移入池后，模板仅保留临时磁盘：

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

应用新模板：

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

#准备滚动发布策略

更新池之前，确认每个将使用更新后池的控制器的滚动发布策略。如果此次迁移没有工作节点池，请跳过 MachineDeployment 命令。

kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system \
  -o jsonpath='{.spec.rolloutStrategy.rollingUpdate.maxSurge}{"\n"}'

kubectl get machinedeployment <md-name> -n cpaas-system \
  -o jsonpath='{.spec.strategy.rollingUpdate.maxSurge}{"\n"}'

对于使用持久化磁盘的池，每个返回值都必须为 0。

如果任何返回值不是 0，请在更新池之前修补受影响的滚动发布策略：

kubectl patch kubeadmcontrolplane <kcp-name> -n cpaas-system \
  --type='merge' \
  -p='{"spec":{"rolloutStrategy":{"type":"RollingUpdate","rollingUpdate":{"maxSurge":0}}}}'

kubectl patch machinedeployment <md-name> -n cpaas-system \
  --type='merge' \
  -p='{"spec":{"strategy":{"type":"RollingUpdate","rollingUpdate":{"maxSurge":0}}}}'

#更新机器配置池

编辑由旧的和新的 HCSMachineTemplate.spec.template.spec.configPoolRef.name 引用的 HCSMachineConfigPool。

在每个必须保留磁盘的主机名下添加一个 persistentDisks[] 条目：

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

编辑池时遵循以下规则：

• 对于每个主机名，将 slot 从 0 开始设置。
• 对于每个主机名，保持槽位连续。
• 将 size、type、mountPath 和 format 设置为要认领的旧数据卷的对应值。
• 每个池 mountPath 必须与现有数据卷的 mountPath 完全匹配。否则会创建新的空磁盘，而不是使用旧磁盘，并且旧磁盘会随旧 ECS 一起删除。
• 如果池尚未包含 cluster.x-k8s.io/cluster-name: <cluster-name>，请添加它。
• 对于必须保留相同路径的所有节点，使用相同的持久化磁盘声明。

仅当替换模板已存在、已从 dataVolumes[] 中删除要保留的路径，并且滚动发布策略使用 maxSurge: 0 后，才应用更新后的池：

kubectl apply -f hcs-pool-persistent-disk.yaml -n cpaas-system

#触发滚动替换

在替换任何旧主机之前应用更新后的池。如果替换旧主机时池尚未声明 persistentDisks[]，其旧数据磁盘会与 ECS 一起删除。

应用更新后的池后，立即在同一维护窗口内将控制平面或工作节点控制器指向新模板。请勿在活动滚动发布仍指向旧模板，且该旧模板也在 dataVolumes[] 中声明 /var/cpaas 的情况下，保留声明 /var/cpaas 持久化磁盘的池。

对于控制平面迁移，将 KubeadmControlPlane 指向新模板：

kubectl patch kubeadmcontrolplane <kcp-name> -n cpaas-system \
  --type='merge' \
  -p='{"spec":{"machineTemplate":{"infrastructureRef":{"name":"<new-template-name>"}}}}'

对于工作节点迁移，将 MachineDeployment 指向新模板：

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

如果模板引用已指向目标模板，并且需要强制逐一替换，请设置 rolloutAfter：

kubectl patch kubeadmcontrolplane <kcp-name> -n cpaas-system \
  --type='merge' \
  -p='{"spec": {"rolloutAfter": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}}'

kubectl patch machinedeployment <md-name> -n cpaas-system \
  --type='merge' \
  -p='{"spec": {"rolloutAfter": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}}'

#验证迁移

监控滚动替换：

kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system -w
kubectl get machinedeployment <md-name> -n cpaas-system -w
kubectl get machine -n cpaas-system -w
kubectl get hcsmachine -n cpaas-system -w

检查池状态：

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

每个已迁移的磁盘都会显示在 status.persistentDiskStatus 下：

确认替换节点可以从保留的路径读取数据：

kubectl --kubeconfig <workload-kubeconfig> debug node/<node-name> --image=busybox -- \
  chroot /host sh -c 'mount | grep /var/cpaas && ls -la /var/cpaas'

如需进行更严格的数据保留检查，请在滚动发布前写入标记，并在替换节点成为 Ready 后读取该标记：

kubectl --kubeconfig <workload-kubeconfig> debug node/<node-name> --image=busybox -- \
  chroot /host sh -c 'cat /var/cpaas/<marker-file>'

#故障处理

当磁盘进入 phase: Error 时，使用池状态决定下一步操作。

当持久化磁盘处于未解决的错误状态时，请勿删除旧的 HCSMachine，也不要强制移除 finalizer。提供商会阻止删除操作，以避免在能够安全声明并卸载磁盘之前删除旧 ECS。

#限制和恢复说明

• 此操作步骤适用于使用 HCSMachineConfigPool、且主机名和 IP 地址固定的集群。
• 由池管理的持久化磁盘必须逐个替换。对于使用持久化磁盘的每次控制平面或工作节点滚动发布，请保留 maxSurge: 0。
• 提供商会通过匹配非空的 mountPath 自动声明现有数据卷。
• 未在 persistentDisks[] 中声明的 dataVolumes[] 仍由模板管理，可能会随旧 ECS 一起删除。
• 提供商接受持久化磁盘条目后，请将 slot、size、type、format 和 mountPath 视为不可变。
• mountOptions 可以更改，但更改仅会在替换 VM 时生效。
• 单控制平面 HCS 集群仅支持创建，无法升级。请勿对单控制平面集群使用此滚动迁移操作步骤。

#相关主题

• Huawei Cloud Stack 的基础设施资源
• 在 Huawei Cloud Stack 上创建集群
• 在 Huawei Cloud Stack 上升级 Kubernetes