Files
homelab-infra/BOOTSTRAP.md
T
karpenokandCursor 13870d6399
ansible-core-net / deploy (push) Failing after 59s
ansible-ger-nod-02 / deploy (push) Successful in 25s
fix(core-net): не ломать Terraform из-за запрета на /dev/net/tun
Токен Proxmox не может пробросить устройство. Остальной стек панели ставится до роли NetBird, а команда для root@pam описана в bootstrap.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-12 16:57:19 +07:00

173 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Инструкция по развертыванию инфраструктуры (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` | `/opt/infisical`, `/opt/vaultwarden` |
| `core-mon` | `playbooks/core-mon.yml` | `roles/core-mon/monitoring` | `/opt/monitoring` (Prometheus и VictoriaMetrics) |
| `rus-central` | `playbooks/rus-central.yml` | `roles/rus-central/netbird` | `/opt/netbird` |
| `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` | 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`); 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` | Prometheus (`:9090`), VictoriaMetrics (`:8428`), Alertmanager (`:9093`), Grafana (`:3000`), Ntfy (`:80`) |
### 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 сертификаты ноды).
- `/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/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`.
---
## 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 (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`. В Prometheus эта нода больше не входит.
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`.