Files
homelab-infra/BOOTSTRAP.md
T
karpenok 6a2f90797a
ansible-deploy / plan (push) Successful in 2s
ansible-lint / lint (push) Successful in 3s
ansible-deploy / deploy (core-mon, ) (push) Successful in 39s
ansible-deploy / deploy (core-net, ) (push) Successful in 57s
ansible-deploy / deploy (core-secrets, ) (push) Successful in 25s
ansible-deploy / deploy (ger-nod-02, ) (push) Successful in 57s
ansible-deploy / deploy (opnsense, ) (push) Successful in 15s
chore: remove NetBird and Authentik layers from homelab
2026-11-19 10:50:19 +07:00

182 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/remnawave`; `roles/core-net/vmagent`; `roles/vector` | `/opt/traefik`; `/opt/remnawave`; `/opt/vmagent`; `/opt/vector` |
| `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` |
| `ger-nod-02` | `playbooks/ger-nod-02.yml` | `roles/remnanode`; `roles/vmagent` | `/opt/remnanode`; `/opt/vmagent` |
| `opnsense` | `playbooks/opnsense.yml` | `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`); vmagent (`127.0.0.1:8429`) + cAdvisor (`127.0.0.1:9101`) |
| **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 | Роль | Стек |
|---|---|---|---|
| **ger-nod-02** | `150.241.64.209` | Remnawave Node (DE) + SelfSteal | `/opt/remnanode`: remnanode + nginx (`yali.gunis.top`) |
Старая панель на Голове (`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).
- `MAIL_ADMIN_USER`: почта администратора (для Grafana и алертов).
- `/ci-cd`:
- `RUNNER_SSH_KEY`: приватный SSH-ключ раннера (ed25519) для деплоя на хосты.
- `TF_STATE_TOKEN`: токен доступа к HTTP State Backend Gitea.
- `CLOUDFLARE_API`: API-токен Cloudflare (Zone DNS Edit для `gunis.top`).
- `/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/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:
```yaml
- 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 <токен>`. Для 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. Проверка раннера — кнопка workflow `runner-smoke`, не правка файлов деплоя.
6. 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.
4. Проверить `https://proxy.gunihome.ru`, `https://gitea.gunihome.ru` и `https://infisical.gunihome.ru`.
Правка только роли `traefik` ставит эту роль, без повторной подготовки машины.
#### 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`** (`150.241.64.209:2222`), host **`yali.gunis.top`**. Пользователи — файл `ansible/roles/core-net/remnawave/files/users.yml` (добавление/изменение/удаление = правка файла). Ссылка подписки `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. Первый прогон: `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. Служебный порт `NODE_PORT` (`2222/tcp`) и порты метрик (`9100/tcp`, `9101/tcp`) в UFW открыты **только** для WAN egress панели (`213.128.28.107` и `185.160.137.140`). Публичный доступ к метрикам закрыт: `vmagent` на `core-net` забирает их по whitelist и отправляет в VictoriaMetrics на `192.168.1.108:8428`.