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
128 lines
11 KiB
Markdown
128 lines
11 KiB
Markdown
# Инструкция по развертыванию инфраструктуры (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`.
|