Files
homelab-infra/BOOTSTRAP.md
T
karpenok bf4144a767
ansible-core-mon / deploy (push) Successful in 22s
ansible-core-net / deploy (push) Successful in 24s
ansible-core-secrets / deploy (push) Successful in 15s
ansible-opnsense / deploy (push) Successful in 6s
ansible-rus-central / deploy (push) Successful in 40s
docs & refactor: sync secrets docs and clean up env var lookups
2026-11-11 18:26:51 +07:00

11 KiB
Raw Blame History

Инструкция по развертыванию инфраструктуры (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
core-mon playbooks/core-mon.yml roles/core-mon/monitoring /opt/monitoring
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)
CT 903 netcore 192.168.1.108 core-mon Prometheus (:9090), Alertmanager (:9093), Grafana (:3000), Ntfy (:80)

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

Пути секретов:

  • /USER/ADMIN:
    • ADMIN_USER: имя администратора хоумлаба (по умолчанию karpenok).
    • ADMIN_PASSWORD: единый пароль администратора (Traefik Dashboard, Grafana, Ntfy, NetBird).
    • MAIL_ADMIN_USER: почта администратора (для Grafana, NetBird и алертов).
  • /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 или MAIL_ADMIN_USER.
    • NETBIRD_AUTH_SECRET: секрет auth.
    • NETBIRD_DATASTORE_KEY: 32-байтный ключ SQLite/datastore.
    • NETBIRD_SESSION_KEY: 32-байтный ключ веб-сессий.
    • NETBIRD_API_TOKEN: сервисный API-токен управления (создаётся и сохраняется пайплайном автоматически).
    • NETBIRD_SETUP_KEY: многоразовый ключ регистрации узлов (создаётся и сохраняется пайплайном автоматически).
    • (Параметры NETBIRD_ADMIN_NAME, NETBIRD_ADMIN_PASSWORD, NETBIRD_ADMIN_EMAIL наследуются из /USER/ADMIN).
  • /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. Гипервизоры и сеть

  1. Поднять OPNsense (192.168.1.1).
  2. Запустить Proxmox VE на netcore (192.168.1.100) и pve (192.168.1.2).
  3. Убедиться в доступности SSH по ключам root_home.

Шаг 2. Gitea & Gitea Actions (CT 109)

  1. Запустить CT 109 на pve.
  2. Запустить стек Gitea: docker compose up -d в каталоге Gitea.
  3. Проверить доступность UI по адресу http://192.168.1.217:3000.
  4. Убедиться, что раннер gitea-runner подключен и имеет статус idle.

Шаг 3. Хранилище секретов Infisical (CT 901)

Important

Мастер-ключи начальной загрузки Infisical (ENCRYPTION_KEY, AUTH_SECRET, POSTGRES_PASSWORD) являются первоисточником шифрования и физически не могут храниться внутри самого Infisical. Они должны быть надежно сохранены в личном оффлайн-менеджере паролей администратора (KeePassXC / Bitwarden / 1Password).

  1. Создать/запустить CT 901 (core-secrets, IP 192.168.1.102).
  2. Для первого старта вручную положить Compose Infisical в /opt/infisical/compose.yaml и подставить мастер-ключи из оффлайн-хранилища. Пайплайну эти ключи пока неоткуда прочитать.
  3. Запустить контейнеры: docker compose -f /opt/infisical/compose.yaml up -d.
  4. Проверить API: curl http://192.168.1.102:8080/api/status.
  5. В 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)

  1. Запустить пайплайн ansible-core-net в Gitea Actions. Первый прогон на новом CT должен быть полным: ручной запуск выполняет site.yml --limit core-net и ставит Docker ролью host.
  2. Раннер подключается напрямую к http://192.168.1.102:8080/api, забирает SSH-ключ раннера и секреты Authentik из /services/authentik. Если секретов Authentik ещё нет, раннер генерирует их и сохраняет в Infisical.
  3. Плейбук поднимает на CT 902 Traefik и Authentik. Authentik слушает только 127.0.0.1:9000; снаружи его публикует Traefik как https://auth.gunihome.ru. Blueprint создаёт группы admins и family, пользователей karpenok и ksynia и закрывает панель Traefik группой admins. Пароли blueprint не задаёт.
  4. Проверить 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

  1. Запустить пайплайн ansible-rus-central в Gitea Actions. Ручной запуск сверяет машину целиком. Push в roles/rus-central/netbird ставит только NetBird.
  2. Раннер считывает ключи из /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.
  3. Запустить пайплайн ansible-opnsense в Gitea Actions. Раннер обращается по HTTPS REST API к 192.168.1.1, проверяет/устанавливает плагин os-netbird, включает службу и регистрирует шлюз OPNsense на https://central.gunihome.ru:443 по NETBIRD_SETUP_KEY.