#Настройка FQDN-имени хоста на существующих кластерах HCS

Используйте это руководство, если существующему кластеру Huawei Cloud Stack (HCS) нужны узлы, у которых POSIX hostname возвращает короткое имя, а hostname -f — полное FQDN-имя, и если кластер был изначально создан до cluster-api-provider-hcs v1.0.1.

Приложения, которые зависят от корректного разделения hostname / hostname -f — сопоставление SAN в TLS-сертификате сервера, формирование SPN для Kerberos, метки мониторинга, использующие короткое имя, а также любой код, вызывающий getfqdn() — требуют, чтобы узел был инициализирован cluster-api-provider-hcs v1.0.1 или более поздней версии. Cloud-init выполняется только при первом запуске, поэтому существующие узлы не получают новое поведение автоматически; узел необходимо заменить через стандартный механизм пошаговой замены Cluster API с уже установленным новым контроллером.

#Обзор

Для того чтобы узел предоставлял поддерживаемое поведение hostname / FQDN, должны одновременно выполняться два условия:

1. Запись HCSMachineConfigPool.spec.configs[].hostname на узле содержит точку (форма FQDN, например master-1.example.org).
2. Узел был впервые загружен cluster-api-provider-hcs v1.0.1 или более поздней версии.

Существующие узлы, загруженные под управлением более старого контроллера, продолжают использовать user-data cloud-init, полученный при первом запуске, поэтому редактирование манифестов или повторное применение user-data не изменяет их поведение hostname задним числом. Поддерживаемый путь миграции — заменить эти узлы через пошаговую замену Cluster API, при этом уже установлен и готов к работе на управляющем кластере обновлённый контроллер.

Ручные изменения файлов /etc/hostname и /etc/hosts на самом узле не сохраняются на узле с неизменяемой ОС. Cloud-init пересоздаёт эти файлы при каждой загрузке, включая перезагрузки, вызванные transactional-update, обновлением ОС или systemctl reboot.

#Предварительные требования

• Плагин cluster-api-provider-hcs на управляющем кластере имеет версию v1.0.1 или более позднюю, а Deployment контроллера в cpaas-system находится в состоянии Ready.
• Существующий workload-кластер работоспособен: все текущие объекты Machine имеют phase=Running, все объекты Node находятся в состоянии Ready, и пошаговая замена не выполняется.
• Ограничения по хранилищу изучены (см. Ограничения по хранилищу и данным).
• Целевой образ VM, используемый существующим HCSMachineTemplate, по-прежнему присутствует в среде HCS. (Изменение образа не требуется; миграция только переименовывает шаблон, чтобы инициировать замену.)
• На пуле HCSMachineConfigPool для control plane имеется как минимум один неиспользуемый слот (hostname, IP), чтобы Cluster API мог создать новую машину control plane до вывода из эксплуатации старой. Если размер существующего пула точно соответствует текущему количеству реплик, перед началом добавьте ещё одну запись.

#Пошаговая процедура

#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. Замена узлов до обновления контроллера приведёт к повторному формированию старого user-data на новых 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. Расширьте пул control plane, добавив слот для surge

Cluster API заменяет машины control plane по одной. Стратегия развертывания по умолчанию требует свободного слота (hostname, IP) в пуле, чтобы поднять заменяющую машину до завершения работы старой. Если в существующем пуле control plane ровно столько же записей, сколько указано в KubeadmControlPlane.spec.replicas, добавьте сейчас ещё одну запись:

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

Добавьте дополнительную запись в spec.configs с новым hostname и свободным IP-адресом из той же подсети, затем сохраните изменения. Новая запись резервируется и используется только при замене первой машины.

#4. Создайте новый HCSMachineTemplate для control plane

Новый шаблон может быть побайтной копией существующего, но с новым 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 назначит эти значения при создании новых 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 начинает пошаговую замену 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 исчезнут), а KubeadmControlPlane.status.readyReplicas станет равным spec.replicas.

#6. Повторите для каждого MachineDeployment (worker-узлы)

Для каждого MachineDeployment, чьим узлам требуется новое поведение hostname, повторите шаги 4 и 5 с worker-шаблоном:

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 worker-узлов будут созданы на новом шаблоне.

#7. Проверьте поведение hostname на каждом новом узле

На каждом новом узле:

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 и создаёт свежую замену на основе нового шаблона. В HCS:

• Системный диск (корневой том) пересоздаётся из образа VM при каждой замене.
• Тома данных, объявленные в HCSMachineTemplate.spec.template.spec.dataVolumes, не отсоединяются и не присоединяются заново; тома на старой VM могут быть удалены вместе с ней.
• Данные workload должны храниться во внешнем постоянном хранилище (HCS EVS CSI или эквивалент), чтобы пережить миграцию.

Перед началом выполните полное резервное копирование и миграцию любого локального состояния узла.

#Откат

Если новое развертывание работает нестабильно — новые VM не загружаются, узлы не переходят в состояние Ready, или приложения ломаются неожиданным образом — верните каждый затронутый ресурс к имени предыдущего шаблона. Cluster API рассматривает возврат как новый drift спецификации и откатывает новые машины обратно на предыдущий шаблон:

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 используют тот же механизм пошаговой замены.
• Устранение неполадок workload-кластеров Huawei Cloud Stack — диагностика симптома kubeadm-init-stalled, который появляется, когда неисправленный контроллер загружает узел с dotted-hostname.
• Устранение неполадок workload-кластера, застрявшего в состоянии Provisioned — независимый от провайдера диагностический поток для import-controller.
• Поведение hostname на узле — как выглядят hostname / hostname -f / /etc/hosts для коротких и dotted-записей пула на только что созданном кластере.