Ansible-роль для патчинга узлов K3s без даунтайма

2 августа 2026 г.

#ansible#ci-cd#cluster-maintenance#k3s#longhorn#patching
Логотип проекта K3s Cluster Maintenance

Модульная Ansible-роль и плейбук для безопасного последовательного патчинга операционной системы и обслуживания узлов кластера K3s. Рассчитан на запуск вручную или из CI-раннера.

Содержание

Обзор

Автоматизация для кластеров K3s, которая последовательно применяет системные обновления и обновления пакетов на мастер-узлах и воркерах — по одному за раз. Роль выполняет проверки состояния, вытеснение (drain) с учётом PodDisruptionBudget (PDB), перезагрузку и восстановление узлов после обновления, сохраняя при этом исходное состояние планировщика.

Архитектура в двух словах

  • Модульная Ansible-роль с maintenance.yml в качестве точки входа

  • Последовательная обработка узлов для сохранения доступности кластера

  • Интеллектуальное обнаружение обновлений — роль пропускает работу, если обновлений нет

  • Проверки состояния хранилища Longhorn с ожиданием восстановления

  • Надёжная обработка перезагрузки с адаптивной логикой ожидания

  • Конфигурация через group_vars на основе групп

Структура роли

roles/
  k3s_node_maintenance/
    ├── tasks/
    │   ├── main.yml                 # Основная оркестрация задач
    │   ├── prerequisites.yml        # Предварительные проверки
    │   ├── package_checks.yml       # Обнаружение обновлений
    │   ├── cluster_preparation.yml  # Вытеснение узла (drain)
    │   ├── package_updates.yml      # Обновления ОС
    │   ├── debian_updates.yml       # Специфика Debian/Ubuntu
    │   ├── redhat_updates.yml       # Специфика RHEL/CentOS
    │   ├── reboot_handling.yml      # Координация перезагрузки
    │   └── cluster_restoration.yml  # Восстановление узла
    ├── defaults/
    │   └── main.yml                 # Значения переменных по умолчанию
    ├── handlers/
    │   └── main.yml                 # Обработчики событий
    └── meta/
        └── main.yml                 # Метаданные роли

Групповые переменные

group_vars/
  ├── k3s_masters/main.yml   # Настройки мастер-узлов
  ├── k3s_workers/main.yml   # Настройки воркеров
  ├── os_debian/main.yml     # Настройки для Debian/Ubuntu
  └── os_redhat/main.yml     # Настройки для RHEL/CentOS

Возможности

  • Автоматический патчинг ОС: системные обновления, патчи безопасности и обновления пакетов

  • Сохранение доступности кластера за счёт безопасной последовательной обработки узлов

  • Интеллектуальное обнаружение: ранний выход, если обновлений не требуется

  • Мониторинг состояния узлов, плоскости управления и хранилища

  • Нативная интеграция с Longhorn: проверка состояния томов и ожидание их восстановления

  • Безопасность плоскости управления за счёт обработки по одному узлу и немедленной остановки при сбое

  • Умное управление перезагрузкой, адаптирующееся к скорости загрузки узла

  • Модульная роль корпоративного уровня, готовая к масштабированию и кастомизации

Требования

  • Кластер K3s — одно- или многоузловой

  • Python 3.12 или новее и uv

  • Ansible Core 2.20.7 или новее

  • Python 3.9 или новее на каждом управляемом узле

  • Рабочий kubeconfig Kubernetes на контроллере Ansible

  • SSH-доступ ко всем узлам с аутентификацией по ключу

  • Проверенные ключи хостов в known_hosts контроллера

  • Коллекция Ansible kubernetes.core

  • Python-клиент Kubernetes для операций с API

Быстрый старт

Установите окружение проекта и коллекцию Ansible:

uv sync --frozen --extra ansible
uv run ansible-galaxy collection install -r collections/requirements.yml
cp hosts.example.yml hosts.yml

Запустите обслуживание:

# Обновить все воркеры
uv run ansible-playbook -i hosts.yml maintenance.yml --limit k3s_workers

# Обновить все мастер-узлы
uv run ansible-playbook -i hosts.yml maintenance.yml --limit k3s_masters

# Обновить конкретный узел
uv run ansible-playbook -i hosts.yml maintenance.yml --limit node-01

# Обновить весь кластер
uv run ansible-playbook -i hosts.yml maintenance.yml

Конфигурация

Переменные роли

Поведение настраивается через групповые переменные.

# host_vars/node-01.yml
# Переопределите, если псевдоним в инвентаре отличается от имени узла Kubernetes.
k3s_node_maintenance_kubernetes_node_name: k3s-worker-a

# Безопасное вытеснение по умолчанию: учитывать PDB, DaemonSet и данные emptyDir.
k3s_node_maintenance_drain_timeout: 300
k3s_node_maintenance_drain_grace_period: 30
k3s_node_maintenance_drain_force: false
k3s_node_maintenance_drain_delete_emptydir_data: false

# Управление обслуживанием
k3s_node_maintenance_skip_if_no_updates: true
k3s_node_maintenance_force_maintenance: false
k3s_node_maintenance_skip_drain: false
k3s_node_maintenance_longhorn_enabled: true

Структура инвентаря

Опишите кластер в файле hosts.yml:

all:
  children:
    k3s_cluster:
      children:
        k3s_masters:
          hosts:
            master-01:
              ansible_host: 10.0.0.100
            master-02:
              ansible_host: 10.0.0.101
            master-03:
              ansible_host: 10.0.0.102
        k3s_workers:
          hosts:
            worker-01:
              ansible_host: 10.0.0.150
            worker-02:
              ansible_host: 10.0.0.151
        os_debian:
          hosts:
            master-01:
            worker-01:
        os_redhat:
          hosts:
            master-02:
            master-03:
            worker-02:

Содержимое репозитория

Файл Описание

maintenance.yml

Основной плейбук, использующий архитектуру корпоративных ролей

hosts.example.yml

Пример инвентаря с групповой структурой

ansible.cfg

Конфигурация Ansible

roles/

Модульная архитектура ролей

group_vars/

Переменные, специфичные для типа узла и ОС

pyproject.toml

Python-зависимости и метаданные проекта

collections/requirements.yml

Требуемые коллекции Ansible

Справочник тегов

Тег Описание Сценарий использования

prerequisites

Предварительные проверки

Валидация настройки окружения

check_updates

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

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

cluster

Операции планировщика кластера

Вытеснение и восстановление узлов без изменения пакетов

prepare

Подготовка кластера

Только cordon и drain узлов

packages

Все операции с пакетами

Только управление пакетами

updates

Установка пакетов

Только установка обновлений

reboot

Координация перезагрузки

Только обработка перезагрузки

restore

Восстановление кластера

Снятие ограничений (uncordon) и восстановление планировщика

resume

Ручное восстановление

Проверка готовности и опциональное восстановление планировщика

uncordon

Снятие ограничений узла

Только восстановление планировщика узла

debian

Только Debian или Ubuntu

Операции, специфичные для ОС

redhat

Только RHEL или CentOS

Операции, специфичные для ОС

longhorn

Валидация Longhorn

Проверка состояния хранилища и восстановление томов

Проверки работоспособности

  • Предварительная валидация предусловий кластера и связности

  • Проверка готовности узла до и после обслуживания

  • Проверка готовности и доступности планировщика для всех узлов кластера

  • Проверка состояния томов Longhorn и ожидание восстановления при наличии Longhorn

Точка входа

Этот проект представляет собой Ansible-автоматизацию, а не сетевой сервис.

  • Основная точка входа: maintenance.yml

  • Запуск: uv run ansible-playbook -i hosts.yml maintenance.yml с нужными тегами и ограничениями

Рекомендации для продакшена

  • Узлы обрабатываются последовательно; при первом сбое обслуживание останавливается

  • Устанавливайте консервативные таймауты с учётом времени загрузки узла и скачивания образов

  • Используйте тег check_updates, чтобы не выполнять лишнюю работу при отсутствии обновлений

  • При использовании Longhorn давайте деградировавшим томам время восстановиться до перехода к следующему узлу

  • Не отключайте drain, если не проанализировали последствия для нагрузки

  • Задавайте k3s_node_maintenance_kubernetes_node_name, если имя хоста в инвентаре отличается от имени узла Kubernetes

Разработка

# 1) Клонировать репозиторий
git clone https://github.com/sudo-kraken/k3s-cluster-maintenance.git
cd k3s-cluster-maintenance

# 2) Установить Python-зависимости и коллекции Ansible
uv sync --frozen --extra ansible
uv run ansible-galaxy collection install -r collections/requirements.yml

# 3) Настроить инвентарь
cp hosts.example.yml hosts.yml
# отредактируйте hosts.yml, добавив данные своего кластера

# 4) Проверить связность
uv run ansible all -i hosts.yml -m ping

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

  • Проверить доступные обновления:

    uv run ansible all -i hosts.yml -m package_facts

  • Проверить состояние кластера:

    kubectl get nodes
kubectl get pods --all-namespaces

  • Проверить статус Longhorn (если используется):

    kubectl get pods -n longhorn-system

Типичные проблемы

  • Обновлений нет — штатное поведение. Роль пропускает обслуживание, если ни один пакет не требует обновления.

  • Узел не готов после обслуживания:

    kubectl get nodes
kubectl uncordon <node-name>

  • Проблемы с подключением Ansible:

    uv run ansible all -i hosts.yml -m ping
ssh user@node-ip

Режим отладки

uv run ansible-playbook -i hosts.yml maintenance.yml -vvv
uv run ansible-playbook -i hosts.yml maintenance.yml --list-tags
uv run ansible-playbook -i hosts.yml maintenance.yml --tags check_updates --check
uv run ansible-playbook -i hosts.yml maintenance.yml --limit node-01 --tags resume \
  -e k3s_node_maintenance_resume_restore_scheduling=true

Лицензия

Проект распространяется под лицензией MIT. Подробности — в файле LICENSE.

Безопасность

Если вы обнаружили проблему безопасности, следуйте инструкциям в SECURITY.md и воспользуйтесь приватным механизмом сообщения об уязвимостях в репозитории. Не открывайте публичный issue.

Участие в проекте

Открывайте issues или отправляйте pull-запросы, если у вас есть предложения или улучшения. Подробнее — в файле CONTRIBUTING.md.

Поддержка

Откройте issue, указав как можно больше деталей: версию Ansible, сведения о дистрибутиве и соответствующий вывод плейбука.

Отказ от ответственности

Этот инструмент выполняет операции по обслуживанию вашего кластера Kubernetes. Всегда:

  • Тестируйте в непродакшеновом окружении прежде всего

  • Убедитесь, что у вас есть свежие резервные копии

  • Изучите задачи роли перед развёртыванием

  • Следите за процессом во время выполнения

Используйте на свой страх и риск. Автор не несёт ответственности за какой-либо ущерб или потерю данных.

Похожее

© 2026 meganuke