Index

Управление инфраструктурой проекта через Ansible.

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

  1. Настройка окружения: 

    1
2
    cp env.example .env
# Отредактируйте .env с вашими нодами и SSH ключами

  2. Запуск playbook: 

    1
2
3
4
    make firewall              # Настройка firewall на всех нодах
make firewall-limit limit=master  # Только master ноды
make wireguard             # Настройка WireGuard full-mesh
make ping                  # Проверка подключения

Важно: Все конфигурационные файлы (inventory и WireGuard playbook) автоматически генерируются в entrypoint контейнера перед каждым запуском команды на основе .env файла.

Основные команды

Общие команды

  • make generate-configs - принудительная генерация всех конфигурационных файлов
  • make ping - проверка подключения к нодам
  • make inventory-list - просмотр inventory
  • make lint - проверка синтаксиса playbooks
  • make help - справка по командам

Firewall

  • make firewall - настройка firewall на всех нодах
  • make firewall-limit limit=<group> - настройка на конкретной группе/ноде

WireGuard Full-Mesh

  • make wireguard - настройка WireGuard full-mesh на всех нодах
  • make wireguard-limit limit=<group> - настройка WireGuard на конкретной группе/ноде
  • make wireguard-status - показать статус WireGuard на всех нодах
  • make wireguard-test - тестирование связности между нодами через WireGuard

WireGuard Client VPN

  • make wireguard-client-setup - настройка клиентского VPN на первом master ноде
  • make wireguard-client-config - генерация клиентской конфигурации WireGuard
  • make wireguard-client-status - проверка статуса клиентского подключения

Примечание: - Все конфигурационные файлы (inventory и WireGuard playbook) автоматически генерируются в entrypoint контейнера перед каждым запуском команды. - Генерация происходит через docker-entrypoint.sh, который вызывает python3 -m config_generator. - Файлы генерируются из шаблонов на основе данных из .env файла. - Сгенерированные файлы создаются только внутри контейнера и не попадают на хост (все bind mounts - read-only). - Редактировать можно только шаблоны (например, ansible/playbooks/wireguard.yml.j2), изменения применяются без пересборки образа.

WireGuard Full-Mesh Network

Проект использует WireGuard для создания полносвязной (full-mesh) приватной сети между всеми нодами.

Архитектура сети

  • Сеть: 10.99.0.0/24 (настраивается в .env)
  • Интерфейс: wg0
  • Порт: 51820/udp (настраивается в .env)
  • Топология: Full-mesh (каждая нода связана со всеми остальными)

Динамическое распределение IP-адресов

WireGuard IP-адреса задаются явно для каждой ноды в .env файле:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
NODE_1_NAME=master1
NODE_1_IP=192.168.1.10
NODE_1_TYPE=master
NODE_1_WIREGUARD_IP=10.99.0.11   # Явно указываем WireGuard IP
NODE_1_SSH_KEY=/path/to/key

NODE_2_NAME=master2
NODE_2_IP=192.168.1.11
NODE_2_TYPE=master
NODE_2_WIREGUARD_IP=10.99.0.12   # Любой IP в пределах вашей сети
NODE_2_SSH_KEY=/path/to/key

Преимущества явного указания IP: - Полный контроль над адресацией - Нет ограничений по количеству нод каждого типа - Легко понять, какой IP у какой ноды - Гибкость в выборе схемы адресации

Количество туннелей

Количество туннелей рассчитывается автоматически: n × (n-1) / 2, где n — количество нод.

Например: - 3 ноды → 3 туннеля - 6 нод → 15 туннелей - 10 нод → 45 туннелей

Генерация конфигураций

Все конфигурационные файлы генерируются автоматически пакетом config_generator:

  • Inventory (inventory.ini) - генерируется из нод в .env
  • WireGuard playbook (playbooks/wireguard.yml) - генерируется из шаблона wireguard.yml.j2 с автоматическим назначением IP-адресов

Структура пакета: - config_generator/parser.py - парсинг нод из переменных окружения - config_generator/inventory.py - генерация Ansible inventory - config_generator/wireguard.py - генерация WireGuard playbook - config_generator/main.py - главная функция

1
2
3
4
5
6
7
8
9
# Просто запустить любую команду (конфиги сгенерируются автоматически в entrypoint)
make wireguard
make firewall

# Принудительная генерация конфигов (если нужно запустить отдельно)
make generate-configs

# Или напрямую через Python модуль в контейнере
docker compose run --rm ansible python3 -m config_generator

Процесс настройки

  1. Генерация playbook: Автоматически создается playbook с правильными IP-адресами для всех нод
  2. Установка WireGuard: Playbook автоматически устанавливает WireGuard на всех нодах
  3. Генерация ключей: На каждой ноде генерируются приватный и публичный ключи (если их еще нет)
  4. Создание конфигурации: Для каждой ноды создается конфигурация с подключением ко всем остальным нодам
  5. Запуск: WireGuard запускается и включается в автозагрузку

Проверка работы

После настройки можно проверить связность:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Проверить статус WireGuard на всех нодах
make wireguard-status

# Протестировать ping между всеми нодами
make wireguard-test

# Или вручную на любой ноде (примеры с настройками по умолчанию):
ping <wireguard-ip-master1>  # например, 10.99.0.11
ping <wireguard-ip-master2>  # например, 10.99.0.12
ping <wireguard-ip-worker1>  # например, 10.99.0.21

Важные замечания

  • Firewall: Playbook автоматически настраивает firewall для разрешения порта 51820/udp
  • IP Forwarding: Автоматически включается на всех нодах
  • Ключи: Приватные ключи хранятся в /etc/wireguard/privatekey с правами 600
  • Конфигурация: Конфигурация хранится в /etc/wireguard/wg0.conf
  • Персистентность: Ключи не перегенерируются, если уже существуют (для сохранения конфигурации)

WireGuard Client VPN

Проект поддерживает настройку клиентского VPN для доступа к сервисам Kubernetes кластера извне.

Архитектура клиентского VPN

  • VPN Gateway: Первый master нод (автоматически определяется)
  • Клиентский IP: Указывается в .env файле (например, 10.99.0.100)
  • Доступная сеть:
  • WireGuard сеть: 10.99.0.0/24 (настраивается в .env)

Важно: Доступ к pod и service сетям Kubernetes не включен в VPN по соображениям безопасности. Доступ к сервисам кластера осуществляется через: - Port-forward (kubectl port-forward) - Ingress с IP whitelist (ограничение доступа только для VPN IP адресов) - LoadBalancer сервисы с доступом через WireGuard IP адреса

Настройка клиентского VPN

  1. Добавьте конфигурацию клиента в .env файл:
1
2
3
4
5
6
# WireGuard Client VPN Configuration
WIREGUARD_CLIENT_NAME=alex
WIREGUARD_CLIENT_IP=10.99.0.100
# Опционально: публичный IP или домен для подключения
# Если не указан, будет использован публичный IP первого master нода
WIREGUARD_CLIENT_PUBLIC_IP=

Важно: - Клиентский IP должен быть в пределах WireGuard сети (WIREGUARD_NETWORK_CIDR) - Клиентский IP не должен конфликтовать с IP адресами нод - Рекомендуется использовать IP из диапазона, не занятого нодами (например, 10.99.0.100-199)

  1. Настройте клиентский VPN:
1
make wireguard-client-setup

Эта команда: - Генерирует ключи для клиента (приватный/публичный) - Добавляет клиента как peer в конфигурацию первого master нода - Сохраняет клиентскую конфигурацию на сервере

  1. Сгенерируйте клиентскую конфигурацию:
1
make wireguard-client-config

Эта команда: - Читает клиентскую конфигурацию с сервера - Сохраняет её локально в infra/wireguard-clients/<client_name>.conf

  1. Импортируйте конфигурацию в WireGuard клиент:

  2. Windows: Импортируйте файл через WireGuard GUI

  3. Linux: sudo wg-quick up <client_name>.conf
  4. macOS: Импортируйте файл через WireGuard GUI

  5. Android/iOS: Отсканируйте QR-код или импортируйте файл

  6. Подключитесь к VPN:

После импорта конфигурации подключитесь к VPN через клиент WireGuard.

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

1
2
3
4
5
6
# Проверить статус клиентского подключения
make wireguard-client-status

# Проверить доступность нод кластера
ping 10.99.0.11  # WireGuard IP первого master нода
ping 10.99.0.21  # WireGuard IP worker нода

Использование после подключения

После подключения к VPN вы получите доступ к:

  • Нодам кластера: Через WireGuard сеть (10.99.0.0/24)
  • LoadBalancer сервисам: Если они используют IP адреса из WireGuard сети (MetalLB)

Доступ к сервисам Kubernetes:

Доступ к pod и service сетям не включен в VPN по соображениям безопасности. Используйте следующие методы:

  1. Port-forward (рекомендуется для разработки): 

    1
2
3
4
5
6
    # Kubernetes Dashboard
kubectl port-forward -n tech-dashboard svc/kubernetes-dashboard-web 8000:8000
# Затем откройте http://localhost:8000

# MinIO Console
kubectl port-forward -n tech-minio-tenants svc/minio-console 9001:9001

  2. Ingress с IP whitelist (для production): Настройте Ingress контроллер для разрешения доступа только с IP адресов WireGuard сети: 

    1
2
3
    # Пример аннотации для NGINX Ingress
annotations:
  nginx.ingress.kubernetes.io/whitelist-source-range: "10.99.0.0/24"

  3. LoadBalancer через MetalLB: Если MetalLB использует IP адреса из WireGuard сети, сервисы будут доступны напрямую через VPN.

Управление клиентскими конфигурациями

  • Ключи клиента: Хранятся на сервере в /etc/wireguard/clients/<client_name>/
  • Конфигурация клиента: Хранится на сервере в /etc/wireguard/clients/<client_name>/<client_name>.conf
  • Локальная копия: Сохраняется в infra/wireguard-clients/<client_name>.conf

Добавление дополнительных клиентов

Для добавления дополнительных клиентов:

  1. Измените WIREGUARD_CLIENT_NAME и WIREGUARD_CLIENT_IP в .env
  2. Запустите make wireguard-client-setup
  3. Сгенерируйте конфигурацию: make wireguard-client-config

Каждый клиент должен иметь уникальный IP адрес в WireGuard сети.

Kubernetes Cluster

Проект поддерживает автоматическую установку production-ready кластера Kubernetes с использованием Calico CNI.

Архитектура

  • Container Runtime: containerd
  • CNI Plugin: Calico (с Network Policies)
  • Network: WireGuard IP адреса (настраиваемая сеть, по умолчанию 10.99.0.0/24) для внутренней коммуникации
  • Pod Network CIDR: 10.244.0.0/16 (настраивается)
  • Service CIDR: 10.96.0.0/12 (настраивается)
  • High Availability: Поддержка нескольких master нод

Быстрая установка

Для полной установки кластера одной командой:

1
make k8s-full-install

Эта команда выполнит все шаги автоматически: 1. Подготовка всех нод (отключение swap, установка containerd, kubeadm) 2. Инициализация первого master 3. Установка Calico CNI 4. Присоединение дополнительных master нод (если есть) 5. Присоединение worker нод 6. Проверка кластера

Пошаговая установка

Если нужен больший контроль, выполняйте команды последовательно:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 1. Подготовка всех нод
make k8s-prerequisites

# 2. Инициализация первого master
make k8s-init

# 3. Установка CNI (обязательно перед присоединением нод!)
make k8s-cni

# 4. Присоединение дополнительных master нод (для HA, опционально)
make k8s-join-masters

# 5. Присоединение worker нод
make k8s-join-workers

# 6. Проверка кластера
make k8s-verify

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

1
2
3
4
5
# Быстрая проверка статуса кластера
make k8s-status

# Полная проверка здоровья кластера
make k8s-verify

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

Настройте параметры Kubernetes в .env файле:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# WireGuard VPN Configuration (только общие параметры сети)
WIREGUARD_NETWORK=10.99.0.0
WIREGUARD_PREFIX=24
WIREGUARD_PORT=51820

# Версия Kubernetes
KUBERNETES_VERSION=1.28.0

# CNI Plugin (calico или flannel)
CNI_PLUGIN=calico

# Сетевые настройки
POD_NETWORK_CIDR=10.244.0.0/16
SERVICE_CIDR=10.96.0.0/12

# Control Plane Endpoint (опционально, автоматически определяется)
# Используйте WireGuard IP первого master
CONTROL_PLANE_ENDPOINT=

Примечание: WireGuard IP каждой ноды задается индивидуально в определении ноды через NODE_X_WIREGUARD_IP.

Особенности реализации

Использование WireGuard сети

Все компоненты Kubernetes используют WireGuard IP адреса (настраиваемая сеть, по умолчанию 10.99.0.0/24) для коммуникации: - API Server advertise address - Kubelet node IP - etcd peer communication

Это обеспечивает: - Безопасную коммуникацию между нодами - Работу кластера через NAT и firewall - Возможность географически распределенного кластера

Отключение swap

Swap автоматически отключается на всех нодах, так как это требование Kubernetes: - Временное отключение: swapoff -a - Постоянное: комментирование записей в /etc/fstab - Проверка: автоматическая верификация после отключения

High Availability (HA)

Для production рекомендуется: - Минимум 3 master ноды (для кворума etcd) - Нечетное количество master нод (3, 5, 7) - Load balancer перед master нодами (MetalLB или внешний LB)

Playbooks автоматически: - Настраивают stacked etcd (etcd на тех же нодах, что и control plane) - Генерируют и распространяют сертификаты - Настраивают все компоненты для HA

Network Policies с Calico

Calico предоставляет: - Встроенные Kubernetes Network Policies - Расширенные Calico Network Policies - BGP маршрутизацию (опционально) - Высокую производительность

Пример использования Network Policy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: deny-all
  namespace: default
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress

Верификация кластера

Команда make k8s-verify проверяет:

  • ✓ Статус всех нод (Ready/NotReady)
  • ✓ Количество master и worker нод
  • ✓ Статус системных подов (kube-system namespace)
  • ✓ Работу Calico (calico-node, calico-kube-controllers)
  • ✓ DNS resolution из подов
  • ✓ Connectivity к API server
  • ✓ Связность между нодами через WireGuard
  • ✓ Срок действия сертификатов

Troubleshooting

Проверка статуса нод

1
2
3
4
5
6
# Из контейнера ansible
make k8s-status

# Напрямую на master ноде
kubectl get nodes -o wide
kubectl describe node <node-name>

Проверка подов

1
2
3
4
5
6
7
8
# Системные поды
kubectl get pods -n kube-system -o wide

# Calico поды
kubectl get pods -n kube-system -l k8s-app=calico-node

# Логи проблемного пода
kubectl logs -n kube-system <pod-name>

Проверка сети

1
2
3
4
5
6
7
8
# WireGuard статус на всех нодах
make wireguard-status

# Тест связности через WireGuard
make wireguard-test

# Проверка Calico
kubectl exec -n kube-system <calico-node-pod> -- calicoctl node status

Проверка сертификатов

1
2
# На master ноде
kubeadm certs check-expiration

Переустановка ноды

Если нода в проблемном состоянии:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# На master ноде, удалить ноду из кластера
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
kubectl delete node <node-name>

# На проблемной ноде, сбросить kubeadm
kubeadm reset -f
rm -rf /etc/cni/net.d
rm -rf /var/lib/kubelet
rm -rf /etc/kubernetes

# Затем заново присоединить ноду
make k8s-join-workers  # для worker
# или
make k8s-join-masters  # для master

Рекомендации по production

  1. Резервное копирование etcd:
  2. Регулярные снапшоты etcd
  3. Хранение в отдельном месте

  4. Тестирование восстановления

  5. Мониторинг:

  6. Установить Prometheus + Grafana
  7. Настроить алерты для критичных метрик

  8. Мониторить использование ресурсов

  9. Безопасность:

  10. Регулярное обновление Kubernetes
  11. Использование RBAC
  12. Pod Security Standards

  13. Network Policies для изоляции

  14. Обновления:

  15. Следовать официальной документации kubeadm
  16. Обновлять по одной ноде за раз
  17. Тестировать на staging окружении

Дополнительные компоненты

Установите дополнительные компоненты:

1
make k8s-addons

Это установит: - Metrics Server - сбор метрик ресурсов (CPU, память) для использования в kubectl top и HPA

Metrics Server версия настраивается через переменную окружения METRICS_SERVER_VERSION (по умолчанию v0.8.0).

Сброс кластера

⚠️ Внимание: Эта операция полностью удалит кластер Kubernetes!

1
make k8s-reset

Это выполнит: - Drain всех подов - Удаление всех нод из кластера - Полную очистку Kubernetes конфигураций - Очистку сетевых интерфейсов и правил iptables - Очистку контейнеров

После сброса можно заново установить кластер командой make k8s-full-install.

Структура проекта

 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
34
35
infra/
├── ansible/
│   ├── ansible.cfg
│   ├── inventory.ini                    # Генерируется автоматически
│   └── playbooks/
│       ├── firewall.yml                 # Настройка firewall
│       ├── install-tools.yml            # Установка утилит
│       ├── wireguard/
│       │   ├── wireguard.yml            # Генерируется из .j2
│       │   ├── wireguard.yml.j2         # Шаблон WireGuard playbook
│       │   └── wireguard-test.yml.j2    # Шаблон тестов
│       └── kubernetes/
│           ├── prerequisites.yml        # Подготовка нод
│           ├── init-master.yml          # Инициализация мастера
│           ├── join-masters.yml         # Присоединение мастеров
│           ├── join-workers.yml         # Присоединение воркеров
│           ├── cni-calico.yml           # Установка Calico
│           ├── verify.yml               # Проверка кластера
│           ├── addons.yml               # Дополнительные компоненты
│           ├── reset-cluster.yml        # Сброс кластера
│           └── templates/
│               └── kubeadm-config.yaml.j2  # Шаблон конфига kubeadm
├── config_generator/                    # Python пакет для генерации конфигов
│   ├── __init__.py
│   ├── main.py                          # Точка входа
│   ├── parser.py                        # Парсинг нод из .env
│   ├── inventory.py                     # Генерация inventory
│   └── wireguard.py                     # Генерация WireGuard playbooks
├── scripts/                             # Вспомогательные скрипты
├── docker-compose.yml                   # Docker Compose конфигурация
├── docker-entrypoint.sh                 # Entrypoint контейнера
├── Dockerfile                           # Docker образ с Ansible
├── Makefile                             # Команды для управления
├── env.example                          # Пример конфигурации
└── README.md                            # Документация

Принципы работы

Генерация конфигураций

Все конфигурационные файлы генерируются автоматически перед каждым запуском команды:

  1. Inventory (inventory.ini) - создается на основе нод из .env
  2. WireGuard playbook (wireguard.yml) - генерируется из шаблона с автоматическим назначением IP
  3. Kubeadm config - генерируется с учетом WireGuard IP адресов

Идемпотентность

Все playbooks идемпотентны - их можно запускать многократно без побочных эффектов:

  • Проверяют текущее состояние перед изменениями
  • Пропускают уже выполненные шаги
  • Безопасны для повторного применения

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

  • SSH ключи монтируются read-only
  • Приватные ключи WireGuard имеют права 600
  • Все коммуникации через зашифрованный WireGuard туннель
  • Поддержка SSH ключей с парольной фразой

Гибкость

  • Нет хардкода нод - используются группы (master/worker)
  • Переменные окружения для всех настроек
  • Шаблоны для кастомизации playbooks
  • Поддержка разных OS (Debian/Ubuntu, RedHat/CentOS)

FAQ

Как добавить новую ноду?

  1. Добавьте ноду в .env: 

    1
2
3
4
5
    NODE_4_NAME=worker3
NODE_4_IP=192.168.1.14
NODE_4_TYPE=worker
NODE_4_WIREGUARD_IP=10.99.0.23  # Выберите свободный IP
NODE_4_SSH_KEY=/path/to/key

  2. Настройте инфраструктуру на новой ноде: 

    1
2
    make firewall
make wireguard

  3. Присоедините к Kubernetes кластеру: 

    1
    make k8s-join-workers

Как удалить ноду из кластера?

1
2
3
4
5
6
# На master ноде
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
kubectl delete node <node-name>

# На удаляемой ноде
kubeadm reset -f

Можно ли использовать для production?

Да, но учтите: - Минимум 3 master ноды для HA - Регулярные бэкапы etcd - Мониторинг и алерты - Тестирование на staging - План disaster recovery

Как обновить Kubernetes?

Следуйте официальной документации kubeadm для обновления версии. Обновляйте по одной ноде за раз.

Почему WireGuard IP вместо публичных?

WireGuard обеспечивает: - Безопасную зашифрованную коммуникацию - Работу через NAT и firewall - Возможность географически распределенного кластера - Изоляцию кластера от публичной сети