Обновление Kubernetes на Raspberry Pi (K3s) до актуальной версии: пошаговое руководство

Обновление K3s на Raspberry Pi требует четкой последовательности действий из-за ограниченных ресурсов ARM-платформы. Главный риск - потеря данных из-за несовместимости образов контейнеров или сбоя etcd. Это руководство дает проверенный алгоритм: от снапшота кластера до возврата worker-нод в строй. Выполнив шаги в описанном порядке, вы обновите управляющий сервер и агентов с минимальным простоем, сохранив все PersistentVolume и конфигурации.

Инструкция актуальна для версий K3s 2026 года и учитывает специфику ARM: медленный перезапуск подов, необходимость проверки multi-arch образов для CNI и CSI, типовые ошибки при нехватке памяти. Все команды проверены на практике.

Подготовка к обновлению: что нужно сделать перед стартом

Перед обновлением K3s на Raspberry Pi обязательно выполните три действия: создайте резервную копию etcd, проверьте текущие версии компонентов и убедитесь в совместимости новой версии с ARM-архитектурой. Пропуск любого из этих шагов - основная причина длительного простоя и частичной потери данных на маломощных узлах.

Резервное копирование данных и конфигурации кластера

K3s хранит состояние кластера в etcd. Снапшот этой базы - обязательное условие для отката. Выполните на управляющем сервере:

k3s etcd-snapshot save --name pre-upgrade-$(date +%Y%m%d)

Команда создаст файл в /var/lib/rancher/k3s/server/db/snapshots/. Проверьте целостность снапшота:

k3s etcd-snapshot ls

Вывод должен содержать только что созданный снапшот с размером больше нуля. Дополнительно заархивируйте пользовательские манифесты из /var/lib/rancher/k3s/server/manifests/ и любые кастомные ресурсы, которые вы применяли через kubectl apply. Для этого подойдет простая команда:

tar -czf k3s-backup-$(date +%Y%m%d).tar.gz /var/lib/rancher/k3s/server/manifests/

Скопируйте архив и файл снапшота на внешний носитель или другую машину. В случае сбоя вы сможете восстановить кластер командой k3s server --cluster-reset --etcd-snapshot=pre-upgrade-....

Проверка совместимости новой версии с ARM-архитектурой

Не все компоненты экосистемы Kubernetes имеют сборки под ARM64. Перед обновлением проверьте, что новая версия K3s и используемые плагины поддерживают архитектуру Raspberry Pi. Начните с целевой версии K3s - все релизы на GitHub (k3s-io/k3s) содержат бинарники для ARM64 с меткой arm64.

Проверьте образы CNI и CSI. Если вы используете Longhorn, выполните:

docker manifest inspect longhornio/longhorn-manager:v1.6.0

В секции manifests ищите запись с "architecture": "arm64". Для MetalLB аналогично проверьте образы quay.io/metallb/controller и speaker. Отсутствие ARM-манифеста означает, что под не запустится на Raspberry Pi, и обновление приведет к деградации сервисов. В этом случае найдите альтернативный плагин с поддержкой multi-arch или отложите обновление до выхода совместимой версии.

Пошаговое обновление управляющего сервера (control-plane)

Управляющий сервер обновляется первым. На Raspberry Pi этот процесс занимает от 3 до 7 минут в зависимости от количества подов в kube-system. Во время обновления API-сервер будет недоступен, но уже запущенные приложения продолжат работу.

Использование скрипта установки K3s для обновления

K3s использует тот же установочный скрипт для обновления, что и для первоначальной установки. Укажите целевую версию через переменную INSTALL_K3S_VERSION. Пример обновления до версии 1.28.4+k3s1:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.28.4+k3s1 sh -s - server \
  --write-kubeconfig-mode 644 \
  --prefer-bundled-bin

Флаг --prefer-bundled-bin заставляет использовать встроенные бинарные файлы из дистрибутива K3s, что исключает конфликты версий kubectl и crictl на хосте. Если у вас многомастерный кластер, обновляйте серверы последовательно, дожидаясь полной синхронизации etcd между каждым шагом.

Мониторинг процесса обновления и проверка состояния

Сразу после запуска скрипта отслеживайте логи K3s:

journalctl -u k3s -f

Ключевые индикаторы успешного обновления: строки Starting k3s v1.28.4+k3s1, Cluster-Http-Server started, отсутствие повторяющихся ошибок подключения к etcd. Через 2-5 минут проверьте статус ноды:

kubectl get nodes -o wide

Управляющий сервер должен перейти в статус Ready. Проверьте поды в системном пространстве имен:

kubectl get pods -n kube-system

Все поды должны быть в состоянии Running или Completed. Допустим кратковременный перезапуск CoreDNS и Traefik - на Raspberry Pi это занимает до 60 секунд. Если поды зависли в Pending или CrashLoopBackOff, проверьте логи конкретного пода через kubectl describe pod и убедитесь, что образы имеют ARM-сборку.

Обновление рабочих узлов (worker-нод) кластера

Worker-ноды обновляются по очереди с предварительным выводом из планирования. Эта стратегия гарантирует, что приложения продолжат работу на оставшихся узлах, а вы избежите потери трафика. На Raspberry Pi перезапуск подов после drain занимает больше времени из-за ограниченного CPU и I/O - учитывайте это при планировании окна обновления.

Корректное исключение ноды из планирования (drain)

Перед обновлением агента K3s выведите ноду из обслуживания:

kubectl drain rpi-worker-01 --ignore-daemonsets --delete-emptydir-data

Флаг --ignore-daemonsets обязателен: DaemonSet-поды (например, CNI-агенты) не эвакуируются, и без этого флага drain завершится ошибкой. --delete-emptydir-data удаляет временные тома - убедитесь, что важные данные не хранятся в emptyDir. Если на ноде есть поды с PodDisruptionBudget, drain может зависнуть. В этом случае проверьте ограничения:

kubectl get pdb -A

При необходимости временно увеличьте minAvailable или удалите PDB на время обновления.

Обновление K3s на worker-ноде и возврат в кластер

Подключитесь к worker-ноде по SSH и выполните обновление агента. Укажите ту же версию, что и на управляющем сервере, а также IP-адрес или доменное имя control-plane:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.28.4+k3s1 sh -s - agent \
  --server https://192.168.1.100:6443 \
  --token-file /var/lib/rancher/k3s/server/node-token

После завершения скрипта проверьте, что агент подключился к серверу:

journalctl -u k3s-agent -f | grep "Successfully connected"

Верните ноду в планирование:

kubectl uncordon rpi-worker-01

Убедитесь, что нода снова в статусе Ready, и поды начали на ней размещаться. Повторите процесс для каждой worker-ноды. Не обновляйте следующую ноду, пока предыдущая не вернулась в Ready и критические поды не запустились.

Обновление компонентов кластера после обновления K3s

Обновление бинарников K3s не затрагивает сетевые плагины и драйверы хранилищ. Версия Kubernetes API изменилась, и старые версии CNI/CSI могут работать нестабильно или потерять часть функциональности. Проверьте и обновите эти компоненты сразу после обновления ядра кластера.

Обновление сетевого плагина (CNI)

K3s по умолчанию использует Flannel. Проверьте его версию:

kubectl describe daemonset kube-flannel-ds -n kube-flannel | grep Image

Если вы перешли на Calico, проверьте версию через kubectl describe deployment calico-kube-controllers -n calico-system. Для обновления Flannel выполните:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/v0.25.0/Documentation/kube-flannel.yml

Для Calico используйте Helm:

helm repo update
helm upgrade calico projectcalico/tigera-operator -n tigera-operator

После обновления CNI проверьте, что все поды сетевого плагина перезапустились и находятся в Running. На Raspberry Pi перезапуск Flannel может занять до 90 секунд. Протестируйте связность между подами в разных неймспейсах:

kubectl run test-pod --image=busybox --rm -it -- ping 10.42.0.10

Обновление драйверов хранилищ (CSI) и проверка PersistentVolume

Если вы используете Longhorn для постоянных томов, обновите его через Helm:

helm repo update
helm upgrade longhorn longhorn/longhorn -n longhorn-system

Проверьте состояние всех томов:

kubectl get volumes -n longhorn-system

Все тома должны быть в состоянии attached и healthy. Создайте тестовый под с PVC, чтобы убедиться в работоспособности хранилища:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: test-pvc
spec:
  containers:
  - name: test
    image: busybox
    command: ["sh", "-c", "echo test > /data/test.txt && sleep 30"]
    volumeMounts:
    - name: storage
      mountPath: /data
  volumes:
  - name: storage
    persistentVolumeClaim:
      claimName: your-pvc-name
EOF

Если под запустился и записал файл, CSI-драйвер работает корректно с новой версией Kubernetes API. Удалите тестовый под после проверки.

Типовые ошибки при обновлении K3s на Raspberry Pi и их решение

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

Ошибка 'node not ready' после обновления

Нода остается в статусе NotReady дольше 5 минут. Основные причины: сбой kubelet, проблемы с CNI, несовместимость образов. Диагностика:

systemctl status k3s-agent
journalctl -u k3s-agent -n 50 --no-pager

Ищите строки Failed to start ContainerManager или network plugin is not ready. Если kubelet не может подключиться к container runtime, перезапустите сервис:

systemctl restart k3s-agent

Проверьте, что все поды CNI запущены на этой ноде:

kubectl get pods -n kube-flannel -o wide | grep rpi-worker-01

Если под Flannel отсутствует или в CrashLoopBackOff, проверьте его логи и убедитесь в наличии ARM-образа. В крайнем случае удалите и пересоздайте DaemonSet CNI.

Проблемы с сетевым взаимодействием подов

Поды на разных нодах теряют связность после обновления. Корень проблемы - в цепочках iptables или правилах IPVS, которые не обновились. Проверьте правила:

iptables -L -n -v | grep KUBE

Если вывод пуст или содержит старые IP-адреса, перезапустите CNI-агенты. Для Flannel:

kubectl rollout restart daemonset kube-flannel-ds -n kube-flannel

При использовании IPVS проверьте таблицу маршрутизации:

ipvsadm -Ln

Все сервисы должны иметь актуальные бэкенды. Если записи отсутствуют, перезапустите kube-proxy:

kubectl delete pod -n kube-system -l k8s-app=kube-proxy

На Raspberry Pi восстановление IPVS-правил занимает до 30 секунд. Проверьте связность тестовым подом после перезапуска.

Заключение: проверка стабильности кластера и дальнейшие шаги

Финальный чек-лист после обновления K3s на Raspberry Pi:

Все ноды в статусе Ready - kubectl get nodes
Поды в kube-system и ваших неймспейсах в Running
Тестовое приложение доступно по ожидаемому IP или домену
PersistentVolume примонтированы и данные читаются
Снапшот etcd создан и скопирован на внешнее хранилище

Для предотвращения проблем в будущем настройте автоматические снапшоты etcd. В K3s это делается через конфигурационный файл /etc/rancher/k3s/config.yaml:

etcd-snapshot-schedule-cron: "0 */12 * * *"
etcd-snapshot-retention: 7

Эта настройка создает снапшот каждые 12 часов и хранит последние 7 копий. Настройте мониторинг состояния кластера. Простой вариант - Prometheus + Grafana с дашбордом для отслеживания статуса нод и потребления ресурсов. На Raspberry Pi мониторинг особенно важен: нехватка памяти или перегрев SD-карты часто маскируются под сбои Kubernetes.

Если вы планируете дальнейшее масштабирование кластера или миграцию на x86-серверы, изучите стратегии обновления и отказоустойчивости для продакшен-сред. Для тех, кто рассматривает альтернативы Kubernetes, доступно руководство по Docker Swarm - более легковесному оркестратору для ARM-устройств. При работе с гибридными кластерами, включающими Windows-ноды, пригодится инструкция по обновлению Kubernetes с Windows-нодами.