Files
homelab-infra/BOOTSTRAP.md
T
karpenokandCursor 321c78fc27
ansible-core-mon / deploy (push) Successful in 26s
ansible-rus-central / deploy (push) Successful in 54s
ansible-core-net / deploy (push) Successful in 58s
ansible-core-secrets / deploy (push) Successful in 18s
ansible-ger-nod-02 / deploy (push) Successful in 1m18s
ansible-opnsense / deploy (push) Successful in 8s
fix(core-git): не терять образ раннера и не деплоить из-за пустого файла
Архив homelab-ansible хранится на диске CT, проверка раннера вынесена в отдельную кнопку, cAdvisor смотрит свой порт.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 23:09:05 +07:00

25 KiB
Raw Blame History

Инструкция по развертыванию инфраструктуры (Bootstrap Guide)

Плейбук называется машиной. В roles/<машина>/ лежат продукты этой машины: один каталог, один Compose, один путь /opt/<продукт>. База и кэш остаются внутри Compose этого продукта. Роль host стоит отдельно: она готовит любую машину и ни одному продукту не принадлежит.

Пайплайн подключается к машине, а применяет только роли, чьи файлы изменились (--tags). Роль host ставит пакеты, Docker и SSH. Она вызывается только из playbooks/host.yml, который подключает site.yml. Полный прогон и ручной запуск идут через site.yml --limit <машина>, поэтому подготовка машины выполняется один раз вместе с продуктами. Плейбук отдельной машины продукты ставит, машину не готовит.

Машина Плейбук Роли Каталоги
core-net playbooks/core-net.yml roles/core-net/traefik; roles/core-net/netbird; roles/core-net/remnawave; roles/core-net/vmagent; roles/core-net/authentik (опц., по умолчанию выкл.) /opt/traefik; клиент NetBird; /opt/remnawave; /opt/vmagent; /opt/authentik (если включён)
core-secrets playbooks/core-secrets.yml roles/core-secrets/infisical, roles/core-secrets/vaultwarden, roles/core-secrets/cadvisor /opt/infisical, /opt/vaultwarden, /opt/cadvisor
core-mon playbooks/core-mon.yml roles/core-mon/monitoring /opt/monitoring (VictoriaMetrics, vmalert, Grafana)
core-git playbooks/core-git.yml roles/core-git/gitea, roles/core-git/cadvisor /opt/gitea, /opt/cadvisor
rus-central playbooks/rus-central.yml roles/rus-central/netbird, roles/rus-central/cadvisor /opt/netbird, /opt/cadvisor
ger-nod-02 playbooks/ger-nod-02.yml roles/ger-nod-02/netbird; roles/ger-nod-02/remnanode; roles/ger-nod-02/vmagent клиент NetBird; /opt/remnanode; /opt/vmagent
opnsense playbooks/opnsense.yml roles/opnsense/netbird; roles/opnsense/xray REST API (192.168.1.1:4433)

Полная сверка одной машины: ansible-playbook playbooks/site.yml --limit <машина>. Боевой Gitea после cutover — core-git (192.168.1.105). Пайплайны клонируют с http://192.168.1.105:3000. CT 109 на pve оставлен как rollback, стек на нём остановлен — не удалять, пока не подтверждён стабильный прогон.

core-git пайплайном не ставится. Раннер живёт на этой машине: workflow, который деплоит её или делает terraform apply по CT 904, оборвёт сам себя. Плейбук core-git.yml и apply ресурса core_git — с рабочей станции. deploy-machine.sh core-git завершается с ошибкой. Terraform из Actions считает netcore с -exclude=proxmox_virtual_environment_container.core_git.


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, в том числе CT 904. Apply CT 904 с раннера запрещён, см. выше. CT 109 на pve оставлен как rollback.

1.2. Базовые управляющие контейнеры (LXC / Debian 13)

CT ID Хост PVE IP Имя хоста Продукты
CT 109 pve 192.168.1.217 gitea / DNS gitea-old Старый стек остановлен (rollback). Не удалять до проверки
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); Remnawave Panel (127.0.0.1:3000) + Subscription (127.0.0.1:3010); клиент NetBird (нужен /dev/net/tun); Authentik (127.0.0.1:9000) — опционально, по умолчанию выкл.
CT 903 netcore 192.168.1.108 core-mon VictoriaMetrics (:8428), vmalert (127.0.0.1:8880), Alertmanager (:9093), Grafana (:3000), Ntfy (:80)
CT 904 netcore 192.168.1.105 core-git Gitea (:3000, git SSH :222), Postgres, Actions Runner (dind); cAdvisor (:9101)

1.3. Внешние узлы

Имя IP Роль Стек
rus-central 45.154.185.208 Внешний шлюз NetBird /opt/netbird: NetBird и его собственный Traefik
ger-nod-02 150.241.64.209 Remnawave Node (DE) + SelfSteal /opt/remnanode: remnanode + nginx (yali.gunis.top)

Домен панели NetBird задаётся в ansible/inventories/prod/host_vars/rus-central.yml.

Старая панель на Голове (remna.gunihome.ru) не входит в эту автоматизацию и не трогается.

ansible/roles/core-net/traefik/files/dynamic/ — известный бардак: плоский список старых и новых маршрутов. Имена вроде tv.yml — это поддомены, а не описание сервиса. Каталог разбирается после того, как вся старая инфраструктура переедет на роли машин. До этого файлы оттуда не переименовывать и не раскладывать. Подробности — в README.md внутри каталога.


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.
    • CLOUDFLARE_API: API-токен Cloudflare (Zone DNS Edit для gunis.top, DNS-01 сертификаты ноды).
  • /services/gitea:
    • POSTGRES_USER / POSTGRES_DB / POSTGRES_PASSWORD: учётка БД (пароль же в GITEA__database__PASSWD). До cutover — значения боевого инстанса на CT 109.
    • GITEA_RUNNER_REGISTRATION_TOKEN: опционально; после переноса runner-data/.runner не нужен.
  • /VPS:
    • PASS_GER_NOD_02: первичный root-пароль ger-nod-02 (только bootstrap; после роли host вход по ключу).
  • /services/infisical:
    • POSTGRES_PASSWORD: пароль БД Infisical.
    • ENCRYPTION_KEY: 32-байтный hex-ключ шифрования хранилища.
    • AUTH_SECRET: base64 секрет сессий/JWT Infisical.
  • /services/authentik (нужен только если включите 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: многоразовый ключ регистрации роутеров (homelab-routers). Панель и ноды им не пользуются.
    • NETBIRD_REMNAWAVE_SETUP_KEY: многоразовый ключ remnawave-peers для core-net и ger-nod-02. В группу роутеров не входит.
    • (Параметры NETBIRD_ADMIN_NAME, NETBIRD_ADMIN_PASSWORD, NETBIRD_ADMIN_EMAIL наследуются из /USER/ADMIN).
  • /services/opnsense:
    • OPNSENSE_API_KEY: API-ключ администратора OPNsense.
    • OPNSENSE_API_SECRET: API-секрет администратора OPNsense.
  • /services/opnsense-xray:
    • Ключи по именам из ansible/roles/opnsense/xray/files/instances.yml (например FIN_01): полные vless:// ссылки подписок Xray. Роль opnsense/xray конвертирует их в outbound и синхронизирует инстансы плагина os-xray через API; активна ровно одна (active: true).
  • /services/remnawave:
    • REMNAWAVE_ADMIN_USER / REMNAWAVE_ADMIN_PASSWORD: логин панели (Remnawave v3 требует пароль ≥24 с upper+lower+digit). Генерируются пайплайном при первом прогоне; не путать с /USER/ADMIN.
    • REMNAWAVE_APP_SECRET, REMNAWAVE_POSTGRES_PASSWORD, REMNAWAVE_METRICS_PASS, REMNAWAVE_WEBHOOK_SECRET_HEADER: генерируются пайплайном при первом прогоне, если пусто.
    • REMNAWAVE_API_TOKEN: сервисный API-токен панели (infra-automation, scopes *), создаётся и сохраняется пайплайном (при сбое — создать в UI и положить сюда вручную).
    • REMNANODE_SECRET_KEY: SECRET_KEY ноды Ger-nod-02 (GET /api/keygen/), сохраняется пайплайном.
    • XRAY_CHECKER_SUBSCRIPTION_URL: ссылка подписки пользователя homelab для Xray Checker на core-mon. В лог не пишется.
  • /proxmox/netcore:
    • PROXMOX_ENDPOINT: https://192.168.1.100:8006/
    • PROXMOX_API_TOKEN: токен root@pam!terraform=UUID

Провайдер Proxmox сам дописывает /api2/json. В секрет его класть не нужно. Секреты /proxmox/pve этот репозиторий не читает: Terraform описывает только узел netcore.

2.1. Сервисы для агентов (Agent Vault)

Продукт, который сам создаёт себе токен, сам же регистрирует его в Access Bundle. За это отвечает общая роль agent_vault_service (стоит отдельно, как host): она ищет сервис по имени в бандле, создаёт его при отсутствии и обновляет креденшл при наличии. Ротация токена на каждом прогоне поэтому не ломает доступ агента.

Вызов из роли продукта — после того как секрет сохранён в Infisical:

- name: Зарегистрировать панель Remnawave в Agent Vault
  ansible.builtin.include_role:
    name: agent_vault_service
  vars:
    agent_vault_service_name: remnawave-panel
    agent_vault_service_host: "{{ remnawave_panel_domain }}:443"  # имя, доступное агенту, не 127.0.0.1
    agent_vault_service_paths: ["/api"]
    agent_vault_service_methods: [GET, POST]
    agent_vault_secret_path: /services/remnawave
    agent_vault_secret_key: REMNAWAVE_API_TOKEN

Креденшл роль читает из Infisical сама (infisical secrets get --plain), поэтому токен не проходит через переменные Ansible и не может попасть в лог прогона.

По умолчанию прокси подставляет Authorization: Bearer <токен>. Если сервис ждёт другой префикс (NetBird — Authorization: Token <токен>), задайте agent_vault_service_header_prefix: Token; для Basic-авторизации креденшл задаётся типом basic.

По умолчанию сервис кладётся в бандл homelab-ops проекта homelab-agents. Запись идёт только в Infisical: прокси подхватывает изменение на следующем poll (60 с), агента перезапускать не нужно. Идентичность пайплайна должна быть Admin в этом проекте Agent Vault — иначе регистрация вернёт 403.

На версии Infisical v0.167.7 сервисы создаются bundle-scoped маршрутом POST /api/v1/agent-vault/access-bundles/<id>/services; описанного в документации POST /api/v1/agent-vault/services там ещё нет.


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 904 core-git)

С рабочей станции, не из Actions.

  1. Поднять CT 904 (192.168.1.105), стек в /opt/gitea (docker compose up -d).
  2. UI: https://gitea.gunihome.ru или http://192.168.1.105:3000.
  3. Git SSH: gitea.internal:222. DNS: gitea.internal → .105 (старый CT 109 — gitea-old.internal).
  4. Раннер homelab = idle. Образ задач homelab-ansible:latest лежит архивом в /opt/gitea/images/ и подмонтирован в раннер. Если внутренний диск раннера очистили, /opt/gitea/ensure-runner-image.sh загружает образ из архива. В Docker Hub этого образа нет.
  5. В /etc/pve/lxc/904.conf на netcore должна быть строка lxc.apparmor.profile: unconfined. Проверка со станции: scripts/check-core-git-lxc.sh. Без неё задачи падают сразу, хотя сайт Gitea открывается. После смены строки контейнер надо перезагрузить.
  6. Проверка раннера — кнопка workflow runner-smoke, не правка файлов деплоя.
  7. Rollback: CT 109, каталог /root/docker/gitea/, файл запуска compose.yaml (ссылка на docker compose.yml). Стек не запущен. Поднятие: docker compose up -d в этом каталоге, Traefik и DNS вернуть на .217. Не удалять, пока новая машина спокойно работает.

Шаг 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 (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-ключ раннера и ADMIN_* из Infisical. Панель Traefik (proxy.gunihome.ru) закрывается BasicAuth из /USER/ADMIN.
  3. Плейбук поднимает Traefik на CT 902. Роль Authentik в плейбуке есть, но по умолчанию выключена (authentik_enabled=false в defaults и в CI): compose не стартует, стек на cold bootstrap не нужен.
  4. Проверить https://proxy.gunihome.ru, https://gitea.gunihome.ru и https://infisical.gunihome.ru.

Правка только роли traefik ставит эту роль, без повторной подготовки машины.

Authentik (опционально, не часть cold bootstrap)

Стек оставляем в репозитории на будущее: SSO/forwardAuth для выбранных приложений, не для всего edge сразу.

Чтобы включить:

  1. Положить секреты в Infisical /services/authentik (AUTHENTIK_SECRET_KEY, AUTHENTIK_POSTGRES_PASSWORD).
  2. Убрать принудительный -e authentik_enabled=false из ansible/ci/deploy-machine.sh (или передать authentik_enabled=true при ручном прогоне) и выставить authentik_enabled: true.
  3. Прогнать ansible-core-net (или --tags authentik): стек слушает 127.0.0.1:9000, снаружи — https://auth.gunihome.ru. Blueprints заводят группы admins/family и пользователей karpenok/ksynia; пароли blueprint не задаёт. Первый запуск создаёт akadmin (пароль в логе authentik-server).
  4. На нужных роутерах Traefik повесить middleware authentik (forwardAuth из roles/core-net/traefik/files/dynamic/authentik.yml) — точечно, не на все сервисы.

Remnawave Panel + Subscription (на core-net)

Новая панель рядом с Traefik. Старый remna.gunihome.ru на Голове не затрагивается.

  1. В Infisical положить:
    • /ci-cd → CLOUDFLARE_API
    • /VPS → PASS_GER_NOD_02 (пароль нового VPS)
  2. Запустить ansible-core-net (полный прогон или --tags remnawave после того, как Traefik уже с роутами rw/sub).
  3. Роль поднимает /opt/remnawave (panel+db+redis) и /opt/remnawave/subscription, создаёт REMNAWAVE_ADMIN_*, каждый прогон перевыпускает API-токен infra-automation и кладёт его в Infisical (старый сразу недействителен). Config profile DE-Yali, сквад Default-Squad на inbound Steal-Yali, нода Ger-nod-02, host yali.gunis.top. Пользователи — файл ansible/roles/core-net/remnawave/files/users.yml (добавление/изменение/удаление = правка файла). Когда peer ger-nod-02 уже есть в NetBird, адрес ноды в панели меняется на его NetBird IP. Пока peer нет, остаётся 150.241.64.209. Ссылка подписки homelab пишется в XRAY_CHECKER_SUBSCRIPTION_URL и в лог не попадает.
  4. Проверить https://rw.gunihome.ru и https://sub.gunihome.ru.

Important

Логи: шаги bootstrap и ошибки API видны в CI. Значения ключей туда не пишутся: stdout — только статус, секреты лежат в /opt/remnawave/.bootstrap-secrets.json (0600). no_log только у чтения этого файла, записи в Infisical и шаблона .env. В stderr поля token / SECRET_KEY / privateKey / shortUuid / пароли клиентов заменяются на [REDACTED].

Шаг 4b. Remnawave Node ger-nod-02 (SelfSteal)

  1. После успешного ansible-core-net (чтобы в Infisical был REMNANODE_SECRET_KEY) запустить ansible-ger-nod-02.
  2. Первый прогон: как у rus-central — ansible_password из /VPS → PASS_GER_NOD_02; роль host кладёт ключ и отключает пароль. Роль remnanode держит A-запись yali.gunis.top в Cloudflare, выпускает LE по HTTP-01 (порт 80, без TXT _acme-challenge в зоне), поднимает remnanode + nginx SelfSteal.
  3. В панели нода должна стать зелёной; браузер на https://yali.gunis.top — маскировочный сайт.
  4. Клиент NetBird ходит на https://central.gunihome.ru ключом remnawave-peers. Пока peer панели не виден, NODE_PORT 2222 остаётся открыт для WAN egress панели. Когда peer core-net есть, 2222 разрешён только с его NetBird IP. Публичный :9100 закрыт: метрики ноды уходят vmagent-ом в VictoriaMetrics на 192.168.1.108:8428 через маршрут homelab-lan.
  5. На core-net (unprivileged LXC) /dev/net/tun сам не появляется. Токен Terraform получает 403: проброс устройства разрешён только root@pam. На netcore: pct set 902 -dev0 /dev/net/tun,mode=0666 && pct reboot 902, затем ещё раз ansible-core-net. До этого панель остаётся на публичном адресе ноды.

Шаг 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). Отдельно создаётся группа remnawave и ключ remnawave-peers (NETBIRD_REMNAWAVE_SETUP_KEY): он не добавляет peer в homelab-routers. Оба ключа сохраняются в Infisical.
  3. Запустить пайплайн ansible-opnsense в Gitea Actions. Раннер обращается по HTTPS REST API к 192.168.1.1, проверяет/устанавливает плагин os-netbird, включает службу и регистрирует шлюз OPNsense на https://central.gunihome.ru:443 по NETBIRD_SETUP_KEY.