Files
homelab-infra/BOOTSTRAP.md
T
karpenokandCursor a0507719b0 refactor: drop the finished secrets migration from the deploy path
Product tags now come from the role directory, and edits to the CI scripts no longer redeploy every machine.

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

114 lines
9.2 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. Она выполняется вместе со всеми продуктами машины, когда меняются плейбук, инвентарь или сама роль `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` |
| `rus-central` | `playbooks/rus-central.yml` | `roles/rus-central/netbird` | `/opt/netbird` |
Полная сверка одной машины: `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`) |
### 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`
### Пути секретов:
- `/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`.
- `NETBIRD_AUTH_SECRET`: секрет auth.
- `NETBIRD_DATASTORE_KEY`: 32-байтный ключ SQLite/datastore.
- `NETBIRD_SESSION_KEY`: 32-байтный ключ веб-сессий.
- `/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)
1. Запустить пайплайн **`ansible-rus-central`** в Gitea Actions. Ручной запуск сверяет машину целиком. Push в `roles/rus-central/netbird` ставит только NetBird.
2. Раннер считывает ключи из `/services/netbird` и деплоит стек в `/opt/netbird` на `45.154.185.208`. Домен берётся из `host_vars/rus-central.yml`.