11 KiB
Инструкция по развертыванию инфраструктуры (Bootstrap Guide)
Плейбук называется машиной. В roles/<машина>/ лежат продукты этой машины: один каталог, один Compose, один путь /opt/<продукт>. База и кэш остаются внутри Compose этого продукта. Роль host стоит отдельно: она готовит любую машину и ни одному продукту не принадлежит.
Пайплайн подключается к машине, а применяет только роли, чьи файлы изменились (--tags). Роль host ставит пакеты, Docker и SSH. Она выполняется вместе со всеми продуктами машины, когда меняются плейбук, инвентарь или сама роль host, и при ручном запуске.
| Машина | Плейбук | Роли | Каталоги |
|---|---|---|---|
core-net |
playbooks/core-net.yml |
roles/core-net/traefik, roles/core-net/authentik |
/opt/traefik, /opt/authentik |
core-secrets |
playbooks/core-secrets.yml |
roles/core-secrets/infisical, roles/core-secrets/vaultwarden |
/opt/infisical, /opt/vaultwarden |
rus-central |
playbooks/rus-central.yml |
roles/rus-central/netbird |
/opt/netbird |
opnsense |
playbooks/opnsense.yml |
roles/opnsense/netbird |
REST API (192.168.1.1) |
Полная сверка одной машины: ansible-playbook playbooks/site.yml --limit <машина>. Gitea в автоматизацию не входит: без неё не запустить пайплайны.
1. Топология инфраструктуры
1.1. Физические узлы и гипервизоры (Proxmox VE)
| Узел | IP | Роль | SSH / Доступ |
|---|---|---|---|
| netcore | 192.168.1.100:8006 |
PVE Cluster Node / Core CTs | root@192.168.1.100 (LAN only) |
| pve | 192.168.1.2:8006 |
PVE Main Node / Services | root@192.168.1.2 (LAN only) |
| opnsense | 192.168.1.1 |
Маршрутизатор / Шлюз | Шлюз по умолчанию |
Terraform в этом репозитории описывает только узел netcore. Узел pve и CT 109 поднимаются отдельно.
1.2. Базовые управляющие контейнеры (LXC / Debian 13)
| CT ID | Хост PVE | IP | Имя хоста | Продукты |
|---|---|---|---|---|
| CT 109 | pve |
192.168.1.217 |
gitea |
Gitea (:3000), Postgres (:5432), Gitea Actions Runner (dind) |
| CT 901 | netcore |
192.168.1.102 |
core-secrets |
Infisical (:8080), Postgres, Redis, Vaultwarden (:8000) |
| CT 902 | netcore |
192.168.1.104 |
core-net |
Traefik (:80, :443), Authentik (127.0.0.1:9000) |
1.3. Внешние узлы
| Имя | IP | Роль | Стек |
|---|---|---|---|
| rus-central | 45.154.185.208 |
Внешний шлюз NetBird | /opt/netbird: NetBird и его собственный Traefik |
Домен панели NetBird задаётся в ansible/inventories/prod/host_vars/rus-central.yml.
2. Структура секретов в Infisical
Проект: infra (Slug: infra-xxx, Environment: prod)
API Endpoint (внутренний LAN): http://192.168.1.102:8080/api
Внешний URL: https://infisical.gunihome.ru
Пути секретов:
/ci-cd:RUNNER_SSH_KEY: приватный SSH-ключ раннера (ed25519) для деплоя на хосты.TF_STATE_TOKEN: токен доступа к HTTP State Backend Gitea.
/services/infisical:POSTGRES_PASSWORD: пароль БД Infisical.ENCRYPTION_KEY: 32-байтный hex-ключ шифрования хранилища.AUTH_SECRET: base64 секрет сессий/JWT Infisical.
/services/authentik:AUTHENTIK_SECRET_KEY: случайный ключ шифрования сессий Authentik.AUTHENTIK_POSTGRES_PASSWORD: пароль БД PostgreSQL Authentik.
/services/netbird:NETBIRD_LETSENCRYPT_EMAIL: почта для сертификата. Если секрета нет, берётсяletsencrypt_emailизgroup_vars/all.yml.NETBIRD_AUTH_SECRET: секрет auth.NETBIRD_DATASTORE_KEY: 32-байтный ключ SQLite/datastore.NETBIRD_SESSION_KEY: 32-байтный ключ веб-сессий.NETBIRD_ADMIN_EMAIL: почта первого суперпользователя NetBird.NETBIRD_ADMIN_NAME: имя суперпользователя NetBird.NETBIRD_ADMIN_PASSWORD: пароль суперпользователя NetBird (минимум 8 символов).NETBIRD_API_TOKEN: сервисный API-токен управления (создаётся и сохраняется пайплайном автоматически).NETBIRD_SETUP_KEY: многоразовый ключ регистрации узлов (создаётся и сохраняется пайплайном автоматически).
/services/opnsense:OPNSENSE_API_KEY: API-ключ администратора OPNsense.OPNSENSE_API_SECRET: API-секрет администратора OPNsense.
/proxmox/netcore:PROXMOX_ENDPOINT:https://192.168.1.100:8006/PROXMOX_API_TOKEN: токенroot@pam!terraform=UUID
Провайдер Proxmox сам дописывает /api2/json. В секрет его класть не нужно. Секреты /proxmox/pve этот репозиторий не читает: Terraform описывает только узел netcore.
3. Последовательность холодного старта (Cold Bootstrap)
При полном отказе всех систем порядок восстановления следующий:
Шаг 1. Гипервизоры и сеть
- Поднять OPNsense (
192.168.1.1). - Запустить Proxmox VE на
netcore(192.168.1.100) иpve(192.168.1.2). - Убедиться в доступности SSH по ключам
root_home.
Шаг 2. Gitea & Gitea Actions (CT 109)
- Запустить CT 109 на
pve. - Запустить стек Gitea:
docker compose up -dв каталоге Gitea. - Проверить доступность UI по адресу
http://192.168.1.217:3000. - Убедиться, что раннер
gitea-runnerподключен и имеет статусidle.
Шаг 3. Хранилище секретов Infisical (CT 901)
Important
Мастер-ключи начальной загрузки Infisical (
ENCRYPTION_KEY,AUTH_SECRET,POSTGRES_PASSWORD) являются первоисточником шифрования и физически не могут храниться внутри самого Infisical. Они должны быть надежно сохранены в личном оффлайн-менеджере паролей администратора (KeePassXC / Bitwarden / 1Password).
- Создать/запустить CT 901 (
core-secrets, IP192.168.1.102). - Для первого старта вручную положить Compose Infisical в
/opt/infisical/compose.yamlи подставить мастер-ключи из оффлайн-хранилища. Пайплайну эти ключи пока неоткуда прочитать. - Запустить контейнеры:
docker compose -f /opt/infisical/compose.yaml up -d. - Проверить API:
curl http://192.168.1.102:8080/api/status. - В Gitea Settings → Secrets добавить репозиторные секреты:
INFISICAL_CLIENT_ID(Machine Identity:ci-cd-runner)INFISICAL_CLIENT_SECRET
Дальше стек ведёт пайплайн ansible-core-secrets: Infisical в /opt/infisical, Vaultwarden в /opt/vaultwarden.
Шаг 4. Traefik и Authentik (CT 902)
- Запустить пайплайн
ansible-core-netв Gitea Actions. Первый прогон на новом CT должен быть полным: ручной запуск выполняетsite.yml --limit core-netи ставит Docker рольюhost. - Раннер подключается напрямую к
http://192.168.1.102:8080/api, забирает SSH-ключ раннера и секреты Authentik из/services/authentik. Если секретов Authentik ещё нет, раннер генерирует их и сохраняет в Infisical. - Плейбук поднимает на CT 902 Traefik и Authentik. Authentik слушает только
127.0.0.1:9000; снаружи его публикует Traefik какhttps://auth.gunihome.ru. Blueprint создаёт группыadminsиfamily, пользователейkarpenokиksyniaи закрывает панель Traefik группойadmins. Пароли blueprint не задаёт. - Проверить
https://auth.gunihome.ru,https://proxy.gunihome.ru,gitea.gunihome.ruиinfisical.gunihome.ru. Панель открывается учёткой из группыadmins. Первый запуск Authentik создаётakadmin; одноразовый пароль пишется в лог контейнераauthentik-server.akadminв группуadminsне входит.
Правка только роли traefik или только роли authentik ставит эту роль, без повторной подготовки машины.
Шаг 5. NetBird (rus-central) и связка с OPNsense
- Запустить пайплайн
ansible-rus-centralв Gitea Actions. Ручной запуск сверяет машину целиком. Push вroles/rus-central/netbirdставит только NetBird. - Раннер считывает ключи из
/services/netbird, деплоит стек в/opt/netbirdна45.154.185.208, автоматически регистрирует первого суперпользователя (POST /api/setup), создаёт сервисный токен (NETBIRD_API_TOKEN), группуhomelab-routers, маршрут к подсети192.168.1.0/24и многоразовый ключ установки (NETBIRD_SETUP_KEY), после чего сохраняетNETBIRD_API_TOKENиNETBIRD_SETUP_KEYв Infisical. - Запустить пайплайн
ansible-opnsenseв Gitea Actions. Раннер обращается по HTTPS REST API к192.168.1.1, проверяет/устанавливает плагинos-netbird, включает службу и регистрирует шлюз OPNsense наhttps://central.gunihome.ru:443поNETBIRD_SETUP_KEY.