up
This commit is contained in:
1 parent
27f15e7bc7
commit
87d468c8c1
15 files changed
-192
No files matched your search
@@ -1,22 +1,16 @@
|
||||
# Секреты и локальные файлы
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
services/netbird/config.yaml
|
||||
*.key
|
||||
*.pem
|
||||
id_rsa*
|
||||
*.token
|
||||
secrets/
|
||||
vault_pass.txt
|
||||
|
||||
# Инфраструктурные артефакты
|
||||
*.tfstate
|
||||
*.tfstate.*
|
||||
.terraform/
|
||||
*.tfvars
|
||||
|
||||
# Служебное
|
||||
.DS_Store
|
||||
*.log
|
||||
*.bak
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
# Правила для AI-агентов
|
||||
|
||||
Ты — DevOps/SRE-ассистент, управляющий личной инфраструктурой на базе Ansible, Docker Compose и GitOps (Gitea Actions). Этот файл — системные инструкции. Соблюдай их без напоминаний.
|
||||
|
||||
## Контекст
|
||||
|
||||
- Репозиторий `homelab-infra` описывает **новую** инфраструктуру. Это единственный источник правды о том, что разворачивается отсюда.
|
||||
- Прежний homelab, текущие VPS и их поломки — вне скоупа. Не инвентаризируй их, не предлагай починку и не переноси в этот репозиторий, пока пользователь явно не попросил.
|
||||
- Инфраструктура строится вокруг overlay-сети **NetBird**: новый хост сначала входит в сеть, потом получает роль.
|
||||
- Сервисы первичны. Хост и набор сервисов на нём меняются. Не создавай каталог на каждую машину и не пиши отдельный плейбук, который описывает одну машину целиком.
|
||||
- Trilium, дерево «Хоумлаб», — архив прежней лабы. Читать его только по прямой просьбе. Ветку «Работа» не читать.
|
||||
|
||||
## Границы (критически важно)
|
||||
|
||||
1. **Рабочая инфраструктура (Iterika) — запретная зона.** Не подключайся и не изменяй хосты из рабочего SSH-конфига (`pve203`, `pve215`, `pve216`, `stata`, `bastion`, `billing` и остальные из `~/.ssh/config.d/work.conf`). Не читай заметки Trilium из ветки «Работа».
|
||||
2. **Секреты не хардкодить.** Никаких паролей, токенов, приватных ключей в манифестах и документах. Используй переменные окружения (`${VAR}`) и шаблоны Ansible (`*.j2`). Реальные значения — только в Gitea Actions Secrets или локально в `.env` (в `.gitignore`).
|
||||
3. **Ничего не исполнять на хостах напрямую**, кроме явно read-only команд диагностики (`docker ps`, `df -h`, `systemctl status` и т.п.), и только после подтверждения пользователем.
|
||||
4. Деструктивные действия (удаление данных, рестарты боевых сервисов, правка фаервола) — только с явного подтверждения пользователя (human-in-the-loop).
|
||||
|
||||
## Как устроена доставка
|
||||
|
||||
Схема из документации Ansible. Другую не выдумывать.
|
||||
|
||||
```
|
||||
inventories/prod/hosts.yml # машины и группы: home, vps и группа сервиса
|
||||
inventories/prod/group_vars/ # значения группы. Домен сервиса лежит здесь
|
||||
inventories/prod/host_vars/ # исключение одной машины, если оно нужно
|
||||
roles/host/ # подготовка любой машины
|
||||
roles/<сервис>/ # доставка одного сервиса
|
||||
playbooks/host.yml
|
||||
playbooks/<сервис>.yml
|
||||
playbooks/site.yml # сначала все машины, затем сервисы на свои группы
|
||||
```
|
||||
|
||||
- `ansible_host` в `hosts.yml` — адрес подключения. Не DNS-имя: домашний DNS может подменить имя.
|
||||
- Роль `host` не копировать в сервис. `site.yml` запускает её до сервисов.
|
||||
- В роли `host` только общее: Docker и SSH. Порты сервиса и Compose — в роли сервиса.
|
||||
- Gitea Actions выполняет `ansible-playbook playbooks/site.yml -i inventories/prod/hosts.yml --limit <группа>`. В сценарии нет адресов и имён машин.
|
||||
- Новая машина — строка в `hosts.yml`. Новый сервис — роль и группа. Не описание машины.
|
||||
- Шаблоны Ansible — `*.j2`. Секреты не в git.
|
||||
|
||||
## Технические стандарты
|
||||
|
||||
- Только **Docker Compose v2** (`docker compose`, не `docker-compose`). Ключ `version:` в compose-файлах не указывать.
|
||||
- Образы **пинить по версии**, не использовать `:latest` в новых манифестах.
|
||||
- Служебные порты (БД, кэши, админки) не публиковать наружу (`0.0.0.0`): только `127.0.0.1` или внутренние Docker-сети.
|
||||
- Перед коммитом compose-манифеста проверять синтаксис: `docker compose -f <путь> config > /dev/null`.
|
||||
- Документация и комментарии — на русском, идентификаторы — на английском.
|
||||
|
||||
## Коммиты (Conventional Commits)
|
||||
|
||||
Формат: `<тип>(<область>): <описание>` на русском.
|
||||
|
||||
- `feat(netbird): ...` — новая функциональность
|
||||
- `fix(netbird): ...` — исправление
|
||||
- `docs(design): ...` — только документация
|
||||
- `chore(repo): ...` — обслуживание репозитория
|
||||
|
||||
Примеры:
|
||||
- `feat(netbird): набросок архитектуры management-сервера`
|
||||
- `docs(netbird): требования к VPS management`
|
||||
|
||||
## Ветвление
|
||||
|
||||
- `main` — рабочее состояние. Прямой push в main допустим на этапе 0 (проектирование).
|
||||
- Для изменений, затрагивающих развёрнутые сервисы, — ветка `feature/<имя>` → pull request → проверка diff → merge.
|
||||
- Черновики и незаконченное — ветки `wip/<имя>`.
|
||||
@@ -1,33 +0,0 @@
|
||||
# homelab-infra
|
||||
|
||||
Инфраструктура как код для новой личной сети. Репозиторий описывает то, что мы разворачиваем с этого момента. Прежний homelab и текущие VPS сюда не переносятся.
|
||||
|
||||
## Идея
|
||||
|
||||
Репозиторий — единственный источник правды. Изменение коммитится сюда и доставляется через Gitea Actions. Правки на хостах вручную по SSH не являются способом ведения инфраструктуры.
|
||||
|
||||
**Сервисы первичны, хосты заменяемы.** Каталог сервиса не называется именем машины. Хост, на котором сервис окажется, и состав группы на этом хосте могут смениться без перестройки репозитория.
|
||||
|
||||
Первый сервис — overlay-сеть **NetBird**. Новый хост сначала входит в неё, потом получает роль.
|
||||
|
||||
## Структура
|
||||
|
||||
```
|
||||
homelab-infra/
|
||||
├── inventories/prod/ # машины, группы площадок и сервисов
|
||||
├── roles/host/ # подготовка любой машины
|
||||
├── roles/netbird/ # панель NetBird
|
||||
├── playbooks/ # host.yml, netbird.yml, site.yml
|
||||
├── docs/netbird/
|
||||
└── .gitea/workflows/
|
||||
```
|
||||
|
||||
Новая машина — строка в `inventories/prod/hosts.yml`. Новый сервис — роль `roles/<имя>/` и плейбук `playbooks/<имя>.yml`. Адрес подключения и домен в роли не пишутся.
|
||||
|
||||
## Сейчас
|
||||
|
||||
Панель NetBird — роль `roles/netbird`. Куда её ставить, написано в `inventories/prod/hosts.yml`, группа `netbird`. Запуск — `.gitea/workflows/netbird-install.yml`. Состав сервиса — в `docs/netbird/design.md`.
|
||||
|
||||
## Ресурсы
|
||||
|
||||
- Git: `https://gitea.gunihome.ru/karpenok/homelab-infra`
|
||||
@@ -1,62 +0,0 @@
|
||||
# NetBird: архитектура overlay-сети
|
||||
|
||||
Статус: **установка панели**. Роль — `roles/netbird`. Машина и домен — в `inventories/prod`.
|
||||
|
||||
## Задача
|
||||
|
||||
NetBird — транспортный фундамент новой инфраструктуры. Новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в overlay и только потом получает сервисы.
|
||||
|
||||
Сервис не привязан к имени машины. Меняется хост — меняется строка в inventory, роль `roles/netbird/` остаётся той же.
|
||||
|
||||
## Компоненты
|
||||
|
||||
| Компонент | Назначение | Порты |
|
||||
| --- | --- | --- |
|
||||
| `netbird-server` 0.82.0 | management, signal, relay и STUN в одном контейнере | 443/tcp через Traefik, 3478/udp |
|
||||
| Dashboard | веб-панель | 443/tcp через Traefik |
|
||||
| Traefik v3.7.14 | сертификат Let's Encrypt и маршрутизация | 80/tcp, 443/tcp |
|
||||
| Встроенный вход | пользователи панели без отдельного Zitadel | — |
|
||||
|
||||
Манифесты живут в `roles/netbird/` и доставляются сценарием Gitea Actions. Официальный установщик — ориентир по составу контейнеров, не способ запуска.
|
||||
|
||||
## Требования к VPS
|
||||
|
||||
| Параметр | Минимум | Комментарий |
|
||||
| --- | --- | --- |
|
||||
| CPU / RAM | 1 vCPU / 1 ГБ | запас — 2 vCPU / 2 ГБ |
|
||||
| Диск | 20 ГБ | база management растёт медленно |
|
||||
| Сеть | белый IPv4 | стабильность важнее локации |
|
||||
| ОС | Ubuntu 24.04 или Debian 12+ | baseline хоста тоже из этого репозитория |
|
||||
| Порты | 80, 443/tcp; 3478/udp | signal и API идут через 443 |
|
||||
|
||||
80/tcp нужен на выпуск Let's Encrypt. Дальше трафик панели и management идёт на 443.
|
||||
|
||||
## Адресация и группы
|
||||
|
||||
Overlay NetBird — `100.64.0.0/10`.
|
||||
|
||||
Группы описывают роль пира, не имя хоста. Состав группы меняется без смены политики.
|
||||
|
||||
| Группа | Кто в ней | Политика |
|
||||
| --- | --- | --- |
|
||||
| `infra-core` | management и будущие управляющие узлы | DNS и маршруты, которые нужны остальным группам |
|
||||
| `servers` | VPS с сервисами | SSH из `admin` |
|
||||
| `workstations` | ПК и ноутбуки | доступ к `servers` по ACL |
|
||||
| `iot` | умный дом, камеры | только явно разрешённые направления |
|
||||
|
||||
Политика по умолчанию — default-deny.
|
||||
|
||||
## Решения до аренды VPS
|
||||
|
||||
1. **Домен.** `central.gunihome.ru`, A-запись на адрес VPS создана вручную.
|
||||
2. **IdP.** На старте встроенный вход панели. Внешний IdP — отдельное решение, когда появится общий SSO.
|
||||
3. **Хостинг.** Провайдер и локация. На состав сервиса не влияют.
|
||||
4. **Бэкап базы management.** Куда складывать снимок и как часто. Решить до появления пиров кроме рабочей станции.
|
||||
|
||||
## Развёртывание
|
||||
|
||||
1. Цель доставки — `central.gunihome.ru`. Отдельного каталога хоста нет.
|
||||
2. Сценарий `netbird-install` запускает `playbooks/site.yml` с ограничением на группу `netbird`. Роль `host` ставит Docker, роль `netbird` открывает порты панели и поднимает её.
|
||||
3. Сертификат выпускает Traefik. Первый администратор создаётся на `/setup`.
|
||||
4. Группы и политики из этого документа задаются уже в панели.
|
||||
5. Первый пир — рабочая станция. Проверка: пинг по overlay-адресу и SSH на management по адресу NetBird.
|
||||
@@ -1,3 +0,0 @@
|
||||
---
|
||||
# Общий слой переменных площадки prod.
|
||||
# Адрес подключения здесь не хранится: он лежит в hosts.yml как ansible_host.
|
||||
@@ -1,2 +1 @@
|
||||
# Публичное имя сервиса. На какой машине он стоит, задаёт группа netbird в hosts.yml.
|
||||
netbird_domain: central.gunihome.ru
|
||||
@@ -1,5 +1,3 @@
|
||||
# Канонический inventory: где машина и чем она является.
|
||||
# ansible_host — адрес подключения. Это не DNS-имя: домашний DNS может его подменить.
|
||||
all:
|
||||
children:
|
||||
home:
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
---
|
||||
# Подготовка любой машины из inventory. Сервисы эту роль не копируют, а подключают.
|
||||
- name: Подготовить машину
|
||||
hosts: all
|
||||
gather_facts: false
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
---
|
||||
# Только панель. Подготовка машины — роль host в playbooks/host.yml.
|
||||
- name: Установить панель NetBird
|
||||
hosts: netbird
|
||||
gather_facts: false
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
---
|
||||
# Полный прогон площадки: все машины, затем каждый сервис на свою группу.
|
||||
- ansible.builtin.import_playbook: host.yml
|
||||
- ansible.builtin.import_playbook: netbird.yml
|
||||
@@ -1,6 +1,3 @@
|
||||
# Пример переменных. На хосте файл называется .env и создаётся плейбуком при первом запуске.
|
||||
# Значения ключей сюда не записывать.
|
||||
|
||||
COMPOSE_PROJECT_NAME=netbird
|
||||
NETBIRD_DOMAIN=
|
||||
NETBIRD_LETSENCRYPT_EMAIL=
|
||||
|
||||
@@ -1,7 +1,3 @@
|
||||
# Панель NetBird по образцу getting-started.sh из релиза v0.82.0.
|
||||
# Встроенный Traefik выпускает сертификат Let's Encrypt и ведёт трафик на панель и сервер.
|
||||
# Секрет почты и ключи подставляются из .env, который создаётся на хосте и в git не попадает.
|
||||
|
||||
name: netbird
|
||||
|
||||
services:
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
# Конфиг netbird-server. Собирает плейбук. Ключи берутся из фактов, не из git.
|
||||
|
||||
server:
|
||||
listenAddress: ":80"
|
||||
exposedAddress: "https://{{ netbird_domain }}:443"
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# Панель за Traefik. Сертификат выпускает Traefik, поэтому LETSENCRYPT_DOMAIN=none.
|
||||
NETBIRD_MGMT_API_ENDPOINT=https://{{ netbird_domain }}
|
||||
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://{{ netbird_domain }}
|
||||
AUTH_AUDIENCE=netbird-dashboard
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# NetBird
|
||||
|
||||
Роль: `roles/netbird`. Плейбук: `playbooks/netbird.yml`.
|
||||
|
||||
Адрес машины и имя сайта здесь не хранятся. Они лежат в `inventories/prod/hosts.yml` и `inventories/prod/group_vars/netbird.yml`.
|
||||
Reference in new issue
Block a user