#Обновление кластеров в Huawei Cloud Stack

Это руководство объясняет, как обновлять кластеры Kubernetes в Huawei Cloud Stack с минимальным временем простоя, сохраняя стабильность и целостность данных.

#Обзор

Обновления кластеров в HCS охватывают несколько компонентов и следуют структурированному подходу, чтобы обеспечить надежность системы:

• Обновления плоскости управления: обновление компонентов плоскости управления Kubernetes и базовой инфраструктуры
• Обновления рабочих узлов: обновление рабочих узлов с новыми образами машин и версиями Kubernetes
• Обновления инфраструктуры: изменение спецификаций виртуальных машин, хранилища и сетевых настроек

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

Обновляйте кластеры HCS в следующем порядке:

1. (Предварительное условие) Сначала обновите платформу ACP в управляющем кластере. Это приводит контроллер cluster-api-provider-hcs и связанные компоненты CAPI к версиям, которые понимают новую схему. Запускайте обновления рабочих кластеров только после того, как контроллеры на стороне управления завершат развертывание и перейдут в состояние Ready.
2. Обновите версию Distribution на рабочем кластере. См. Обновление кластеров.
3. Обновите версию Kubernetes плоскости управления.
4. Обновите рабочие узлы до целевой версии Kubernetes.

Cluster API оркестрирует поэтапные обновления со встроенными механизмами безопасности, чтобы снизить влияние на сервисы.

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

Перед началом убедитесь, что выполнены все перечисленные ниже предварительные требования:

• Обновление Distribution Version завершено.
• Плоскость управления доступна.
• Все узлы исправны и находятся в состоянии Ready.
• Целевой образ VM присутствует в среде HCS под тем же именем, что и значение Alauda OS Image Version в строке OS Support Matrix. Обновление завершится ошибкой, если образ отсутствует в момент применения нового HCSMachineTemplate.
• Для межверсийных обновлений, охватывающих более одного minor-уровня Kubernetes, промежуточные Core-образы и образы VM заранее подготовлены. См. Подготовка к межверсийному обновлению.
• Целевая версия Kubernetes совместима с вашими рабочими нагрузками и дополнениями.
• Проверьте путь обновления Kubernetes и политику допустимого расхождения версий.
• Любое локальное состояние узла, которое должно пережить замену, должно быть объявлено в HCSMachineConfigPool.spec.configs[].persistentDisks[], а не в HCSMachineTemplate.spec.template.spec.dataVolumes[].

Для первоначального развертывания см. руководство Создание кластера.

#Обновления плоскости управления

Обновления плоскости управления затрагивают API server Kubernetes, etcd, scheduler и controller manager, а также базовую инфраструктуру VM.

Для плоскостей управления HCS, основанных на HCSMachineConfigPool, который использует постоянные диски, управляемые пулом, сохраняйте KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge: 0 во время обновления. Постоянные диски привязаны к фиксированным идентификаторам (hostname, slot), поэтому при rollout старый узел должен быть удален до того, как новый узел сможет повторно использовать тот же диск.

#Обновления образа инфраструктуры

Обновление базовых образов машин для узлов плоскости управления обеспечивает исправления безопасности, улучшение производительности и обновленные системные компоненты.

#Процедура

1. Создайте обновленный шаблон машины

   Скопируйте существующий HCSMachineTemplate, на который ссылается KubeadmControlPlane, и измените необходимые спецификации:

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

2. Измените спецификации шаблона

   Измените новый шаблон:

   • Установите metadata.name в <new-template-name>
   • Удалите из скопированного манифеста метаданные и поля status, сгенерированные сервером.
   • Не заполняйте поля идентичности времени выполнения, включая spec.template.spec.providerID и spec.template.spec.serverId. Поставщик HCS назначает эти значения при создании экземпляров.
   • Не включайте сохраняемые пути, такие как /var/cpaas, в spec.template.spec.dataVolumes[]. Объявляйте эти пути в указанном HCSMachineConfigPool.spec.configs[].persistentDisks[].
   • При необходимости обновите:
     • spec.template.spec.imageName
     • spec.template.spec.flavorName
     • spec.template.spec.rootVolume.size
     • spec.template.spec.dataVolumes только для временных дисков

3. Разверните обновленный шаблон

   Примените новый шаблон машины:

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

4. Обновите ссылку плоскости управления

   Измените ресурс KubeadmControlPlane, чтобы он ссылался на новый шаблон:

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

5. Отслеживайте поэтапное обновление

   Плоскость управления автоматически выполнит поэтапное обновление:

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

#Обновления версии Kubernetes

Обновление версии Kubernetes включает обновление как программного обеспечения плоскости управления, так и поддерживающих образов виртуальных машин.

#Обязательные значения из матрицы поддержки ОС

Авторитетное сопоставление между выпуском ACP, его образом Alauda OS, версией Kubernetes, соответствующими версиями CoreDNS, etcd и Kube-OVN находится в Матрица поддержки ОС. Перед началом найдите строку, соответствующую целевой версии ACP; в этой строке содержатся все значения, необходимые для процедуры ниже.

Ячейки, которые вы берете из этой строки, сопоставляются с манифестами обновления следующим образом:

Теги образов CoreDNS и etcd относятся только к плоскости управления, поскольку clusterConfiguration — это поле KubeadmControlPlane. Рабочие узлы наследуют версии контейнерных образов из нового шаблона VM; MachineDeployment не содержит собственных тегов dns/etcd. Аннотация Kube-OVN находится в ресурсе Cluster, а не в KubeadmControlPlane, поскольку поставщик HCS отслеживает ее независимо от rollout плоскости управления Kubernetes.

#Процедура

1. Создайте новый HCSMachineTemplate для целевой версии Kubernetes

   Скопируйте существующий шаблон плоскости управления и примените его под новым metadata.name с целевым imageName:

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

   В new-cp-template.yaml:

   • Установите metadata.name в <new-template-name>.

   • Установите spec.template.spec.imageName в значение Alauda OS Image Version из целевой строки в Матрица поддержки ОС.

   • Удалите метаданные, сгенерированные сервером (resourceVersion, uid, generation, creationTimestamp, managedFields, annotation kubectl.kubernetes.io/last-applied-configuration), а также все поле status.

   • Не заполняйте поля идентичности времени выполнения, включая spec.template.spec.providerID и spec.template.spec.serverId. Поставщик HCS устанавливает providerID в hcs://<cluster-name>/<machine-name> и serverId в идентификатор экземпляра HCS ECS после создания VM; предварительное заполнение этих значений в шаблоне ломает привязку идентичности контроллером.

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

2. Примените исправление KubeadmControlPlane с целевыми значениями Kubernetes

   Обновите ресурс KubeadmControlPlane одной правкой, чтобы spec.version, тег образа CoreDNS, тег образа etcd и ссылка на инфраструктурный шаблон оставались согласованы с одним и тем же релизом Alauda OS:

   • spec.version ← Версия Kubernetes из строки OS Support Matrix

   • spec.kubeadmConfigSpec.clusterConfiguration.dns.imageTag ← столбец coredns из той же строки

   • spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.imageTag ← столбец etcd из той же строки

   • spec.machineTemplate.infrastructureRef.name ← имя нового HCSMachineTemplate, созданного на шаге 1

     kubectl edit kubeadmcontrolplane <kcp-name> -n cpaas-system

   Одного только обновления spec.version недостаточно. Теги образов CoreDNS и etcd должны обновляться вместе с версией Kubernetes, поскольку они собираются из одного и того же релиза Alauda OS; если оставить их на предыдущих значениях, это может привести к тому, что поды CoreDNS и etcd не будут соответствовать новой minor-версии Kubernetes.

   Сохраняйте spec.rolloutStrategy.rollingUpdate.maxSurge: 0, если связанный пул плоскости управления использует постоянные диски. Новый узел должен повторно использовать тот же фиксированный hostname и слот диска после удаления старого узла.

3. Обновите chart Kube-OVN на рабочем кластере

   Kube-OVN — это компонент жизненного цикла Core, но на immutable OS поставщик HCS не привязывает его версию chart к версии Kubernetes кластера. Версия chart хранится в отдельном AppRelease с именем cni-kube-ovn в namespace cpaas-system рабочего кластера, и вы переводите ее вперед в два шага: сначала обновляете аннотацию в ресурсе Cluster для учета и будущего пересоздания, затем напрямую изменяете существующий AppRelease, чтобы повысить revision chart.

   WARNING

   Почему на HCS требуются два шага

   Поставщик HCS создает AppRelease cni-kube-ovn в первый раз, когда кластер собирается, а затем синхронизирует только блок spec.values (имя кластера, CIDR, registry, список узлов плоскости управления). Он не записывает spec.source.charts[0].targetRevision в уже существующий AppRelease. В результате изменение cpaas.io/kube-ovn-version в ресурсе Cluster само по себе не меняет версию chart на рабочем кластере. Аннотацию по-прежнему необходимо обновить, чтобы зафиксированная целевая версия соответствовала строке OS Support Matrix, но само обновление chart выполняется через прямое исправление AppRelease.

   3.1. Обновите аннотацию cpaas.io/kube-ovn-version в ресурсе Cluster

   kubectl annotate cluster <cluster-name> -n cpaas-system \
     cpaas.io/kube-ovn-version=<kube-ovn-version-from-matrix> --overwrite

   Аннотация не обновляется автоматически при изменении spec.version; держите ее в соответствии со столбцом kube-ovn (chart) целевой строки.

   3.2. Измените revision chart AppRelease на рабочем кластере

   Выполняйте исправление на API server рабочего кластера (а не на bootstrap KIND и не на global-кластере):

   kubectl patch apprelease cni-kube-ovn -n cpaas-system --type='json' \
     -p='[{"op":"replace","path":"/spec/source/charts/0/targetRevision","value":"<kube-ovn-version-from-matrix>"}]'

   Используйте то же значение, которое вы указали в аннотации. releaseName (cpaas-kube-ovn) и name (acp/chart-cpaas-kube-ovn) управляются поставщиком; не изменяйте их.

   3.3. Дождитесь завершения синхронизации

   Отслеживайте фазу chart и установленный revision:

   # Overall AppRelease state — Sync and Health columns must reach a Success-equivalent reason
   kubectl get apprelease cni-kube-ovn -n cpaas-system
   
   # Installed revision and chart phase
   kubectl get apprelease cni-kube-ovn -n cpaas-system \
     -o jsonpath='Installed: {.status.charts.*.installedRevision}{"\n"}Phase: {.status.charts.*.phase}{"\n"}'

   Нормальная последовательность — Upgrading → HealthChecking → Success. На небольших кластерах полный переход обычно завершается примерно за одну минуту. Интерпретируйте фазы следующим образом:

   Фаза	Значение	installedRevision
   Upgrading	Идет обновление Helm release. Состояние Sync — Unknown(Syncing).	Пока предыдущая версия
   HealthChecking	Helm release применен; контроллер проверяет pod-ы Kube-OVN. Состояние Sync — True(Synced).	Уже целевая версия
   Success	Все три состояния (Validate, Sync, Health) равны True.	Целевая версия

   WARNING

   Не объявляйте обновление завершенным только по installedRevision. Это поле переключается на целевое значение во время HealthChecking, еще до того, как pod-ы будут подтверждены как Ready. Chart считается обновленным только тогда, когда phase равно Success и installedRevision совпадает с целевым значением.

   API AppRelease также определяет Downloading, Installing, Syncing, DownloadFailed, DeployFailed и NotReady. Первые три являются переходными, и обновление должно завершиться самостоятельно. Последние три указывают на сбой, который требует ручного анализа; начните с kubectl describe apprelease cni-kube-ovn -n cpaas-system, чтобы прочитать поле message для каждого состояния.

4. Проверьте ход обновления

   Отслеживайте процесс поэтапного обновления:

   # Check control plane status
   kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system
   
   # Monitor individual machines
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/control-plane
   
   # Verify cluster health
   kubectl get nodes

#Обновления рабочих узлов

Обновления рабочих узлов управляются через ресурсы MachineDeployment.

#Откат неудачного обновления

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

Перед откатом нужно усвоить три факта:

• Старых VM больше нет. Они были удалены во время обновления. Откат использует старый шаблон для создания нового набора заменяющих машин; он не восстанавливает исходные VM.
• Старый ресурс HCSMachineTemplate должен по-прежнему существовать. Не удаляйте предыдущий шаблон до тех пор, пока новый rollout не станет исправным. Если вы уже удалили его, восстановите его из системы контроля версий или резервной копии перед откатом.
• Только постоянные диски, управляемые пулом, сохраняют локальное состояние узла. Данные, записанные в HCSMachineTemplate.spec.template.spec.dataVolumes[] во время окна обновления, теряются при замене этой VM. Данные, записанные на диски, объявленные в HCSMachineConfigPool.spec.configs[].persistentDisks[], сохраняются и переподключаются к заменяющей VM. Данные приложений по-прежнему следует хранить во внешнем постоянном хранилище, таком как HCS EVS CSI, если только ваша операционная модель явно не зависит от локального состояния узла.

Процедура:

• Плоскость управления: измените KubeadmControlPlane, чтобы восстановить прежние значения spec.machineTemplate.infrastructureRef.name, spec.version, spec.kubeadmConfigSpec.clusterConfiguration.dns.imageTag и spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.imageTag.

• Рабочие узлы: измените каждый MachineDeployment, чтобы восстановить прежние значения spec.template.spec.infrastructureRef.name и spec.template.spec.version.

• Kube-OVN: если chart Kube-OVN был обновлен, откатите его тем же способом, которым выполнялось обновление: сначала восстановите аннотацию, затем верните revision chart в AppRelease. Проверьте результат тем же контролем installedRevision + phase=Success, который используется на шаге 3.

  kubectl annotate cluster <cluster-name> -n cpaas-system \
    cpaas.io/kube-ovn-version=<previous-kube-ovn-version> --overwrite
  
  kubectl patch apprelease cni-kube-ovn -n cpaas-system --type='json' \
    -p='[{"op":"replace","path":"/spec/source/charts/0/targetRevision","value":"<previous-kube-ovn-version>"}]'

Если новая плоскость управления так и не достигла quorum etcd, контроллер KubeadmControlPlane может отказаться откатывать какие-либо машины, поскольку его предварительные проверки блокируются из-за неисправного etcd. Сначала восстановите quorum etcd (вмешательство оператора), а затем повторите откат.

#Дополнительные ресурсы

• Документация по обновлению Cluster API
• Политика допустимого расхождения версий Kubernetes