Советы и решение типовых проблем

Шаг 1. Спросите кластер, что случилось

kubectl describe node k8s-node1

Листайте до раздела Conditions — там список состояний узла. Ищите условие, которое не в порядке:

Там же, внизу вывода, раздел Events — последние события узла, часто прямо называющие виновника.

Шаг 2. Посмотрите журналы на самом узле

Зайдите по SSH на проблемную машину и проверьте главного агента:

# k3s (сервер или агент):
sudo journalctl -u k3s -n 100 --no-pager
sudo journalctl -u k3s-agent -n 100 --no-pager

# kubeadm (kubelet):
sudo journalctl -u kubelet -n 100 --no-pager

# следить в реальном времени:
sudo journalctl -u k3s -f

Частые строки и их значения:

• container runtime is down — упал containerd: sudo systemctl status containerd;
• failed to load Kubelet config file или ругань на swap — вернитесь к инструкции «Подготовка», проверьте swapon --show;
• таймауты к apiserver — проверьте сеть: ping control-plane, правильность IP и токена (в k3s — /etc/rancher/k3s/).

Шаг 3. Проверьте системные поды сети

Если kubelet жив, но поды не стартуют — часто виноват CNI:

# flannel (kubeadm):
kubectl get pods -n kube-flannel

# логи проблемного пода flannel:
kubectl logs -n kube-flannel имя-пода

Шаг 4. Найдите, кто ест память

# потребление по подам (нужен metrics-server; в k3s встроен)
kubectl top nodes
kubectl top pods -A --sort-by=memory

# почему перезапустился конкретный под
kubectl describe pod имя-пода | grep -A3 "Last State"
# Reason: OOMKilled — ядро убило процесс за превышение лимита

Шаг 5. Разберитесь с requests и limits

Ключ к стабильности — правильные значения у каждого контейнера:

• requests — сколько памяти гарантированно зарезервировано за подом. Планировщик не разместит под на узле, если свободных requests там меньше, чем просит под. Занижать requests «чтобы влезло» — откладывать проблему.
• limits — потолок. Превысил — получил OOMKilled и перезапуск.

Практический подход: запустите приложение без жёстких ограничений, дайте поработать пару дней, посмотрите реальное потребление (kubectl top pods) и выставьте requests чуть выше среднего, limits — выше пикового. Для домашних сервисов ориентиры есть в таблице на странице «Требования».

Шаг 6. Почистите «зависшие» Evicted-поды

Evicted-поды не удаляются сами и засоряют вывод:

# найти все Evicted во всех namespace
kubectl get pods -A --field-selector=status.phase=Failed

# удалить их разом
kubectl delete pods -A --field-selector=status.phase=Failed

Шаг 7. Найдите, что заняло место

# общая картина
df -h

# самые тяжёлые каталоги (обычно /var/lib — образы, тома, etcd)
sudo du -h -d1 /var/lib 2>/dev/null | sort -rh | head
sudo du -h -d1 /var/lib/rancher 2>/dev/null | sort -rh | head   # для k3s

Типовые «толстяки» в домашнем кластере:

• Образы контейнеров — каждый образ сотни мегабайт, а их копятся десятки версий;
• Логи контейнеров — болтливое приложение пишет гигабайты в /var/log/pods;
• Локальные тома — /var/lib/rancher/k3s/storage растёт вместе с данными приложений;
• etcd — сама по себе маленькая, но без чистки истории раздувается.

Шаг 8. Почистите образы и логи

# неиспользуемые образы (k3s / containerd):
sudo k3s crictl rmi --prune

# усечь разросшиеся логи конкретного пода:
sudo truncate -s 0 /var/log/pods/*/имя-пода/*.log

Чтобы логи не разрастались в будущем, в k3s можно ограничить их размер при установке: INSTALL_K3S_EXEC="--kubelet-arg container-log-max-size=10Mi --kubelet-arg container-log-max-files=3".

Шаг 9. Присмотрите за etcd

Размер etcd смотрим в k3s так:

sudo k3s etcd-snapshot list
ls -lh /var/lib/rancher/k3s/server/db/

Если база перевалила за гигабайт на пустом кластере — полезно сделать дефрагментацию. Для k3s обычно достаточно того, что он сам периодически компактирует историю; в ванильном kubeadm-кластере дефрагментация делается через etcdctl (тема уже продвинутая — обратитесь к официальной документации kubernetes.io, раздел про etcd maintenance).

Шаг 10. Снапшоты etcd в k3s

В k3s это встроено и делается одной командой:

# ручной снапшот прямо сейчас
sudo k3s etcd-snapshot save --name before-upgrade

# список снапшотов
sudo k3s etcd-snapshot list

# файлы лежат здесь:
ls -lh /var/lib/rancher/k3s/server/db/snapshots/

Настройте автоматические снапшоты при установке или добавьте параметры в /etc/systemd/system/k3s.service (после правки: sudo systemctl daemon-reload && sudo systemctl restart k3s):

# флаги запуска k3s server:
--etcd-snapshot-schedule-cron="0 3 * * *"   # каждый день в 03:00
--etcd-snapshot-retention=7                  # хранить 7 последних

Шаг 11. Восстановление из снапшота (порядок действий)

# остановить k3s
sudo systemctl stop k3s

# восстановить кластер из выбранного снапшота
sudo k3s server --cluster-reset \
  --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/имя-снапшота

# после успешного восстановления снять режим reset
sudo systemctl start k3s
# проверить: kubectl get nodes, kubectl get pods -A

Потренируйтесь на свежем кластере: сделайте снапшот, создайте под, восстановитесь из снапшота — под должен исчезнуть. Опыт восстановления до того, как всё сгорело, бесценен.

Шаг 12. Бэкап манифестов и данных

• Манифесты: все свои YAML храните в git-репозитории (тем более когда поднимете Gitea — см. «Примеры»). Полный экспорт существующих объектов на всякий случай: kubectl get all -A -o yaml > cluster-dump.yaml (это скорее снимок для изучения, чем полноценный бэкап — восстанавливайтесь из своих чистых манифестов).
• Данные томов: для NFS — бэкапится каталог шары обычными средствами (rsync по расписанию). Для local-path — rsync каталога /var/lib/rancher/k3s/storage/ на NFS по cron. Для баз данных — их штатные дампы (pg_dump и т.п.) перед копированием файлов.

Шаг 1. Сделайте бэкап перед обновлением

# снапшот etcd (k3s)
sudo k3s etcd-snapshot save --name before-upgrade

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

Шаг 2. Обновите control-plane

В k3s — просто повторный запуск установочного скрипта с новой версией:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.31.4+k3s1 sh -

В kubeadm-кластере — штатная процедура: снять hold с пакетов, обновить kubeadm, выполнить kubeadm upgrade plan и kubeadm upgrade apply, затем обновить kubelet и kubectl. Подробный порядок зависит от версии — сверяйтесь с официальной документацией kubernetes.io.

Шаг 3. Обновите рабочие узлы по одному

# выгнать поды с узла
kubectl drain k8s-node2 --ignore-daemonsets --delete-emptydir-data

# обновить k3s-agent на узле (тот же скрипт с той же версией)
# ... или пакеты в kubeadm

# вернуть узел в строй
kubectl uncordon k8s-node2

Правило: версии узлов не должны отличаться от control-plane больше чем на два минорных релиза, а лучше держать всех на одной версии.

Шаг 13. Золотое правило диагностики

Когда «ничего не работает», идите по цепочке снизу вверх и проверяйте каждое звено одной командой:

1. Узел жив? → kubectl get nodes
2. Под запущен? → kubectl get pods -o wide
3. Что говорит сам под? → kubectl describe pod + kubectl logs
4. Есть ли за сервисом живые поды? → kubectl get endpoints
5. Работает ли сервис изнутри кластера? → kubectl run tmp --rm -it --image=busybox -- wget -qO- http://имя-сервиса
6. Работает ли Ingress? → kubectl describe ingress и логи контроллера

90% домашних проблем находится на первых трёх шагах этой цепочки.