17-kubernetes — Kubernetes (k3s + kubectl + helm)

Ставит лёгкий Kubernetes-дистрибутив k3s, ждёт готовности узла, копирует доступ (kubeconfig) деплой-пользователю, ставит Helm и открывает нужные порты в файрволе. Поддерживает одиночный сервер и HA-кластер из нескольких серверов. ☐ опциональный.

Зачем нужен #

Kubernetes (сокращённо «k8s») — это система оркестрации контейнеров: она сама запускает ваши приложения-контейнеры на серверах, перезапускает упавшие, держит нужное число копий (реплик), обновляет их без простоя и распределяет нагрузку. Вы описываете «что должно работать», а Kubernetes следит, чтобы так и было.

k3s — это официальный облегчённый дистрибутив Kubernetes (сертифицирован CNCF), собранный в один бинарник. Он идеально подходит для одного продакшен-сервера: внутри уже есть containerd (среда запуска контейнеров), поэтому Docker не требуется. При этом это полноценный Kubernetes — те же kubectl, манифесты и Helm.

Модуль ставит k3s, консольный клиент kubectl (внутри k3s), пакетный менеджер Helm (устанавливает готовые приложения в кластер «одной командой», как apt для Kubernetes), настраивает доступ и файрвол — и даёт команду mitdev k8s deploy для развёртывания ваших контейнеров.

Когда включать и когда не нужен #

• Включайте, если приложения поставляются как Docker-образы и вы хотите катить их с автоперезапуском, репликами и обновлением без простоя; или планируете отказоустойчивый кластер из нескольких серверов.
• Не нужен, если приложение проще запускать через PM2/Docker Compose — Kubernetes добавляет сложность, которая оправдана не всегда.
• Важно про nginx: если на сервере уже установлен nginx, k3s ставится с отключённым traefik (см. ниже) — публикация приложений идёт через nginx.

Зависимости и требования #

• Отдельных модулей mitdev формально не требует, но:
  • если установлен модуль user — kubeconfig копируется деплой-пользователю (DEPLOY_USER);
  • если установлен nginx — traefik в k3s отключается, приложения публикуются через nginx.
• Нужен доступ в интернет: k3s ставится скриптом https://get.k3s.io, Helm — официальным скриптом с raw.githubusercontent.com.
• Для HA-кластера (несколько серверов) — приватная сеть между узлами и открытые кластерные порты (модуль открывает их сам для указанных пиров).

Три режима кластера #

Режим выбирается переменной K8S_CLUSTER_MODE (её задаёт мастер установки):

etcd («embedded etcd») — это встроенная в k3s распределённая база, где хранится всё состояние кластера; в HA-режиме она реплицируется между серверами, поэтому кластер переживает отказ узла. Для кворума etcd нужно нечётное число серверов (обычно 3).

Режим join требует двух параметров, которые даёт первый узел командой mitdev k8s token:

• K8S_SERVER_URL — адрес вида https://<ip-первого-узла>:6443;
• K8S_TOKEN — секретный токен присоединения.

Ещё одна переменная — K8S_PEERS (список IP остальных серверов кластера): по ним модуль точечно открывает кластерные порты в файрволе.

Что именно делает #

Пошагово, в порядке выполнения module_install:

1. Ставит k3s (канал stable) в выбранном режиме. Если k3s уже установлен и запущен — шаг пропускается. Формируется строка запуска:
   • single → server;
   • init → server --cluster-init (поднимает встроенный etcd);
   • join → server --server <K8S_SERVER_URL> (проверяет наличие K8S_SERVER_URL и K8S_TOKEN).
2. Если обнаружен nginx (state_done nginx или служба активна) — к строке запуска добавляется --disable traefik. traefik — это встроенный в k3s веб-балансировщик (ingress-контроллер), который сам занимает порты 80 и 443; nginx хочет те же порты, поэтому их «драка» устраняется отключением traefik. Публикация приложений тогда идёт через nginx.
3. Ждёт готовности узла (_k8s_wait_node_ready): до 30 попыток с интервалом 4 секунды (до ~2 минут) опрашивает kubectl get nodes, пока узел не перейдёт в состояние Ready (готов принимать поды).
4. Копирует kubeconfig деплой-пользователю (если задан DEPLOY_USER): создаёт /home/<user>/.kube (700), кладёт /etc/rancher/k3s/k3s.yaml в ~/.kube/config (600, владелец — деплой-пользователь). kubeconfig — это файл с адресом кластера и ключами доступа; с ним kubectl работает от имени пользователя без sudo.
5. Ставит Helm официальным скриптом в /usr/local/bin/helm (если ещё не установлен).
6. Открывает порты в файрволе (если UFW активен):
   • 6443/tcp — API-сервер Kubernetes;
   • 10.42.0.0/16 — сеть подов (pod — минимальная единица запуска, один или несколько контейнеров);
   • 10.43.0.0/16 — сеть сервисов (внутренние виртуальные адреса служб);
   • для каждого пира из K8S_PEERS дополнительно (нужно для HA): 2379:2380/tcp (etcd), 10250/tcp (kubelet — агент на узле), 8472/udp (flannel VXLAN — сетевой туннель между узлами).
7. Если режим init — печатает подсказку: токен присоединения берётся командой mitdev k8s token.
8. Верификация и state_mark.

Файлы, службы и порты #

Учётные данные #

Отдельных паролей модуль не сохраняет в /root/.mitdev-credentials. Доступ к кластеру даёт kubeconfig:

• для root — /etc/rancher/k3s/k3s.yaml (используется автоматически через k3s kubectl);
• для деплой-пользователя — ~/.kube/config (права 600).

Секрет присоединения новых узлов к кластеру — токен в /var/lib/rancher/k3s/server/node-token (читается только root). Его показывает mitdev k8s token.

Настройка #

Эти переменные собирает мастер установки (их нет в config/defaults.conf):

K8S_SERVER_URL и K8S_TOKEN для режима join вы берёте с первого узла командой mitdev k8s token.

Как переопределить настройки #

Обычно эти переменные задаются интерактивно в мастере установки при выборе кластерного сценария. Их можно передать и явно перед запуском (флаг -E сохраняет окружение при sudo):

# первый узел HA-кластера
K8S_CLUSTER_MODE=init sudo -E ./install.sh

# присоединяемый узел
K8S_CLUSTER_MODE=join \
  K8S_SERVER_URL=https://10.8.0.1:6443 \
  K8S_TOKEN=<токен-с-первого-узла> \
  K8S_PEERS="10.8.0.1 10.8.0.2" \
  sudo -E ./install.sh

Как пользоваться #

Режим single — одиночный сервер #

Ничего дополнительно делать не нужно: после установки узел готов, деплойте приложения (см. ниже).

Режим init + join — HA-кластер по шагам #

Узел 1 (первый сервер, режим init):

# при установке выбран режим init (или K8S_CLUSTER_MODE=init)
# после установки получите параметры присоединения:
sudo mitdev k8s token
# выведет:  URL: https://<ip-узла-1>:6443   и   Токен: <строка>

Узел 2 и далее (режим join): запустите установку с параметрами, полученными на узле 1:

K8S_CLUSTER_MODE=join \
  K8S_SERVER_URL=https://<ip-узла-1>:6443 \
  K8S_TOKEN=<токен-с-узла-1> \
  K8S_PEERS="<ip-узла-1> <ip-узла-3>" \
  sudo -E ./install.sh

Проверка кластера (на любом узле):

sudo mitdev k8s nodes    # все узлы должны быть Ready
sudo mitdev k8s status

Для кворума etcd держите нечётное число серверов (3 — типичный минимум для HA).

Добавить ещё один узел #

Повторите шаг «join» на новом сервере с тем же URL и токеном (токен всегда можно переполучить на первом узле через mitdev k8s token). Не забудьте добавить IP нового узла в K8S_PEERS на нём (и при желании открыть порты для него на других узлах).

Развернуть приложение — mitdev k8s deploy #

sudo mitdev k8s deploy <имя> <образ> [порт] [домен] [реплики]

• <имя> — латиница-kebab (например web), по RFC 1123;
• <образ> — Docker-образ, например ghcr.io/org/app:latest;
• [порт] — порт внутри контейнера (по умолчанию спрашивается, типовое 3000);
• [домен] — если указан, приложение публикуется наружу (через traefik или nginx); пусто — доступно только внутри кластера;
• [реплики] — число копий (по умолчанию 2).

Пример:

sudo mitdev k8s deploy web ghcr.io/org/app:latest 3000 app.example.com 3

Что происходит: рендерится манифест Deployment + Service в /var/lib/mitdev/k8s/web.yaml, применяется kubectl apply, ожидается раскатка (rollout status, до 180 с). Манифест включает podAntiAffinity — правило, которое старается разнести реплики по разным узлам кластера: падение одного сервера уносит максимум одну копию, остальные продолжают обслуживать трафик. Также заданы проверки готовности/живости (readiness/liveness probes) и плавное обновление (rolling update без простоя). Если задан домен: при включённом traefik создаётся Ingress (правило маршрутизации HTTP по домену), при nginx — сайт nginx на выделенный NodePort сервиса (с предложением выпустить SSL через certbot).

Управлять кластером через kubectl #

От root — через встроенный клиент:

sudo k3s kubectl get pods -A

От деплой-пользователя — обычный kubectl (kubeconfig уже лежит в ~/.kube/config):

kubectl get pods
kubectl get nodes

Удобные обёртки mitdev:

sudo mitdev k8s status      # версия, узлы, поды, приложения mitdev
sudo mitdev k8s nodes       # узлы (get nodes -o wide)
sudo mitdev k8s pods [ns]   # поды (всех или одного namespace)
sudo mitdev k8s services    # сервисы
sudo mitdev k8s logs <app>  # логи приложения (follow)
sudo mitdev k8s apply <файл.yaml>

Проверка, что всё работает #

module_verify считает модуль успешным, если: команда k3s есть, служба k3s активна, узел в состоянии Ready, и установлен helm.

Ручные проверки:

# версия и служба
sudo k3s --version
systemctl status k3s

# узел(ы) должны быть Ready
sudo k3s kubectl get nodes

# системные поды (kube-system) в Running
sudo k3s kubectl get pods -A

# Helm установлен
helm version

# общая диагностика mitdev
sudo mitdev doctor

Типовые задачи #

• Получить токен и URL для присоединения узла:

  sudo mitdev k8s token
  

• Развернуть приложение с публикацией на домен:

  sudo mitdev k8s deploy web ghcr.io/org/app:latest 3000 app.example.com 2
  

• Обновить образ приложения — повторите deploy с новым тегом образа (пройдёт rolling update):

  sudo mitdev k8s deploy web ghcr.io/org/app:v2 3000 app.example.com 2
  

• Посмотреть логи приложения:

  sudo mitdev k8s logs web
  

• Удалить одно приложение (Deployment/Service/Ingress + сайт nginx, если был):

  sudo mitdev k8s delete web
  

• Удалить все приложения mitdev, но оставить кластер:

  sudo mitdev k8s delete-all
  

• Установить готовое приложение через Helm (пример):

  helm repo add bitnami https://charts.bitnami.com/bitnami
  helm install my-redis bitnami/redis
  

Частые ошибки #

Безопасность и продакшен #

Модуль уже закрывает: k3s работает через containerd без Docker, kubeconfig деплой-пользователя имеет права 600, порты открываются точечно (API — всем, кластерные — только пирам из K8S_PEERS), traefik отключается при конфликте с nginx.

Остаётся на клиенте:

• Порт 6443 (API-сервер) — не открывайте его в интернет шире необходимого. UFW открывает 6443/tcp; ограничьте источник до доверенных сетей/пиров, если API не должен быть публичным.
• kubeconfig — секрет. Держите ~/.kube/config и /etc/rancher/k3s/k3s.yaml с правами 600 и не копируйте на чужие машины.
• Для HA держите нечётное число серверов (кворум etcd) и приватную сеть между узлами.
• Ограничивайте ресурсы подов (в шаблоне уже заданы requests/limits) и следите за обновлениями образов.

Откат и удаление #

• Авто-откат при падении установки (module_rollback): запускает штатный k3s-uninstall.sh (если есть) и удаляет helm.
• mitdev remove kubernetes (то же, что mitdev k8s delete-cluster): запускает официальный /usr/local/bin/k3s-uninstall.sh, который сносит весь узел — все поды, рабочие нагрузки, хранилище containerd и состояние кластера (etcd/sqlite). Дополнительно удаляются Helm, kubeconfig деплой-пользователя и правила файрвола, открытые модулем. Это и есть команда «удалить кластер и все поды».
• Флаг --purge здесь ничего сверх этого не добавляет — деинсталлятор k3s и так удаляет данные кластера.

См. также #

• ../KUBERNETES.md — подробное руководство по Kubernetes в mitdev.
• ../HA.md — отказоустойчивость и кластеры.
• ../COMMANDS.md — все подкоманды mitdev k8s.
• ../MODULES.md — краткий обзор всех модулей.