Настроил. Добавил серию статей о K3S Cluster

2026-02-16 14:15:59 +00:00
parent 49ab08074f
commit 7b08cef369
141 changed files with 27755 additions and 1682 deletions
@@ -0,0 +1,650 @@
+---
+title: "Установить K3s HA кластер"
+date: 2025-11-02
+draft: true
+description: "Один curl-скрипт на каждую ноду - и через 15 минут у вас работающий HA-кластер. Устанавливаем K3s на 3 master и 2 worker ноды, настраиваем kubectl."
+summary: "Инфраструктура готова: 5 VM работают, ОС настроена, порты открыты. Пора устанавливать K3s. Один curl-скрипт на каждую ноду - и через 15 минут у вас работающий HA-кластер."
+tags: ["kubernetes", "k3s", "homelab", "installation", "ha", "etcd", "devops"]
+series: ["K3s HA кластер для homelab"]
+series_order: 3
+# seriesOpened: true
+showTableOfContents: true
+---
+
+Инфраструктура готова: 5 VM работают, ОС настроена, порты открыты. Пора устанавливать K3s. Один curl-скрипт на каждую ноду - и через 15 минут у вас работающий HA-кластер.
+
+Звучит слишком просто? Потому что сложная часть уже позади - в предыдущих статьях. Теперь осталось не перепутать флаги и порядок установки.
+
+**Результат:** 5 нод в статусе Ready, etcd кластер 3/3 healthy, kubectl работает с локальной машины.
+
+---
+
+## Для кого это
+
+**Подходит:**
+- Прошёл статьи 1 и 2 (или имеешь готовые VM с настроенной ОС)
+- Все 5 нод доступны по SSH
+- Понимаешь разницу между master и worker
+
+**Не подходит:**
+- VM ещё не созданы → статья 2
+- Не понимаешь зачем 3 master ноды → статья 1
+
+---
+
+## Что понадобится
+
+| Компонент | Значение |
+|-----------|----------|
+| K3s версия | v1.31.4+k3s1 (или актуальная stable) |
+| Token | Сгенерируем на первом шаге |
+| SSH доступ | Ко всем 5 нодам |
+| Время | ~15-20 минут |
+
+---
+
+## Шаг 1: Сгенерировать token
+
+Token - общий секрет для всех нод кластера. Без правильного token нода не присоединится.
+
+**На локальной машине:**
+
+```bash
+# Сгенерировать случайный token
+openssl rand -base64 32
+```
+
+**Пример вывода:**
+```
+K10f8c9a7b6e5d4c3b2a1f0e9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4==
+```
+
+**Сохрани этот token** - он понадобится для каждой ноды. Положи в менеджер паролей или временный файл.
+
+```bash
+# Для удобства - сохранить в переменную (на время сессии)
+export K3S_TOKEN="твой_сгенерированный_token"
+echo $K3S_TOKEN
+```
+
+---
+
+## Шаг 2: Установить K3s на первую master ноду
+
+Первая нода инициализирует etcd кластер. Она особенная - использует флаг `--cluster-init`.
+
+**SSH на k3s-master-1:**
+
+```bash
+ssh k3s@192.168.11.201
+```
+
+**Установка:**
+
+```bash
+# Задать переменные
+export K3S_TOKEN="твой_сгенерированный_token"
+export INSTALL_K3S_VERSION="v1.31.4+k3s1"
+
+# Установить K3s
+curl -sfL https://get.k3s.io | sh -s - server \
+  --cluster-init \
+  --tls-san=192.168.11.201 \
+  --disable=traefik \
+  --disable=servicelb \
+  --write-kubeconfig-mode=644
+```
+
+**Разбор флагов:**
+
+| Флаг | Зачем |
+|------|-------|
+| `server` | Режим control plane (не agent) |
+| `--cluster-init` | **Ключевой!** Инициализирует etcd. Только на первой ноде |
+| `--tls-san=192.168.11.201` | Добавить IP в сертификат API server |
+| `--disable=traefik` | Отключить встроенный Traefik (установим свой через Helm) |
+| `--disable=servicelb` | Отключить встроенный LB (установим MetalLB) |
+| `--write-kubeconfig-mode=644` | Разрешить чтение kubeconfig без sudo |
+
+**Установка займёт 1-2 минуты.** K3s скачает бинарник (~50MB) и запустит все компоненты.
+
+### Проверка
+
+```bash
+# 1. Статус сервиса
+sudo systemctl status k3s
+```
+
+**Ожидаемый результат:**
+```
+● k3s.service - Lightweight Kubernetes
+     Loaded: loaded
+     Active: active (running) since ...
+```
+
+```bash
+# 2. Статус ноды
+sudo k3s kubectl get nodes
+```
+
+**Ожидаемый результат:**
+```
+NAME           STATUS   ROLES                       AGE   VERSION
+k3s-master-1   Ready    control-plane,etcd,master   45s   v1.31.4+k3s1
+```
+
+<!-- СКРИНШОТ: Терминал с выводом `sudo k3s kubectl get nodes` - одна нода в статусе Ready -->
+
+### Checkpoint: Первая master работает
+
+```bash
+# Быстрая проверка
+sudo systemctl is-active k3s && \
+sudo k3s kubectl get nodes | grep -q "Ready" && \
+echo "✓ Master-1 готов" || echo "✗ Проблема"
+```
+
+**Если статус NotReady или сервис не запустился:**
+
+```bash
+# Смотреть логи
+sudo journalctl -u k3s -f --no-pager | tail -50
+```
+
+| Ошибка в логах | Причина | Решение |
+|----------------|---------|---------|
+| `cgroup v1 is not supported` | Нужен cgroup v2 | Вернись к статье 2, шаг 6.5 |
+| `port 6443 already in use` | Что-то занимает порт | `sudo ss -tlnp \| grep 6443` |
+| `etcd failed to start` | Мало места на диске | `df -h`, увеличь диск |
+
+---
+
+## Шаг 3: Добавить вторую master ноду
+
+Теперь присоединяем вторую master. Она подключается к существующему кластеру - **без** `--cluster-init`.
+
+**SSH на k3s-master-2:**
+
+```bash
+ssh k3s@192.168.11.202
+```
+
+**Установка:**
+
+```bash
+export K3S_TOKEN="твой_сгенерированный_token"
+export INSTALL_K3S_VERSION="v1.31.4+k3s1"
+
+curl -sfL https://get.k3s.io | sh -s - server \
+  --server=https://192.168.11.201:6443 \
+  --tls-san=192.168.11.202 \
+  --disable=traefik \
+  --disable=servicelb \
+  --write-kubeconfig-mode=644
+```
+
+**Ключевое отличие:**
+- ❌ Нет `--cluster-init` - кластер уже инициализирован
+- ✅ Есть `--server=https://192.168.11.201:6443` - адрес существующего кластера
+
+### Проверка
+
+```bash
+# На master-2
+sudo k3s kubectl get nodes
+```
+
+**Ожидаемый результат:**
+```
+NAME           STATUS   ROLES                       AGE   VERSION
+k3s-master-1   Ready    control-plane,etcd,master   3m    v1.31.4+k3s1
+k3s-master-2   Ready    control-plane,etcd,master   30s   v1.31.4+k3s1
+```
+
+Две ноды - но кворума ещё нет. etcd требует большинство, а 2 из 3 - это ещё не "большинство от трёх".
+
+---
+
+## Шаг 4: Добавить третью master ноду
+
+**SSH на k3s-master-3:**
+
+```bash
+ssh k3s@192.168.11.203
+```
+
+**Установка (аналогично master-2):**
+
+```bash
+export K3S_TOKEN="твой_сгенерированный_token"
+export INSTALL_K3S_VERSION="v1.31.4+k3s1"
+
+curl -sfL https://get.k3s.io | sh -s - server \
+  --server=https://192.168.11.201:6443 \
+  --tls-san=192.168.11.203 \
+  --disable=traefik \
+  --disable=servicelb \
+  --write-kubeconfig-mode=644
+```
+
+### Checkpoint: Control Plane HA готов
+
+**На любой master ноде:**
+
+```bash
+# 1. Все 3 master ноды Ready
+sudo k3s kubectl get nodes
+```
+
+**Ожидаемый результат:**
+```
+NAME           STATUS   ROLES                       AGE   VERSION
+k3s-master-1   Ready    control-plane,etcd,master   5m    v1.31.4+k3s1
+k3s-master-2   Ready    control-plane,etcd,master   3m    v1.31.4+k3s1
+k3s-master-3   Ready    control-plane,etcd,master   1m    v1.31.4+k3s1
+```
+
+```bash
+# 2. etcd кластер здоров
+sudo k3s kubectl exec -n kube-system \
+  $(sudo k3s kubectl get pods -n kube-system -l component=etcd -o name | head -1) \
+  -- etcdctl endpoint health --cluster
+```
+
+**Ожидаемый результат:**
+```
+https://192.168.11.201:2379 is healthy: successfully committed proposal: took = 2.1ms
+https://192.168.11.202:2379 is healthy: successfully committed proposal: took = 1.8ms
+https://192.168.11.203:2379 is healthy: successfully committed proposal: took = 2.3ms
+```
+
+<!-- СКРИНШОТ: Терминал с выводом etcdctl endpoint health - все 3 endpoint healthy -->
+
+**Теперь у вас настоящий HA.** Можете остановить любую master ноду - кластер продолжит работать.
+
+### Тест отказоустойчивости (опционально)
+
+Хотите убедиться, что HA работает? Проверьте:
+
+```bash
+# С локальной машины - остановить master-2
+ssh k3s@192.168.11.202 "sudo systemctl stop k3s"
+
+# Подождать 30-40 секунд, затем на master-1:
+ssh k3s@192.168.11.201 "sudo k3s kubectl get nodes"
+# master-2 станет NotReady, но кластер работает
+
+# Проверить etcd - 2/3 кворум есть
+ssh k3s@192.168.11.201 "sudo k3s kubectl exec -n kube-system \
+  \$(sudo k3s kubectl get pods -n kube-system -l component=etcd -o name | head -1) \
+  -- etcdctl endpoint health --cluster"
+# 2 из 3 healthy - кворум есть
+
+# Вернуть master-2
+ssh k3s@192.168.11.202 "sudo systemctl start k3s"
+```
+
+---
+
+## Шаг 5: Добавить worker ноды
+
+Worker ноды устанавливаются как **agent** - они не участвуют в etcd и не запускают control plane.
+
+### 5.1. Установить K3s agent на worker-1
+
+**SSH на k3s-worker-1:**
+
+```bash
+ssh k3s@192.168.11.210
+```
+
+**Установка:**
+
+```bash
+export K3S_TOKEN="твой_сгенерированный_token"
+export INSTALL_K3S_VERSION="v1.31.4+k3s1"
+
+curl -sfL https://get.k3s.io | sh -s - agent \
+  --server=https://192.168.11.201:6443
+```
+
+**Отличия от master:**
+- `agent` вместо `server` - режим worker
+- Нет флагов `--disable` и `--tls-san` - они не нужны для worker
+- Только `--server` - куда подключаться
+
+### 5.2. Установить K3s agent на worker-2
+
+**SSH на k3s-worker-2:**
+
+```bash
+ssh k3s@192.168.11.211
+```
+
+**Установка:**
+
+```bash
+export K3S_TOKEN="твой_сгенерированный_token"
+export INSTALL_K3S_VERSION="v1.31.4+k3s1"
+
+curl -sfL https://get.k3s.io | sh -s - agent \
+  --server=https://192.168.11.201:6443
+```
+
+### Checkpoint: Все ноды в кластере
+
+**На любой master ноде:**
+
+```bash
+sudo k3s kubectl get nodes -o wide
+```
+
+**Ожидаемый результат:**
+```
+NAME           STATUS   ROLES                       AGE   VERSION        INTERNAL-IP
+k3s-master-1   Ready    control-plane,etcd,master   10m   v1.31.4+k3s1   192.168.11.201
+k3s-master-2   Ready    control-plane,etcd,master   8m    v1.31.4+k3s1   192.168.11.202
+k3s-master-3   Ready    control-plane,etcd,master   6m    v1.31.4+k3s1   192.168.11.203
+k3s-worker-1   Ready    <none>                      2m    v1.31.4+k3s1   192.168.11.210
+k3s-worker-2   Ready    <none>                      1m    v1.31.4+k3s1   192.168.11.211
+```
+
+<!-- СКРИНШОТ: Терминал с выводом kubectl get nodes - все 5 нод Ready -->
+
+**Обрати внимание:**
+- Master: роли `control-plane,etcd,master`
+- Worker: роли `<none>` - только выполнение workloads
+
+![K3S HA Cluster](mermaid-diagram.svg)
+
+---
+
+## Шаг 6: Настроить kubectl на локальной машине
+
+Сейчас kubectl работает только на master нодах через `sudo k3s kubectl`. Настроим доступ с вашей рабочей машины.
+
+### 6.1. Скопировать kubeconfig
+
+**На локальной машине (не на ноде):**
+
+```bash
+# 1. Создать директорию
+mkdir -p ~/.kube
+
+# 2. Скопировать конфиг с master-1
+scp k3s@192.168.11.201:/etc/rancher/k3s/k3s.yaml ~/.kube/config
+
+# 3. Заменить localhost на реальный IP
+sed -i 's/127.0.0.1/192.168.11.201/g' ~/.kube/config
+
+# Для macOS:
+# sed -i '' 's/127.0.0.1/192.168.11.201/g' ~/.kube/config
+
+# 4. Права доступа
+chmod 600 ~/.kube/config
+```
+
+### 6.2. Установить kubectl (если нет)
+
+**Linux:**
+
+```bash
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+rm kubectl
+```
+
+**macOS:**
+
+```bash
+brew install kubectl
+```
+
+### 6.3. Проверить подключение
+
+```bash
+# Версия
+kubectl version
+
+# Ноды
+kubectl get nodes
+
+# Все поды
+kubectl get pods -A
+```
+
+**Ожидаемый результат `kubectl get pods -A`:**
+```
+NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
+kube-system   coredns-xxx                               1/1     Running   0          10m
+kube-system   local-path-provisioner-xxx                1/1     Running   0          10m
+kube-system   metrics-server-xxx                        1/1     Running   0          10m
+```
+
+<!-- СКРИНШОТ: Терминал локальной машины с выводом kubectl get nodes и kubectl get pods -A -->
+
+**Если kubectl не подключается:**
+
+| Симптом | Причина | Решение |
+|---------|---------|---------|
+| `connection refused` | k3s не запущен | `ssh k3s@192.168.11.201 "sudo systemctl status k3s"` |
+| `connection timeout` | Firewall блокирует | Проверь UFW на master: `sudo ufw status \| grep 6443` |
+| `certificate signed by unknown authority` | Неправильный kubeconfig | Скопируй заново с master ноды |
+
+### 6.4. Настроить автодополнение (опционально)
+
+```bash
+# Bash
+echo 'source <(kubectl completion bash)' >> ~/.bashrc
+echo 'alias k=kubectl' >> ~/.bashrc
+echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+echo 'source <(kubectl completion zsh)' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Теперь работает `k get nodes` и Tab-автодополнение.
+
+---
+
+## Финальная проверка
+
+Полный чеклист работоспособности кластера:
+
+```bash
+echo "=== Проверка K3s HA кластера ==="
+
+echo -n "1. Все ноды Ready: "
+[ $(kubectl get nodes --no-headers | grep -c "Ready") -eq 5 ] && echo "✓ (5/5)" || echo "✗"
+
+echo -n "2. Master ноды: "
+kubectl get nodes --no-headers | grep -c "control-plane" | xargs -I {} echo "✓ ({}/3)"
+
+echo -n "3. Worker ноды: "
+kubectl get nodes --no-headers | grep -c "<none>" | xargs -I {} echo "✓ ({}/2)"
+
+echo -n "4. etcd healthy: "
+kubectl exec -n kube-system \
+  $(kubectl get pods -n kube-system -l component=etcd -o name | head -1) \
+  -- etcdctl endpoint health --cluster 2>/dev/null | grep -c "is healthy" | xargs -I {} echo "✓ ({}/3)"
+
+echo -n "5. CoreDNS Running: "
+kubectl get pods -n kube-system -l k8s-app=kube-dns --no-headers | grep -q "Running" && echo "✓" || echo "✗"
+
+echo -n "6. Metrics Server Running: "
+kubectl get pods -n kube-system -l k8s-app=metrics-server --no-headers | grep -q "Running" && echo "✓" || echo "✗"
+
+echo ""
+echo "=== Информация о кластере ==="
+kubectl cluster-info
+```
+
+**Ожидаемый результат:**
+```
+=== Проверка K3s HA кластера ===
+1. Все ноды Ready: ✓ (5/5)
+2. Master ноды: ✓ (3/3)
+3. Worker ноды: ✓ (2/2)
+4. etcd healthy: ✓ (3/3)
+5. CoreDNS Running: ✓
+6. Metrics Server Running: ✓
+
+=== Информация о кластере ===
+Kubernetes control plane is running at https://192.168.11.201:6443
+CoreDNS is running at https://192.168.11.201:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
+Metrics-server is running at https://192.168.11.201:6443/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy
+```
+
+---
+
+## Тестовый деплой
+
+Убедимся, что кластер может запускать приложения:
+
+```bash
+# 1. Создать тестовый под
+kubectl run nginx-test --image=nginx:alpine --port=80
+
+# 2. Подождать запуска
+kubectl wait --for=condition=Ready pod/nginx-test --timeout=60s
+
+# 3. Проверить на какой ноде запустился
+kubectl get pod nginx-test -o wide
+```
+
+**Ожидаемый результат:**
+```
+NAME         READY   STATUS    RESTARTS   AGE   IP           NODE
+nginx-test   1/1     Running   0          30s   10.42.1.5    k3s-worker-1
+```
+
+Под запустился на worker ноде - как и должно быть.
+
+```bash
+# 4. Проверить доступность изнутри кластера
+kubectl run -it --rm debug --image=busybox --restart=Never -- wget -qO- nginx-test
+```
+
+**Ожидаемый результат:** HTML-страница nginx.
+
+```bash
+# 5. Удалить тестовые ресурсы
+kubectl delete pod nginx-test
+```
+
+---
+
+## Troubleshooting
+
+### Нода не присоединяется к кластеру
+
+**Симптом:** После установки нода не появляется в `kubectl get nodes`.
+
+| Причина | Диагностика | Решение |
+|---------|-------------|---------|
+| Неправильный token | Логи: `sudo journalctl -u k3s-agent -f` | Проверь token, переустанови |
+| Firewall блокирует | `curl -k https://192.168.11.201:6443` | Открой порт 6443 на masters |
+| DNS не резолвит | `ping k3s-master-1` | Проверь /etc/hosts или DNS |
+
+### etcd не формирует кворум
+
+**Симптом:** `etcdctl endpoint health` показывает unhealthy.
+
+```bash
+# Проверить членов etcd
+sudo k3s kubectl exec -n kube-system \
+  $(sudo k3s kubectl get pods -n kube-system -l component=etcd -o name | head -1) \
+  -- etcdctl member list --write-out=table
+```
+
+| Причина | Диагностика | Решение |
+|---------|-------------|---------|
+| Порты 2379-2380 закрыты | `sudo ufw status` | `sudo ufw allow 2379:2380/tcp` |
+| Нода недоступна по сети | `ping 192.168.11.20X` | Проверь сеть, UFW |
+| etcd ещё стартует | `uptime` на ноде | Подожди 2-3 минуты |
+
+### Поды не запускаются на workers
+
+**Симптом:** Все поды на master нодах, workers пустые.
+
+```bash
+# Проверить taints
+kubectl describe node k3s-worker-1 | grep Taints
+```
+
+Если есть taints - убрать:
+```bash
+kubectl taint nodes k3s-worker-1 node.kubernetes.io/not-ready:NoSchedule-
+```
+
+---
+
+## Откат: удаление K3s
+
+Если нужно начать заново:
+
+**На master ноде:**
+```bash
+sudo /usr/local/bin/k3s-uninstall.sh
+```
+
+**На worker ноде:**
+```bash
+sudo /usr/local/bin/k3s-agent-uninstall.sh
+```
+
+**Что удаляется:**
+- Бинарники K3s
+- Systemd сервисы
+- Данные из `/var/lib/rancher/k3s/`
+- etcd данные (на masters)
+- Контейнеры и образы
+
+**⚠️ Внимание:** etcd снапшоты тоже удаляются. Если нужен бэкап:
+```bash
+# Перед удалением - сохранить снапшоты
+sudo cp -r /var/lib/rancher/k3s/server/db/snapshots/ ~/k3s-backup/
+```
+
+---
+
+## Итог
+
+**Что сделано:**
+- ✅ Сгенерирован token для кластера
+- ✅ Установлен K3s на 3 master ноды с embedded etcd
+- ✅ Добавлены 2 worker ноды
+- ✅ Настроен kubectl на локальной машине
+- ✅ Проверена работоспособность кластера
+
+**Что имеем:**
+- HA Control Plane - выдерживает падение 1 master ноды
+- 2 worker ноды для приложений
+- kubectl доступ с локальной машины
+- Встроенные компоненты: CoreDNS, metrics-server, local-path storage
+
+**Что ещё не настроено** (следующие статьи):
+- LoadBalancer (MetalLB) - для доступа к сервисам извне
+- Ingress Controller (Traefik) - для HTTP/HTTPS routing
+- SSL сертификаты (cert-manager) - для автоматического HTTPS
+- Мониторинг (Prometheus/Grafana) - для наблюдения за кластером
+
+---
+
+## Что дальше
+
+Кластер готов, но пока он изолирован от внешнего мира. Чтобы запускать реальные приложения с доступом извне, нужны:
+
+1. **MetalLB** - выдаёт IP-адреса для LoadBalancer сервисов
+2. **Traefik** - маршрутизирует HTTP/HTTPS трафик
+3. **cert-manager** - автоматически получает SSL сертификаты
+
+Это темы для следующей серии статей.
+
+**А пока можно:**
+- Поэкспериментировать с kubectl
+- Задеплоить тестовые приложения
+- Изучить как работает scheduling между нодами
+