68 lines
6.2 KiB
Markdown
68 lines
6.2 KiB
Markdown
# Правила для 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/<имя>`.
|