ADD NODE

Этот гайд описывает процесс добавления новой ноды (Master или Worker) в существующий Kubernetes кластер через Ansible.

1. Подготовка SSH доступа

Ansible должен иметь доступ к ноде по SSH ключу.

  1. Добавьте ваш публичный ключ на ноду: 
    1
    ssh-copy-id -i ~/.ssh/id_rsa.pub root@<NEW_NODE_IP>
  2. Проверьте подключение: 
    1
    ssh root@<NEW_NODE_IP>

2. Обновление конфигурации (.env)

Отредактируйте файл infra/.env, добавив параметры новой ноды. Используйте следующий свободный индекс NODE_X.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Пример для новой worker ноды
NODE_4_NAME=worker3
NODE_4_IP=1.2.3.4                 # Публичный IP
NODE_4_TYPE=worker                # 'master' или 'worker'
NODE_4_WIREGUARD_IP=10.99.0.23    # Свободный IP в сети WireGuard
NODE_4_SSH_KEY=/root/.ssh/id_rsa  # Путь к ключу (относительно корня проекта или полный путь в контейнере)
NODE_4_NODE_TYPE=compute          # 'control-plane' для master, 'compute' для worker
NODE_4_DISK_SIZE=100gb            # Для меток (labels)
NODE_4_MEMORY_TYPE=standard       # 'standard' или 'highmem' (опционально)
NODE_4_DISK_TYPE=ssd              # 'ssd' или 'hdd' (опционально)

Важно: Убедитесь, что NODE_X_WIREGUARD_IP уникален и находится в пределах WIREGUARD_NETWORK_CIDR (обычно 10.99.0.0/24).

3. Проверка подключения к новой ноде

После добавления конфигурации в .env, проверьте, что Ansible может подключиться к новой ноде.

1
2
# Замените worker3 на имя, указанное в NODE_X_NAME
make ping

Ожидаемый результат: Все ноды, включая новую, отвечают pong.

Что проверять: - Новая нода доступна по SSH - SSH ключ работает корректно - Ansible inventory обновился автоматически (конфиг генерируется перед каждой командой)

4. Настройка базовой инфраструктуры

4.1. Настройка Firewall

1
2
# Замените worker3 на имя, указанное в NODE_X_NAME
make firewall-limit limit=worker3

Ожидаемый результат: Firewall настроен на новой ноде, необходимые порты открыты.

Что проверять: - Firewall активен - Порты для WireGuard (51820/udp) и Kubernetes открыты

4.2. Настройка WireGuard (Full-Mesh)

Важно: Эта команда перенастроит WireGuard на всех нодах, чтобы они узнали о новом участнике и обновили свои пиры.

1
make wireguard

Ожидаемый результат: WireGuard перенастроен на всех нодах, новая нода добавлена в full-mesh сеть.

Время выполнения: ~2-5 минут

4.3. Проверка WireGuard связности

1
make wireguard-test

Ожидаемый результат: Все ноды (включая новую) могут связаться друг с другом через WireGuard сеть.

5. Подготовка Kubernetes (Prerequisites)

Установка containerd, kubeadm, kubelet, kubectl и настройка ОС (отключение swap, настройка модулей ядра и т.д.).

1
2
# Ограничиваем выполнение только новой нодой
make k8s-prerequisites-limit limit=worker3

Ожидаемый результат: Нода подготовлена для присоединения к Kubernetes кластеру.

Время выполнения: ~5-10 минут (зависит от скорости интернета)

Что происходит: - Отключение swap - Установка containerd - Установка kubeadm, kubelet, kubectl - Настройка модулей ядра и sysctl параметров - Настройка containerd для работы с systemd cgroup driver

6. Присоединение к кластеру

Вариант А: Если это Worker нода

1
make k8s-join-workers-limit limit=worker3

Ожидаемый результат: Worker нода успешно присоединена к кластеру.

Время выполнения: ~2-5 минут

Что происходит: 1. Получение join токена с первого master нода 2. Присоединение к кластеру через kubeadm join 3. Запуск kubelet

Вариант Б: Если это Master нода

1
make k8s-join-masters-limit limit=master2

Ожидаемый результат: Master нода успешно присоединена к кластеру в качестве control-plane.

Время выполнения: ~5-10 минут

Что происходит: 1. Получение сертификатов и join токена с первого master нода 2. Присоединение к кластеру как control-plane через kubeadm join --control-plane 3. Установка kubectl конфигурации 4. Запуск kubelet и control-plane компонентов

7. Проверка присоединения к кластеру

1
2
3
make k8s-status
# или
kubectl get nodes -o wide

Ожидаемый результат: Новая нода появилась в списке нод в статусе Ready.

Что проверять: - Нода в статусе Ready - Версия Kubernetes совпадает с остальными нодами - Поды системных компонентов запущены (если это master нода)

8. Пост-настройка

8.1. Применение меток (labels) и taints

Важно: Этот шаг необходим для корректной работы планировщика Kubernetes и правильного распределения подов.

1
make k8s-prepare-nodes-limit limit=worker3

Ожидаемый результат: На ноду применены необходимые метки и taints.

Что происходит:

Для Worker нод: - Добавляется метка node-role.kubernetes.io/worker=true - Добавляются кастомные метки из .env (например, node-type, disk-type, disk-size, memory-type)

Для Master нод: - Добавляется метка node-role.kubernetes.io/control-plane=true - Добавляется taint node-role.kubernetes.io/control-plane:NoSchedule - Добавляются кастомные метки из .env

Проверка: 

1
2
3
kubectl get nodes --show-labels
kubectl describe node worker3 | grep -A5 Labels
kubectl describe node worker3 | grep -A5 Taints

8.2. Подготовка для Longhorn (только для Worker нод)

Если нода будет использоваться для хранения данных (Persistent Volume Claims через Longhorn):

1
make longhorn-prepare-nodes-limit limit=worker3

Ожидаемый результат: Нода подготовлена для работы с Longhorn.

Что происходит: - Установка open-iscsi и nfs-common - Настройка и запуск iscsid сервиса - Установка дополнительных утилит (curl, findmnt, grep, awk, blkid, lsblk)

Примечание: Этот шаг обязателен, если вы планируете размещать PVC на этой ноде. Пропуск этого шага может привести к ошибкам при создании volumes.

8.3. Финальная проверка

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Проверка статуса всех нод
make k8s-status

# Более детальная проверка
kubectl get nodes -o wide

# Проверка системных подов
kubectl get pods -n kube-system -o wide

# Проверка подов на новой ноде
kubectl get pods -A --field-selector spec.nodeName=worker3

# Проверка меток и taints
kubectl describe node worker3

9. Верификация кластера (опционально)

После добавления ноды рекомендуется запустить полную верификацию кластера:

1
make k8s-verify

Ожидаемый результат: Все проверки прошли успешно.

Что проверяется: - Все ноды в статусе Ready - Все системные поды в namespace kube-system работают - CoreDNS работает корректно - Metrics Server доступен (если установлен) - Сетевая связность между подами

Troubleshooting

Ошибка SSH

Проблема: Ansible не может подключиться к ноде.

Решение: - Проверьте доступность ноды: ping <NEW_NODE_IP> - Проверьте SSH подключение: ssh root@<NEW_NODE_IP> - Проверьте правильность пути к ключу в .env - Проверьте права на ключ: chmod 600 /path/to/key

WireGuard не поднимается

Проблема: WireGuard интерфейс не создается или нет связности.

Решение: - Убедитесь, что порт 51820/udp открыт в firewall: make firewall-limit limit=worker3 - Проверьте статус WireGuard: make wireguard-status - Проверьте конфигурацию: ssh root@<NEW_NODE_IP> "cat /etc/wireguard/wg0.conf" - Проверьте логи: ssh root@<NEW_NODE_IP> "journalctl -u wg-quick@wg0 -n 50"

Нода в статусе NotReady

Проблема: После присоединения нода остается в статусе NotReady.

Решение: - Проверьте логи kubelet: ssh root@<NEW_NODE_IP> "journalctl -u kubelet -f" - Проверьте статус containerd: ssh root@<NEW_NODE_IP> "systemctl status containerd" - Проверьте сетевую связность через WireGuard: make wireguard-test - Проверьте, что CNI плагин (Calico) установлен: kubectl get pods -n kube-system | grep calico

Ошибка при присоединении к кластеру

Проблема: kubeadm join завершается с ошибкой.

Решение: - Проверьте доступность первого master нода - Проверьте, что порт 6443 открыт на master нодах - Попробуйте сбросить состояние на новой ноде: ssh root@<NEW_NODE_IP> "kubeadm reset -f" - Затем повторите присоединение

Labels или taints не применяются

Проблема: make k8s-prepare-nodes-limit выполняется, но метки не появляются.

Решение: - Убедитесь, что kubectl доступен на master ноде - Проверьте имя ноды в кластере: kubectl get nodes - Проверьте, что переменные в .env заданы корректно (например, NODE_X_NODE_TYPE, NODE_X_DISK_SIZE) - Запустите плейбук с флагом verbose: docker compose run --rm ansible ansible-playbook -i inventory.ini playbooks/kubernetes/k8s-prepare-nodes.yml --limit worker3 -vvv

Longhorn не работает на новой ноде

Проблема: PVC не создаются или остаются в состоянии Pending.

Решение: - Убедитесь, что вы выполнили make longhorn-prepare-nodes-limit limit=worker3 - Проверьте статус open-iscsi: ssh root@<NEW_NODE_IP> "systemctl status iscsid" - Проверьте логи Longhorn manager: kubectl logs -n longhorn-system -l app=longhorn-manager - Проверьте, что нода видна в Longhorn UI (если установлен)

Полный пример добавления worker ноды

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# 1. Добавьте SSH ключ
ssh-copy-id -i ~/.ssh/id_rsa.pub root@192.168.1.30

# 2. Обновите .env (добавьте NODE_7_* переменные)

# 3. Проверьте подключение
make ping

# 4. Настройте firewall
make firewall-limit limit=worker3

# 5. Настройте WireGuard (на всех нодах)
make wireguard

# 6. Проверьте связность
make wireguard-test

# 7. Подготовьте Kubernetes
make k8s-prerequisites-limit limit=worker3

# 8. Присоедините к кластеру
make k8s-join-workers-limit limit=worker3

# 9. Примените метки и taints
make k8s-prepare-nodes-limit limit=worker3

# 10. Подготовьте для Longhorn
make longhorn-prepare-nodes-limit limit=worker3

# 11. Проверьте статус
make k8s-status
kubectl get nodes -o wide
kubectl describe node worker3

Полный пример добавления master ноды

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 1. Добавьте SSH ключ
ssh-copy-id -i ~/.ssh/id_rsa.pub root@192.168.1.40

# 2. Обновите .env (добавьте NODE_8_* переменные, укажите NODE_8_MASTER_NODE=master-4)

# 3. Проверьте подключение
make ping

# 4. Настройте firewall
make firewall-limit limit=master4

# 5. Настройте WireGuard (на всех нодах)
make wireguard

# 6. Проверьте связность
make wireguard-test

# 7. Подготовьте Kubernetes
make k8s-prerequisites-limit limit=master4

# 8. Присоедините к кластеру как control-plane
make k8s-join-masters-limit limit=master4

# 9. Примените метки и taints
make k8s-prepare-nodes-limit limit=master4

# 10. Проверьте статус
make k8s-status
kubectl get nodes -o wide
kubectl describe node master4
kubectl get pods -n kube-system -o wide | grep master4