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

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

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

#概述

节点要呈现受支持的主机名 / FQDN 行为，以下两个条件必须同时满足：

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

在旧控制器下启动的现有节点会继续使用其首次启动时接收的 cloud-init 用户数据，因此编辑清单或重新应用用户数据不会追溯性地更改其主机名行为。受支持的迁移路径是通过 Cluster API 滚动替换来替换这些节点，并确保升级后的控制器已安装在管理集群上且处于 Ready 状态。

在节点上手动编辑 /etc/hostname 和 /etc/hosts 不会在 Alauda OS 节点上持久化。Cloud-init 会在每次启动时重新呈现这些文件，包括由 transactional-update、OS 修补或 systemctl reboot 触发的重启。

#前提条件

• 管理集群上的 Huawei Cloud Stack Infrastructure Provider 为此版本随附的版本（cluster-api-provider-hcs v1.0.1 或更高版本），且 cpaas-system 中的控制器 Deployment 处于 Ready 状态。
• 现有业务集群运行正常：所有当前的 Machine 对象均报告 phase=Running，所有 Node 对象均报告 Ready，且当前没有正在进行的滚动替换。
• 已检查存储注意事项（参见存储和数据注意事项）。
• 现有 HCSMachineTemplate 使用的目标 VM 镜像仍存在于 HCS 环境中。（无需更改镜像；此次迁移仅重命名模板以触发替换。）
• 控制平面 HCSMachineConfigPool 至少有一个未使用的 (hostname, IP) 槽位，以便 Cluster API 在排空旧控制平面机器之前，可以先扩容出一个新的控制平面机器。如果现有池的大小恰好等于当前副本数，请在开始前为其再添加一个条目。

#操作步骤

#1. 确认控制器已升级

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 或更高版本的镜像标签，并报告所有副本均处于 Ready 状态。在控制器升级之前替换节点，会在新 VM 上重新呈现旧的用户数据，使集群保持原有状态。

#2. 确定涉及的池和模板

仅包含带点条目的池需要迁移。列出现有的 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}'

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

#3. 为控制平面池扩展一个扩容槽位

Cluster API 一次替换一个控制平面机器。默认滚动更新策略需要池中有一个空闲的 (hostname, IP) 槽位，以便在终止旧机器之前启动替换机器。如果现有控制平面池的条目数恰好等于 KubeadmControlPlane.spec.replicas，请立即再添加一个条目：

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

在 spec.configs 下添加一个额外条目，为其设置新的主机名以及来自同一子网的空闲 IP，然后保存。新条目会作为备用项保留，仅在替换第一台机器时使用。

#4. 为控制平面创建新的 HCSMachineTemplate

新模板可以是现有模板的逐字节副本，只需使用新的 metadata.name。仅重命名就会触发 Cluster API 滚动机器并获取新的用户数据；无需更改 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 时分配这些值。

应用新模板：

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

在滚动更新确认正常之前，请保留旧模板；回滚时需要使用它。

#5. 修补 KubeadmControlPlane 以引用新模板

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

Cluster API 现在会开始滚动替换控制平面。监控进度：

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

等待每个控制平面 Machine 都变为新模板（旧的 Machine 名称消失），并且 KubeadmControlPlane.status.readyReplicas 等于 spec.replicas。

#6. 对每个 MachineDeployment 重复上述操作（工作节点）

对于节点需要采用新主机名行为的每个 MachineDeployment，使用工作节点模板重复步骤 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，并且所有工作节点 Machine 对象均使用新模板后，再继续操作。

#7. 验证每个新节点上的主机名行为

在每个新节点上：

hostname
hostname -f
cat /etc/hosts

对于池配置为 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），然后确认控制器确实为 v1.0.1 或更高版本。

#存储和数据注意事项

滚动替换会销毁每个旧 VM，并根据新模板创建一个全新的替代 VM。在 HCS 上：

• 每次替换时，系统磁盘（根卷）都会根据 VM 镜像重新构建。
• HCSMachineTemplate.spec.template.spec.dataVolumes 中声明的数据卷不会先分离再重新挂载；旧 VM 上的卷可能会随旧 VM 一起被删除。
• 工作负载数据必须存储在外部持久化存储上（HCS EVS CSI 或同等存储），才能在迁移后保留。

开始操作前，请完成所有节点本地状态的备份和迁移。

#回滚

如果新的部署不健康——新 VM 无法启动、节点未变为 Ready，或应用以意料之外的方式出现故障——请将每个受影响资源的模板名称改回之前的名称。Cluster API 会将回退视为新的规格偏差，并将新机器回滚到之前的模板：

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

在新部署运行正常之前，请勿删除之前的 HCSMachineTemplate。如果该模板已被删除，请先从版本控制或备份中重新创建，再执行回滚。

#相关内容

• 在 Huawei Cloud Stack 上升级 Kubernetes — Kubernetes 版本升级使用相同的滚动替换机制。
• 排查 Huawei Cloud Stack 业务集群故障 — 诊断未修复的控制器启动使用带点主机名的节点时出现的 kubeadm-init-stalled 症状。
• 排查卡在 Provisioned 状态的业务集群 — 与云服务提供商无关的导入控制器诊断流程。
• 节点上的主机名行为 — 在新创建的集群上，池条目为短名称或带点名称时，hostname / hostname -f / /etc/hosts 的表现。