From 87d468c8c1684dd2f1034123b7cfe3c66ff560ec Mon Sep 17 00:00:00 2001 From: karpenok Date: Sun, 8 Nov 2026 01:15:52 +0700 Subject: [PATCH] up --- .gitignore | 6 --- AGENTS.md | 67 ------------------------ README.md | 33 ------------ docs/netbird/design.md | 62 ---------------------- inventories/prod/group_vars/all.yml | 3 -- inventories/prod/group_vars/netbird.yml | 1 - inventories/prod/hosts.yml | 2 - playbooks/host.yml | 1 - playbooks/netbird.yml | 1 - playbooks/site.yml | 1 - roles/netbird/files/.env.example | 3 -- roles/netbird/files/compose.yaml | 4 -- roles/netbird/templates/config.yaml.j2 | 2 - roles/netbird/templates/dashboard.env.j2 | 1 - services/netbird/README.md | 5 -- 15 files changed, 192 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 README.md delete mode 100644 docs/netbird/design.md delete mode 100644 inventories/prod/group_vars/all.yml delete mode 100644 services/netbird/README.md diff --git a/.gitignore b/.gitignore index d5f7c7d..0f0bbef 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 503113f..0000000 --- a/AGENTS.md +++ /dev/null @@ -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/<имя>`. diff --git a/README.md b/README.md deleted file mode 100644 index 066081f..0000000 --- a/README.md +++ /dev/null @@ -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` diff --git a/docs/netbird/design.md b/docs/netbird/design.md deleted file mode 100644 index 553b628..0000000 --- a/docs/netbird/design.md +++ /dev/null @@ -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. diff --git a/inventories/prod/group_vars/all.yml b/inventories/prod/group_vars/all.yml deleted file mode 100644 index 30c32d9..0000000 --- a/inventories/prod/group_vars/all.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -# Общий слой переменных площадки prod. -# Адрес подключения здесь не хранится: он лежит в hosts.yml как ansible_host. diff --git a/inventories/prod/group_vars/netbird.yml b/inventories/prod/group_vars/netbird.yml index 6ae3f5c..3473a14 100644 --- a/inventories/prod/group_vars/netbird.yml +++ b/inventories/prod/group_vars/netbird.yml @@ -1,2 +1 @@ -# Публичное имя сервиса. На какой машине он стоит, задаёт группа netbird в hosts.yml. netbird_domain: central.gunihome.ru diff --git a/inventories/prod/hosts.yml b/inventories/prod/hosts.yml index 4c7eed6..8f03614 100644 --- a/inventories/prod/hosts.yml +++ b/inventories/prod/hosts.yml @@ -1,5 +1,3 @@ -# Канонический inventory: где машина и чем она является. -# ansible_host — адрес подключения. Это не DNS-имя: домашний DNS может его подменить. all: children: home: diff --git a/playbooks/host.yml b/playbooks/host.yml index 5bee4d8..a461f61 100644 --- a/playbooks/host.yml +++ b/playbooks/host.yml @@ -1,5 +1,4 @@ --- -# Подготовка любой машины из inventory. Сервисы эту роль не копируют, а подключают. - name: Подготовить машину hosts: all gather_facts: false diff --git a/playbooks/netbird.yml b/playbooks/netbird.yml index 6d2b529..cdd0f00 100644 --- a/playbooks/netbird.yml +++ b/playbooks/netbird.yml @@ -1,5 +1,4 @@ --- -# Только панель. Подготовка машины — роль host в playbooks/host.yml. - name: Установить панель NetBird hosts: netbird gather_facts: false diff --git a/playbooks/site.yml b/playbooks/site.yml index d9fa2ce..e10b4ea 100644 --- a/playbooks/site.yml +++ b/playbooks/site.yml @@ -1,4 +1,3 @@ --- -# Полный прогон площадки: все машины, затем каждый сервис на свою группу. - ansible.builtin.import_playbook: host.yml - ansible.builtin.import_playbook: netbird.yml diff --git a/roles/netbird/files/.env.example b/roles/netbird/files/.env.example index 3809984..573ccba 100644 --- a/roles/netbird/files/.env.example +++ b/roles/netbird/files/.env.example @@ -1,6 +1,3 @@ -# Пример переменных. На хосте файл называется .env и создаётся плейбуком при первом запуске. -# Значения ключей сюда не записывать. - COMPOSE_PROJECT_NAME=netbird NETBIRD_DOMAIN= NETBIRD_LETSENCRYPT_EMAIL= diff --git a/roles/netbird/files/compose.yaml b/roles/netbird/files/compose.yaml index cbcab47..3e897bf 100644 --- a/roles/netbird/files/compose.yaml +++ b/roles/netbird/files/compose.yaml @@ -1,7 +1,3 @@ -# Панель NetBird по образцу getting-started.sh из релиза v0.82.0. -# Встроенный Traefik выпускает сертификат Let's Encrypt и ведёт трафик на панель и сервер. -# Секрет почты и ключи подставляются из .env, который создаётся на хосте и в git не попадает. - name: netbird services: diff --git a/roles/netbird/templates/config.yaml.j2 b/roles/netbird/templates/config.yaml.j2 index e01a521..d355ef2 100644 --- a/roles/netbird/templates/config.yaml.j2 +++ b/roles/netbird/templates/config.yaml.j2 @@ -1,5 +1,3 @@ -# Конфиг netbird-server. Собирает плейбук. Ключи берутся из фактов, не из git. - server: listenAddress: ":80" exposedAddress: "https://{{ netbird_domain }}:443" diff --git a/roles/netbird/templates/dashboard.env.j2 b/roles/netbird/templates/dashboard.env.j2 index 19f5275..d4b128a 100644 --- a/roles/netbird/templates/dashboard.env.j2 +++ b/roles/netbird/templates/dashboard.env.j2 @@ -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 diff --git a/services/netbird/README.md b/services/netbird/README.md deleted file mode 100644 index b0161ec..0000000 --- a/services/netbird/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# NetBird - -Роль: `roles/netbird`. Плейбук: `playbooks/netbird.yml`. - -Адрес машины и имя сайта здесь не хранятся. Они лежат в `inventories/prod/hosts.yml` и `inventories/prod/group_vars/netbird.yml`.