Files
homelab-infra/AGENTS.md
T

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