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

当你将现有 Huawei Cloud Stack（HCS）集群从较旧的 HCSMachineTemplate data-volume 布局升级到池管理的持久磁盘模型时，请使用本指南。

在 HCS provider v1.0.1 或更高版本中，必须在节点替换后仍需保留的磁盘，会在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明。这也包括平台必需的 /var/cpaas 磁盘。

#概述

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

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

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

#开始之前

在开始前，请验证以下所有条件：

• 管理集群已安装 HCS provider v1.0.1 或更高版本。
• 业务集群处于健康状态，且所有节点均为 Ready。
• 集群使用 HCSMachineConfigPool 分配固定的 hostname 和 IP address。
• 在旧 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中，需保留的磁盘具有非空挂载路径。
• 相关 rollout 策略使用 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

检查当前 machine template：

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

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

#确定要保留哪些磁盘

仅将必须在节点替换后继续存在的磁盘迁移到池管理模型。

使用以下划分：

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

#创建新的 Machine Template

为替换节点创建新的 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 重新创建的临时 data volume。
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

#准备 Rollout 策略

在更新池之前，确认将使用更新后池的每个 controller 的 rollout 策略。如果该迁移中集群没有 worker pool，则跳过 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"}'

对于使用持久磁盘的 pool，返回值必须全部为 0。

如果任一返回值不为 0，请在更新池之前修补受影响的 rollout 策略：

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}}}}'

#更新 Machine Configuration Pool

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

在每个需要保留磁盘的 hostname 下添加一个 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

编辑池时，请遵循以下规则：

• 对每个 hostname，slot 从 0 开始。
• 对每个 hostname，保持 slot 连续。
• 将 size、type、mountPath 和 format 设置为与要接管的旧 data volume 一致。
• 如果池中尚未包含 cluster.x-k8s.io/cluster-name: <cluster-name>，请添加它。
• 对于所有需要保留相同路径的节点，保持相同的 persistent-disk 声明。

仅在替换模板已存在、已从 dataVolumes[] 中移除保留路径，并且 rollout 策略使用 maxSurge: 0 之后，再应用更新后的池：

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

#触发滚动替换

应用更新后的池后，请立即在同一个维护窗口内将控制平面或 worker controller 指向新模板。不要让声明了 /var/cpaas 持久磁盘的池，仍然指向一个在 dataVolumes[] 中也声明了 /var/cpaas 的旧模板。

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

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

对于 worker 迁移，请将 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。provider 会阻止删除，以避免在安全接管并分离磁盘之前删除旧 ECS。

#限制和恢复说明

• 此操作步骤适用于使用具有固定 hostname 和 IP address 的 HCSMachineConfigPool 的集群。
• 池管理的持久磁盘需要逐台替换。对使用持久磁盘的每个控制平面或 worker rollout，都请保持 maxSurge: 0。
• provider 会通过匹配非空 mountPath 自动接管现有 data volume。
• 未在 persistentDisks[] 中声明的 dataVolumes[] 仍归模板所有，并可能随旧 ECS 一起删除。
• 在 provider 接受持久磁盘条目后，请将 slot、size、type、format 和 mountPath 视为不可变。
• mountOptions 可以更改，但更改仅会在替换 VM 上生效。
• 单控制平面 HCS 集群是所述升级工作流中的仅创建拓扑。不要对单控制平面集群使用此滚动迁移操作步骤。

#相关主题

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