#Обновление Kubernetes на Huawei DCS

Это руководство объясняет, как завершить Phase 2 рабочего процесса обновления для кластеров на Huawei DCS. Перед обновлением Kubernetes выполните обновление Distribution Version, описанное в Обновление кластеров.

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

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

1. (Обязательное условие) Сначала обновите платформу ACP на management-кластере. Это приведет к обновлению контроллера cluster-api-provider-dcs и связанных компонентов CAPI (core, провайдер KubeadmControlPlane, bootstrap-провайдер) до версий, которые понимают новую schema. Запускайте обновление workload-кластера только после того, как контроллеры на стороне management-кластера завершат раскатку и перейдут в состояние Ready.
2. Обновите Distribution Version (Aligned Extensions) на workload-кластере. См. Обновление Distribution Version.
3. Обновите Kubernetes control plane.
4. Обновите worker nodes до целевой версии Kubernetes.

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

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

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

• Обновление Distribution Version завершено
• Control plane доступен
• Все узлы находятся в состоянии Ready и исправны
• IP Pool имеет достаточную емкость для rolling updates
• VM-шаблон поддерживает целевую версию Kubernetes. См. Матрица поддержки ОС для сопоставления версий
• Для кросс-версийных обновлений, охватывающих более одного minor-обновления Kubernetes, промежуточные версии Core images и VM-шаблоны заранее подготовлены. См. Подготовка к кросс-версийному обновлению
• Целевая версия Kubernetes совместима с вашими workload и add-ons
• VM-шаблоны DCS имеют версию 4.2.1 или новее, если вы используете persistent disks, управляемые pool, поскольку безопасное завершение работы и отсоединение дисков зависят от guest tools
• Если вы используете persistent disks, управляемые pool, сохраняйте KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge = 0 и для каждого MachineDeployment.spec.strategy.rollingUpdate.maxSurge = 0
• Если кластер использует дополнительные NIC, сохраняйте необходимые записи DCSIpHostnamePool.spec.pool[].additionNic[] и убедитесь, что DCS DVS и Port Groups доступны с хостов, которые могут получить replacement VMs

#Использование YAML

Обновления на основе YAML не зависят от Fleet Essentials.

#Требуемые значения из OS Support Matrix

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

Значения из этой строки используются в manifest обновления следующим образом:

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

Подтвердите у владельца платформы кластера, что целевой образ Alauda OS уже загружен в платформу DCS под тем же именем, что и значение Alauda OS Image Version в строке матрицы. Обновление завершится ошибкой, если этот VM-шаблон отсутствует в DCS в момент применения DCSMachineTemplate.

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

Обновление шаблона машин control plane позволяет раскатить обновленные спецификации VM, системные патчи и параметры инфраструктуры.

#Процедура

1. Создайте обновленный machine template

   Скопируйте существующий DCSMachineTemplate, на который ссылается KubeadmControlPlane, и сохраните его в новый файл:

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

2. Измените спецификацию template

   Обновите новый template по мере необходимости:

   • Установите metadata.name в <new-template-name>
   • Обновите spec.template.spec.vmTemplateName
   • Обновите spec.template.spec.vmConfig.dcsMachineCpuSpec.quantity
   • Обновите spec.template.spec.vmConfig.dcsMachineMemorySpec.quantity
   • Обновите spec.template.spec.vmConfig.dcsMachineDiskSpec только для системных дисков и локальных для template дисков
   • Удалите сгенерированные сервером метаданные (resourceVersion, uid, generation, creationTimestamp, managedFields, annotation kubectl.kubernetes.io/last-applied-configuration) и все поле status из скопированного manifest.
   • Оставьте spec.template.spec.providerID пустым. Провайдер DCS устанавливает providerID в dcs://<machine-name> после создания VM; предварительное заполнение этого поля в template нарушает привязку идентичности контроллера.

   Храните persistent disks, управляемые pool, включая /var/cpaas, в DCSIpHostnamePool.spec.pool[].persistentDisk. Дополнительные NIC храните в DCSIpHostnamePool.spec.pool[].additionNic[].

3. Примените обновленный template

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

4. Обновите ссылку control plane

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

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

5. Контролируйте rolling update

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

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

Обновление версии Kubernetes control plane на immutable OS — это рабочий процесс delete-recreate. VM control plane заменяются по одной из нового DCSMachineTemplate, который указывает на целевой VM-шаблон Alauda OS, а ресурс KubeadmControlPlane патчится, чтобы использовать соответствующие версию Kubernetes, тег образа CoreDNS и тег образа etcd.

Перед началом соберите все необходимые значения из целевой строки ACP в OS Support Matrix, как описано в Требуемые значения из OS Support Matrix.

#Процедура

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

   Скопируйте существующий template control plane и обновите metadata.name на новое имя, а spec.template.spec.vmTemplateName — на значение Alauda OS Image Version, взятое из целевой строки в Матрица поддержки ОС. Храните persistent disks, управляемые pool, в DCSIpHostnamePool.spec.pool[].persistentDisk, а дополнительные NIC — в DCSIpHostnamePool.spec.pool[].additionNic[], вместо того чтобы повторно задавать их как поля template.

   kubectl get dcsmachinetemplate <current-cp-template-name> -n cpaas-system -o yaml > new-cp-template.yaml
   # edit metadata.name and spec.template.spec.vmTemplateName
   kubectl apply -f new-cp-template.yaml -n cpaas-system

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

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

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

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

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

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

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

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

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

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

   WARNING

   Почему на DCS нужны два шага

   Провайдер DCS создает AppRelease cni-kube-ovn при первом создании кластера, и после этого он синхронизирует только блок spec.values (имя кластера, CIDR, registry, список control-plane node). Он не записывает spec.source.charts[0].targetRevision в уже существующий AppRelease. В результате изменение cpaas.io/kube-ovn-version только на ресурсе Cluster не меняет версию chart на workload-кластере. Аннотацию все равно необходимо обновить, чтобы зафиксированная целевая версия соответствовала строке 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 на workload-кластере

   Выполняйте патч против API server workload-кластера, а не 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. Дождитесь завершения reconciliation

   Отслеживайте phase 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. На небольших кластерах полный переход обычно завершается примерно за одну минуту. Интерпретируйте phase следующим образом:

   Phase	Значение	installedRevision
   Upgrading	Выполняется upgrade Helm release. Condition Sync имеет значение Unknown(Syncing).	Все еще предыдущая версия
   HealthChecking	Helm release применен; контроллер проверяет pods Kube-OVN. Condition Sync = True(Synced).	Уже целевая версия
   Success	Все три condition (Validate, Sync, Health) имеют значение True.	Целевая версия

   WARNING

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

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

4. Контролируйте rolling update

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

   KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge должен оставаться 0, когда кластер использует persistent disks, управляемые pool, чтобы VM control plane заменялись по одной.

#Обновление worker nodes

Обновления Kubernetes для worker nodes управляются через ресурсы MachineDeployment. Для worker-обновлений требуется меньше полей, чем для control plane: теги образов CoreDNS и etcd находятся в KubeadmControlPlane.spec.kubeadmConfigSpec.clusterConfiguration, которого у MachineDeployment нет. Worker nodes наследуют версии компонентов Kubernetes из нового VM-шаблона; MachineDeployment нужен только целевой версии Kubernetes и ссылка на новый template.

Перед началом прочитайте ячейки Alauda OS Image Version и Kubernetes Version из целевой строки ACP в Матрица поддержки ОС, как описано в Требуемые значения из OS Support Matrix.

#Процедура

1. Создайте новый DCSMachineTemplate для worker nodes

   • Создайте новый DCSMachineTemplate с vmTemplateName, установленным в значение Alauda OS Image Version из целевой строки в Матрица поддержки ОС
   • Храните /var/cpaas и любые другие диски, сохраняемые при обновлении, в DCSIpHostnamePool.spec.pool[].persistentDisk, а не добавляйте их снова как диски template
   • Храните дополнительные NIC в DCSIpHostnamePool.spec.pool[].additionNic[]

2. Обновите MachineDeployment

   • Установите spec.template.spec.version в значение Kubernetes Version из той же строки OS Support Matrix
   • Установите spec.template.spec.infrastructureRef.name в имя нового DCSMachineTemplate, созданного на шаге 1
   • При необходимости обновите spec.template.spec.bootstrap.configRef.name, если для этого релиза требуется изменение bootstrap-конфигурации

3. Контролируйте rolling update

   • Убедитесь, что rolling update успешно завершен
   • Убедитесь, что новые worker nodes присоединились к кластеру с целевой версией Kubernetes

   MachineDeployment.spec.strategy.rollingUpdate.maxSurge должен оставаться 0, когда кластер использует persistent disks, управляемые pool, чтобы worker nodes заменялись по одной.

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

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

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

• Старых VMs больше нет. Они были уничтожены во время обновления. Rollback использует старый template для создания нового набора replacement machines; он не восстанавливает исходные VMs.
• Старый ресурс DCSMachineTemplate должен все еще существовать. Не удаляйте предыдущий template, пока новая раскатка не станет healthy. Если вы уже удалили его, восстановите его из системы контроля версий или резервной копии перед откатом.
• Идентичность диска, управляемого pool, сохраняется, но состояние данных — нет. Диски, объявленные в DCSIpHostnamePool.spec.pool[].persistentDisk, повторно присоединяются к откатываемым машинам в том же IP-слоте, но любые данные, записанные на эти диски в течение окна обновления (например, записи etcd в новом формате minor-версии Kubernetes), сохраняются. Если новый формат не читается более старой minor-версией Kubernetes, rollback все равно может завершиться неудачно и потребовать ручного восстановления etcd.

Процедура:

• Control plane: пропатчите KubeadmControlPlane, чтобы восстановить прежние spec.machineTemplate.infrastructureRef.name, spec.version, spec.kubeadmConfigSpec.clusterConfiguration.dns.imageTag и spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.imageTag.

• Workers: пропатчите каждый 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>"}]'

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

---

#Использование Web UI

Используйте этот workflow для обновления Kubernetes из web UI после завершения Phase 1.

Требование к версии: Этот workflow требует Fleet Essentials и Alauda Container Platform DCS Infrastructure Provider 1.0.13 или новее. Если версия провайдера ниже 1.0.13, используйте YAML manifest. Если обновление опирается на persistent disks, управляемые pool, используйте провайдер DCS v1.0.16 или новее. В v1.0.16 объявление persistentDisk на DCSIpHostnamePool по-прежнему доступно только через YAML и не отображается в web UI.

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

• Обновление Distribution Version завершено. См. Обновление Distribution Version
• Control Plane Node Pool находится в состоянии Running
• IP Pool имеет достаточную емкость для rolling updates
• Если обновление опирается на persistent disks, управляемые pool, убедитесь, что необходимые записи DCSIpHostnamePool.spec.pool[].persistentDisk уже созданы или обновлены через YAML

#Рабочий процесс обновления

Обновления Kubernetes следуют такой последовательности после обновления Distribution Version:

1. Обновите Control Plane Node Pool.
2. Дождитесь завершения обновления Control Plane Node Pool.
3. Обновите Worker Node Pools в любом порядке.

#Проверка доступных обновлений

Навигация: Clusters → Clusters → Выберите кластер → Вкладка Node Pools

Node Pools, для которых доступны обновления, отображают индикатор Upgrade available. Нажмите на карточку Node Pool, чтобы посмотреть текущую и целевую версии.

#Обновление Control Plane Node Pool

Шаги:

1. На вкладке Node Pools найдите Control Plane Node Pool
2. Нажмите Upgrade
3. Проверьте информацию об обновлении:
   • Current Version: текущая версия Kubernetes
   • Target Version: последняя поддерживаемая minor-версия (выбирается автоматически)
4. Нажмите Confirm, чтобы начать

Мониторинг:

• Следите за состоянием Node Pool
• Узлы будут обновляться по одному (maxSurge=0). Такая замена по одному также обязательна, когда кластер использует persistent disks.
• Время обновления зависит от количества узлов и ресурсов

#Обновление Worker Node Pools

Когда доступно обновление Worker Pool:

• Версия Kubernetes control plane совпадает с версией global-кластера
• Control Plane находится в состоянии Running

Шаги обновления:

1. Для каждого Worker Node Pool:
   • Нажмите кнопку Upgrade
   • Проверьте и подтвердите
2. После завершения обновления Control Plane пулы можно обновлять параллельно

Ограничения обновления:

#Устранение неполадок

---

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

• Миграция существующих кластеров Huawei DCS на persistent disks, управляемые pool
• Документация по обновлению Cluster API
• Политика расхождения версий Kubernetes