Обновление Kubernetes с kubeadm на Ubuntu 22.04

Графика с логотипом Kubernetes

TL;DR

Кратко: определите точную версию (патч) для обновления, обновите kubeadm на контрол-плейне, создайте и примените план обновления, затем поочерёдно обновите worker и control-plane узлы. Держите пакеты в состоянии hold, делайте резервные копии и используйте kubeadm rollback или –force при проблемах. В статье есть пошаговый чеклист, runbook восстановления и рекомендации по тестированию.

Что в этой статье

Подготовка и предварительные требования
Как определить точную целевую версию
Обновление контрол-плейна: план и применение
Обновление рабочих узлов и повторная проверка
Процесс восстановления при сбое
Чеклисты, критерии приёмки и тест-кейсы
Альтернативные подходы, типичные ошибки и рекомендации по безопасности

Введение

kubeadm — официальное средство для установки и управления кластерами на стандартном дистрибутиве Kubernetes. Кластеры, созданные через kubeadm, не обновляются автоматически: в процессе установки часто отключают автоматические обновления пакетов для компонентов Kubernetes. Поэтому при выходе новой минорной версии вам придётся выполнить миграцию вручную.

В этой инструкции приводится детальный рабочий процесс для обновления кластера с версии v1.24 до v1.25 на Ubuntu 22.04. Для других минорных релизов процесс обычно схож, но всегда сверяйтесь с официальной документацией и заметками к релизу: иногда появляются специальные требования или шаги заранее.

Important: перед началом убедитесь, что у вас есть актуальные бэкапы etcd и манифестов, а также доступ к консоли контрол-плейна и рабочим узлам с правами sudo.

Краткие определения

kubeadm: инструмент для подготовки и управления Kubernetes-кластером.
control plane (контрол-плейн): набор компонентов API-сервера, контроллер-менеджера и планировщика.
worker node (рабочий узел): узел, выполняющий Pods и сервисы.
hold (apt-mark hold): блокировка пакета, чтобы apt не обновлял его автоматически.

Предварительные требования и рекомендации

Доступ к всем узлам кластера (SSH, sudo).
Локальная копия kubeconfig для выполнения kubectl команд с вашей машины или доступ с контрол-плейна.
Резервная копия etcd и статических манифестов Kubernetes (описано ниже).
Проверка совместимости версий ваших аддонов: CNI (Calico/Flannel/Weave), Ingress, CSI драйверы, CoreDNS.
План по поочерёдному обновлению узлов (обновление узла за узлом).
Наличие контроля нагрузки и мониторинга (Prometheus, Grafana) для быстрой диагностики.

Important: не перепрыгивайте через минорные версии. Переход v1.23 → v1.25 напрямую неподдерживаем.

Идентификация точной версии для установки

Первый шаг — определить целевую версию патч-релиза минорной версии, в которую вы будете обновляться. Нельзя пропускать минорные версии: например, переход прямо с v1.23 на v1.25 не поддерживается. Поэтому выберите последний патч для следующей минорной версии вашего текущего релиза.

Пример команды для поиска доступных версий в репозитории apt:

$ apt-cache policy kubeadm | grep 1.25

Вывод примера:

1.25.1-00 500

1.25.0-00 500

Это показывает, что 1.25.1-00 — самый свежий патч-римейк для v1.25. Замените 1.25 в команде на ту минорную версию, в которую вы хотите перейти.

Совет: запишите выбранные версии для kubeadm, kubelet и kubectl — они должны совпадать при установке.

Обновление контрол-плейна

Все шаги в этом разделе выполняйте на узле, где запущены компоненты контрол-плейна. Если у вас несколько контрол-плейн узлов, сначала сделайте полный цикл на одном, затем примените процедуру к остальным по очереди.

Обновите пакет kubeadm

Обновите индекс пакетов и снимите hold с kubeadm:

$ sudo apt update

$ sudo apt-mark unhold kubeadm

Установите точно ту версию kubeadm, которую вы выбрали (пример для v1.25.1):

$ sudo apt install -y kubeadm=1.25.1-00

Повторно установите hold, чтобы избежать нежелательных обновлений:

$ sudo apt-mark hold kubeadm

Пример подтверждения:

kubeadm set on hold

Проверьте версию kubeadm:

$ kubeadm version --short

Вы должны увидеть что-то вроде:

kubeadm version: &version.Info{Major:"1", Minor:"25", GitVersion:"v1.25.1"...

Примечание: если версия не совпадает с ожидаемой, повторите шаги или проверьте репозитории apt.

Создание плана обновления

kubeadm имеет встроенную команду планирования, которая проверяет кластер и подсказывает, какие изменения будут применены. Это важный диагностический шаг: он покажет, какие компоненты обновятся, и укажет, требуются ли ручные действия.

Запустите:

$ sudo kubeadm upgrade plan

Выход команды обычно длинный — внимательно просмотрите его. В первой секции вы должны увидеть таблицу с компонентами и их целевыми версиями. Новые версии для CoreDNS или etcd также могут быть показаны.

Пример (сокращённый):

COMPONENT CURRENT TARGET

kube-apiserver v1.24.5 v1.25.1

kube-controller-manager v1.24.5 v1.25.1

kube-scheduler v1.24.5 v1.25.1

kube-proxy v1.24.5 v1.25.1

CoreDNS v1.8.6 v1.9.3

etcd 3.5.3-0 3.5.4-0

Ниже обычно идет таблица, в которой показываются API-группы и указывается, требуется ли ручное вмешательство:

API GROUP CURRENT VERSION PREFERRED VERSION MANUAL UPGRADE REQUIRED

kubeproxy.config.k8s.io v1alpha1 v1alpha1 no

kubelet.config.k8s.io v1beta1 v1beta1 no

Если в колонке “Manual Upgrade Required” вы видите “yes”, изучите официальные заметки к релизу и подготовьте изменения в манифестах/конфигурациях.

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

Применение плана обновления

После проверки плана можно применить обновление контрол-плейна. Выполните на контрол-плейн узле:

$ sudo kubeadm upgrade apply v1.25.1

При запуске появится подтверждение:

[upgrade/version] You have chosen to change the cluster version to "v1.25.1"

[upgrade/versions] Cluster version: v1.24.5

[upgrade/versions] kubeadm version: v1.25.1

[upgrade] Are you sure you want to proceed? [y/N]:

Нажмите y, чтобы продолжить. Процесс может занимать несколько минут — kubeadm будет подтягивать новые образы и перезапускать компоненты контрол-плейна. API-сервер будет временно недоступен для постоянных запросов, но запущенные Pod’ы остаются работающими.

В конце вы должны увидеть сообщение об успешном обновлении:

[upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.25.1". Enjoy!]

В этом моменте контрол-плейн обновлён. Проверьте логи компонентов при необходимости (journalctl -u kubelet, docker/ containerd logs).

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

Теперь обновите worker-узлы. Эти действия также выполняются на контрол-плейн узлах при необходимости (в кластерах с HA — по очереди).

Обновляйте узлы по одному, чтобы минимизировать влияние на доступность: перед обновлением одного узла отклоняйте трафик и эвакуируйте Pod’ы.

Дрейн и cordon

Заблокируйте узел и эвакуируйте с него Pod’ы:

$ kubectl cordon node-1

$ kubectl drain node-1

Команда drain попытается удалить Pod’ы, учитывая DaemonSet и Pod disruption budgets. Если drain застревает, проверьте PDB и удерживающие Pod’ы.

Обновление пакетов kubeadm, kubelet, kubectl

Снимите hold с пакетов:

$ sudo apt update

$ sudo apt-mark unhold kubeadm kubectl kubelet

Установите точные версии для kubeadm, kubectl и kubelet (все три должны совпадать):

$ sudo apt install -y kubeadm=1.25.1-00 kubectl=1.25.1-00 kubelet=1.25.1-00

Верните hold:

$ sudo apt-mark hold kubeadm kubectl kubelet

Применение обновления конфигурации узла

Выполните на узле:

$ sudo kubeadm upgrade node

Эта команда обновит локальные конфигурации kubelet и обновит манифесты, если это необходимо.

Перезапуск kubelet и повторный ввод узла в кластер

После применения обновления перезагрузите daemon и kubelet, затем снимите cordon:

$ sudo systemctl daemon-reload

$ sudo systemctl restart kubelet

$ kubectl uncordon node-1

Проверьте, что узел вернулся в Ready-состояние и показывает ожидаемую версию.

Проверки после обновления

Используйте следующие команды для быстрой проверки:

$ kubectl version --short

Вы должны увидеть совпадение версий клиента и сервера (или ожидать версию сервера равной целевой).

Client Version: v1.25.1

...

Server Version: v1.25.1

Проверьте состояние узлов:

$ kubectl get nodes -o wide

Пример вывода:

NAME STATUS ROLES AGE VERSION

ubuntu22 Ready control-plane 70m v1.25.1

Проверьте также:

Статус CoreDNS: kubectl -n kube-system get deployment coredns
Состояние etcd (если self-hosted): проверка логов и объемов данных
Приложения и ingress: убедитесь, что сервисы доступны

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

Восстановление после неудачного обновления

Иногда обновление может завершиться неудачей, даже если kubeadm корректно спланировал процесс. Непрерывность может быть нарушена из-за прерываний, проблем с образами или неработающих компонентов. kubeadm пытается автоматически откатить изменения в случае фатальной ошибки.

Если обновление не удалось, можно повторно запустить ту же команду:

$ sudo kubeadm upgrade apply v1.25.1

kubeadm попытается выявить отличия в кластере и вернуть его в рабочее состояние или завершить обновление.

Если повторный запуск не помогает, можно попробовать форсировать процесс:

$ kubeadm upgrade apply --force

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

Ручное восстановление из бэкапа kubeadm

При серьёзном разрушении кластера kubeadm пишет локальные резервные копии, которые можно использовать для восстановления:

Скопируйте содержимое /etc/kubernetes/tmp/kubeadm-backup-etcd-- в директорию /var/lib/etcd.
Скопируйте содержимое /etc/kubernetes/tmp/kubeadm-backup-manifests-- в директорию /etc/kubernetes/manifests.

После восстановления файлов перезапустите etcd и kubelet, чтобы вернуть контрол-плейн в предыдущее рабочее состояние.

Важно: при восстановлении вручную убедитесь, что версии бинарников соответствуют содержимому манифестов и резервных копий.

Чеклист администратора (шаблон)

Перед обновлением:

Сделать snapshot/backup etcd
Сохранить статические манифесты /etc/kubernetes/manifests
Проверить совместимость аддонов (CNI, Ingress, CSI)
Проверить наличие свободной ёмкости в кластере для перезапуска Pod’ов
План обновления узлов и окно обслуживания

Во время обновления:

Установить нужную версию kubeadm
Запустить kubeadm upgrade plan и внимательно прочитать вывод
Применить kubeadm upgrade apply на контрол-плейн
Поочерёдно cordon/drain и обновить рабочие узлы
Проверить состояние кластерных компонентов после каждого узла

После обновления:

Проверить kubectl version и kubectl get nodes
Проверить логи kubelet и kube-apiserver
Протестировать критичные приложения
Отправить уведомление командам о завершении

Критерии приёмки

Все контрол-плейн поды обновлены и имеют статус Ready/Running.
Все узлы в кластере показывают целевую версию (kubectl get nodes).
Критичные сервисы (Ingress, DB, приложения) успешно проходят smoke-тесты.
Отсутствие долгосрочных CrashLoopBackOff или Failures в журнальных логах.
Мониторинг не показывает серьёзных регрессий в latency/availability.

Тест-кейсы и сценарии приёма

Smoke-test: GET /healthz на каждом сервисе — ожидаемый HTTP 200.
Нагрузочный тест на критичный путь (короткий burst) — ожидание, что задержки не увеличиваются более чем на X% (определяется соглашением команды).
Восстановление Pod после удаления: создать и удалить pod; убедиться, что Deployment/ReplicaSet восстанавливает экземпляры.
Тесты PDB: симулировать обновление и проверить, что PDB не блокирует критичный аппгрейд.

Note: Величины для SLA/роста латентности задавайте исходя из ваших договорённостей — не придумывайте значения здесь.

Частые ошибки и способы их устранения

Проблема: kubeadm план не выполняется или выдаёт ошибку “unsupported upgrade path”. Решение: проверьте, что выбранная версия kubeadm соответствует следующему минорному релизу; обновите kubeadm до версии, поддерживающей целевой минор.
Проблема: drain зависает из-за PodDisruptionBudget. Решение: временно уменьшите PDB, удалите проблемные Pod’ы вручную или переконфигурируйте стратегию обновления.
Проблема: узел не возвращается в Ready после обновления kubelet. Решение: проверьте логи kubelet (journalctl -u kubelet), убедитесь в версии контейнерного рантайма (containerd/docker) и соответствующих конфигурациях.
Проблема: аддоны (CNI, CSI) не совместимы с новой версией. Решение: обновите аддоны по их документации перед обновлением kubeadm/kubelet.

Альтернативные подходы

Управляемые Kubernetes-сервисы (EKS/GKE/AKS): они управляют процессом обновления сами, что уменьшает операционные обязанности.
kops/eksctl/other provisioning tools: эти инструменты часто имеют собственные рекомендованные пути апгрейда.
Канареечные обновления с использованием blue/green топологий: для критичных production сред применяют стратегии с постепенным переключением трафика.

Выбор зависит от ваших требований по availability, масштабу и регламентам безопасности.

Ментальные модели и эвристики

«Один узел — один этап»: обновляйте по одному узлу и тестируйте после каждого шага.
«План — затем применяй»: всегда выполняйте kubeadm upgrade plan и внимательно читайте вывод.
«Совместимость аддонов прежде версии»: аддоны часто являются слабым звеном при обновлениях.

Runbook восстановления (инцидент)

Оцените масштаб: один узел или весь контрол-плейн.
Снимите нагрузку с проблемных узлов: cordon, drain (если возможно).
Попытайтесь повторно применить kubeadm upgrade apply той же версии.
Если не помогает — попробуйте kubeadm upgrade apply –force.
При полной потере контрол-плейна восстановите файлы из /etc/kubernetes/tmp/kubeadm-backup-* в /var/lib/etcd и /etc/kubernetes/manifests.
Перезапустите etcd и kubelet, проверьте статус контрол-плейна.
Документируйте последовательность, причину и меры по предотвращению в следующий раз.

Риски и смягчающие меры

Риск: несовместимость аддонов → Смягчение: тестовый стенд и проверка совместимости заранее.
Риск: потеря etcd → Смягчение: регулярные snapshot’ы и off-site резервирование.
Риск: отсутствие свободной емкости для перезапуска Pod’ов → Смягчение: добавьте временные узлы или используйте консервативный PDB.

Безопасность и конфиденциальность

Сохраняйте kubeconfig и секреты в защищённом хранилище.
Ограничьте доступ SSH к узлам. Включите аудит и логирование.
При восстановлении убедитесь, что разрешения на каталоги etcd и манифесты корректны.

Совместимость и миграционные советы для Ubuntu 22.04

Убедитесь, что версия containerd или Docker поддерживается выбранной версией kubelet.
Проверяйте зависимости пакетов и репозиторий apt для Kubernetes — используйте официальные репозитории.
Если у вас специфичные системные настройки (cgroup v2), проверьте совместимость с kubelet и runtime.

Примеры команд — сводка (cheat sheet)

Примерный набор команд, собранный в одном месте:

sudo apt update
sudo apt-mark unhold kubeadm
sudo apt install -y kubeadm=1.25.1-00
sudo apt-mark hold kubeadm
kubeadm version --short
sudo kubeadm upgrade plan
sudo kubeadm upgrade apply v1.25.1
kubectl cordon node-1
kubectl drain node-1
sudo apt-mark unhold kubeadm kubectl kubelet
sudo apt install -y kubeadm=1.25.1-00 kubectl=1.25.1-00 kubelet=1.25.1-00
sudo apt-mark hold kubeadm kubectl kubelet
sudo kubeadm upgrade node
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl uncordon node-1
kubectl version --short
kubectl get nodes -o wide

Модель зрелости процесса обновлений (high-level)

Ручные обновления без резервирования — низкая зрелость.
Скрипты и чеклисты, регулярные бэкапы — средняя зрелость.
Автоматизированные пайплайны, канареечные релизы, тесты в CI — высокая зрелость.

Переходите на следующий уровень, внедряя автоматизацию и тестирование.

Что делать, если хочется пропустить ручную работу

Рассмотрите управление кластером через облачный managed Kubernetes (EKS/GKE/AKS) или инструменты автоматизации инфраструктуры (Terraform + провайдеры, системы CI/CD), которые уменьшают ручную операционную нагрузку.

Итог и рекомендации

Обновление Kubernetes с помощью kubeadm — это контролируемый и предсказуемый процесс при наличии хорошей подготовки: точные версии, резервные копии, проверка аддонов и пошаговый чеклист. Начинайте с тестовой среды, держите коммуникацию с командами, имейте план отката и runbook на случай инцидента.

Короткие рекомендации:

Всегда выполняйте kubeadm upgrade plan перед применением.
Подбирайте точный патч-релиз и держите пакеты в hold.
Обновляйте узлы по одному.
Делайте резервные копии etcd и манифестов до начала процесса.

Краткое резюме в конце: планирование, проверка совместимости аддонов, резервное копирование и поочерёдное обновление узлов — ключи к безопасному и предсказуемому апгрейду Kubernetes с kubeadm.

Обновление Kubernetes с помощью kubeadm на Ubuntu 22.04: переход с v1.24 на v1.25