Добавил серию Blog 1-5 части. Подправил настройки и внешний вид сайта

This commit is contained in:
2026-02-19 19:49:44 +00:00
parent 3ecd02c4ab
commit b05195a735
238 changed files with 53664 additions and 1026 deletions
@@ -0,0 +1,647 @@
---
title: "K3s HA для homelab: Ставим K3s HA кластер"
date: 2025-11-02
draft: false
description: "Один curl-скрипт на каждую ноду - и через 15 минут у вас работающий HA-кластер. Устанавливаем K3s на 3 master и 2 worker ноды, настраиваем kubectl."
tags: ["kubernetes", "k3s", "homelab", "installation", "ha", "etcd", "devops"]
series: ["K3s HA кластер для homelab"]
series_order: 3
---
Инфраструктура готова: 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 между нодами