#在现有 HCS 集群上配置 FQDN 主机名

当现有的 Huawei Cloud Stack (HCS) 集群中的节点需要满足：POSIX hostname 返回短标签，而 hostname -f 返回完整 FQDN，且该集群最初创建于 cluster-api-provider-hcs v1.0.1 之前时，请使用本指南。

依赖正常工作的 hostname / hostname -f 分离行为的应用——例如 TLS server certificate SAN 匹配、Kerberos SPN 组合、按短名称键控的监控标签，以及任何调用 getfqdn() 的代码——都要求节点由 cluster-api-provider-hcs v1.0.1 或更高版本初始化。cloud-init 只会在首次启动时运行，因此现有节点不会自动获取新的行为；必须在新的 controller 就绪后，通过标准 Cluster API 滚动替换流程替换这些节点。

#概述

节点要暴露受支持的 hostname / FQDN 行为，必须同时满足以下两个条件：

1. 节点的 HCSMachineConfigPool.spec.configs[].hostname 条目包含一个点号（FQDN 形式，例如 master-1.example.org）。
2. 该节点首次启动时由 cluster-api-provider-hcs v1.0.1 或更高版本引导。

在旧 controller 下启动的现有节点会继续使用首次启动时获得的 cloud-init user-data，因此编辑 manifest 或重新应用 user-data 不会回溯性地更改它们的 hostname 行为。受支持的迁移路径是通过 Cluster API 滚动替换这些节点，并确保升级后的 controller 已安装且在管理集群中处于 Ready 状态。

对节点上的 /etc/hostname 和 /etc/hosts 进行手工编辑不会在不可变 OS 节点上持久保留。cloud-init 会在每次启动时重新渲染这些文件，包括由 transactional-update、OS patching 或 systemctl reboot 触发的重启。

#前提条件

• 管理集群上的 cluster-api-provider-hcs 插件版本为 v1.0.1 或更高，且 cpaas-system 中的 controller Deployment 处于 Ready 状态。
• 现有 workload cluster 运行正常：所有当前 Machine 对象都报告 phase=Running，所有 Node 对象都报告 Ready，并且没有正在进行的滚动替换。
• 已查看存储注意事项（参见 Storage and data caveats）。
• 现有 HCSMachineTemplate 使用的目标 VM image 仍然存在于 HCS 环境中。（无需更换 image；迁移仅通过重命名 template 来触发替换。）
• control plane 的 HCSMachineConfigPool 至少有一个未使用的 (hostname, IP) 槽位，以便 Cluster API 可以在驱逐旧机器之前先扩容出一台新的 control plane 机器。如果现有 pool 的大小刚好等于当前副本数，请在开始前先再增加一条条目。

#操作步骤

#1. 确认 controller 已升级

kubectl get deployment -n cpaas-system -l app=cluster-api-provider-hcs-manager -o wide
kubectl rollout status deployment -n cpaas-system cluster-api-provider-hcs-manager

该 Deployment 必须显示 v1.0.1 或更高版本的 image tag，并报告所有副本均为 Ready。在 controller 升级之前替换节点，会使新 VM 重新渲染旧的 user-data，导致集群仍处于相同状态。

#2. 确定哪些 pool 和 template 在范围内

只有条目中包含点号的 pool 才需要迁移。列出现有的 HCSMachineConfigPool 资源，并检查每个 spec.configs[].hostname：

kubectl get hcsmachineconfigpool -n cpaas-system
kubectl get hcsmachineconfigpool <pool-name> -n cpaas-system \
  -o jsonpath='{range .spec.configs[*]}{.hostname}{"\n"}{end}'

条目全部为短标签（不含点号）的 pool 不受此次迁移影响，无需处理。只继续处理包含带点条目的 pool。

#3. 为 control plane pool 增加一个 surge 槽位

Cluster API 会一次替换一台 control plane 机器。默认的 rollout 策略需要 pool 中有一个空闲的 (hostname, IP) 槽位，以便在终止旧机器之前先拉起替换机器。如果现有 control plane pool 的条目数刚好等于 KubeadmControlPlane.spec.replicas，现在请再添加一条：

kubectl edit hcsmachineconfigpool <cp-pool-name> -n cpaas-system

在 spec.configs 下添加一个额外条目，使用新的 hostname 和同一子网中的一个空闲 IP，然后保存。该新条目会被保留备用，只会在第一台机器被替换时才被消耗。

#4. 为 control plane 创建一个新的 HCSMachineTemplate

新 template 可以逐字节复制现有 template，只需修改一个新的 metadata.name。仅重命名就足以触发 Cluster API 滚动机器并获取新的 user-data；无需更改 imageName、flavorName 或任何其他字段。

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

编辑 new-cp-template.yaml：

• 将 metadata.name 设置为一个新值（例如追加 -fqdn 或日期后缀）。
• 删除服务器生成的元数据（resourceVersion、uid、generation、creationTimestamp、managedFields、kubectl.kubernetes.io/last-applied-configuration 注解）以及整个 status 字段。
• 保持运行时身份字段为空，包括 spec.template.spec.providerID 和 spec.template.spec.serverId。HCS provider 在创建新 VM 时会分配这些值。

应用新的 template：

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

在 rollout 健康之前保留旧 template；回滚时需要使用它。

#5. patch KubeadmControlPlane 以引用新的 template

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

Cluster API 现在会开始对 control plane 进行滚动替换。监控进度：

kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system -w
kubectl get machines -n cpaas-system -l cluster.x-k8s.io/control-plane

等待直到所有 control plane Machine 都变成新的机器（旧的 Machine 名称消失），并且 KubeadmControlPlane.status.readyReplicas 等于 spec.replicas。

#6. 对每个 MachineDeployment（worker）重复上述步骤

对于每个需要新 hostname 行为的 MachineDeployment，使用 worker template 重复步骤 4 和 5：

kubectl get hcsmachinetemplate <current-worker-template> -n cpaas-system -o yaml > new-worker-template.yaml
# Edit metadata.name, strip status/server fields, apply
kubectl apply -f new-worker-template.yaml -n cpaas-system

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

在继续之前，等待每个 MachineDeployment 报告 status.updatedReplicas 等于 spec.replicas，并且所有 worker Machine 对象都已切换到新的 template。

#7. 在每个新节点上验证 hostname 行为

在每个新节点上执行：

hostname
hostname -f
cat /etc/hosts

对于其 pool 配置为 hostname: master-1.example.org 的节点，预期结果为：

• hostname 返回 master-1（短标签，去掉点号及其后的所有内容）。
• hostname -f 返回 master-1.example.org。
• /etc/hosts 包含如下形式的条目：<loopback-or-node-ip> master-1.example.org master-1。

如果新节点报告 hostname 返回 FQDN 风格字符串，或者 hostname -f 返回 Name or service not known，应首先检查该节点上的 cloud-init 日志（/var/log/cloud-init.log 和 /var/lib/cloud/instance/user-data.txt），然后确认 controller 确实已升级到 v1.0.1 或更高版本。

#存储和数据注意事项

滚动替换会销毁每台旧 VM，并根据新 template 构建一个新的替换实例。在 HCS 上：

• 系统磁盘（root volume）会在每次替换时从 VM image 重新构建。
• 在 HCSMachineTemplate.spec.template.spec.dataVolumes 中声明的数据卷不会被卸载并重新挂载；旧 VM 上的卷可能会随之被移除。
• workload 数据必须存放在外部持久化存储（HCS EVS CSI 或等效方案）上，才能在迁移中保留。

开始之前，请完成任何节点本地状态的完整备份和迁移。

#回滚

如果新的 rollout 不健康——新 VM 无法启动、节点无法变为 Ready，或者应用出现意外故障——请将每个受影响资源 patch 回之前的 template 名称。Cluster API 会将该回退视为新的 spec drift，并把新机器滚回到之前的 template：

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

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

在新的 rollout 健康之前，不要删除旧的 HCSMachineTemplate。如果它已经被删除，请先从版本控制或备份中重新创建，再执行回滚。

#相关内容

• 升级 Huawei Cloud Stack 上的集群 — Kubernetes 版本升级使用相同的滚动替换机制。
• 排查 Huawei Cloud Stack Workload Clusters — 用于诊断当未修复的 controller 启动带点号 hostname 的节点时出现的 kubeadm-init-stalled 症状。
• 排查处于 Provisioned 状态的 Workload Cluster — 与 provider 无关的 import-controller 诊断流程。
• 节点上的 hostname 行为 — 在新建集群中，短条目与带点条目的 hostname / hostname -f / /etc/hosts 表现。