Files
homelab-infra/AGENTS.md
T

6.3 KiB

Правила для 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).

Как устроена доставка

Три слоя, и у каждого своё место. Не смешивать их в одном файле.

  1. Хост один на всех. Плейбук playbooks/host.yml готовит любую машину: Docker, базовый firewall, каталоги. Новый VPS попадает в inventory и получает этот плейбук. Задачи хоста не копируются внутрь сервиса.
  2. Сервис один на всех хостов, где он нужен. Каталог services/<имя>/ хранит Compose и шаблоны. Плейбук playbooks/<имя>.yml только доставляет этот сервис и в начале подключает плейбук хоста. Сотня сервисов — сотня таких пар, не сотня описаний машин.
  3. Кто где стоит — только inventory. Имя хоста, группа и публичный домен сервиса лежат в inventory/ и group_vars/. Compose, шаблоны и workflow получают их переменными. Не хардкодить адрес и домен в манифесте.

Gitea Actions запускает ansible-playbook. Сценарий не ставит пакеты, не правит firewall и не описывает контейнеры. Shell-скрипт не заменяет плейбук.

Шаблоны Ansible — *.j2. Секреты по-прежнему не в git: только ${VAR} в Compose и плейсхолдеры в шаблонах.

Технические стандарты

  • Только 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/<имя>.