Конфигурация

Soul Stack настраивается двумя типизированными YAML-файлами:

keeper.yml — конфиг одного инстанса Keeper-кластера (listener-ы, PostgreSQL/Redis/Vault, аутентификация операторов, observability, фоновые подсистемы). Полный справочник — keeper.yml.
soul.yml — конфиг агента на управляемом хосте (идентичность, endpoints Keeper-а, TLS, пути, observability). Полный справочник — soul.yml.

Оба файла валидируются по типизированной схеме на старте: неизвестные ключи, неверные типы и нарушенные инварианты отвергаются с понятной ошибкой, а не игнорируются молча.

Где секреты

Секреты в открытом виде в конфиг не пишутся. Вместо значения указывается vault:-ссылка, которую Keeper резолвит через свой Vault-клиент на старте:

postgres:
  dsn_ref: vault:secret/keeper/postgres   # читается из Vault, а не хранится в файле

Так оформляются DSN PostgreSQL, пароль Redis, ключ подписи операторских токенов, host-CA для push и прочее. Plaintext там, где ожидается vault:-ref, схема отвергает.

У агента (soul.yml) vault:-ref-ов нет: у soul нет Vault-клиента (это сознательная мера изоляции — агенту нечем читать секреты). Те немногие локальные секреты, что нужны агенту (например, пароль для Basic-auth на /metrics), задаются путём к файлу с ограниченными правами, а не значением в YAML.

Что доступно из коробки

Сквозные возможности не требуют отдельной интеграции — они встроены в оба исполняемых файла и управляются блоками конфига:

Возможность	Keeper	Soul	Где настраивается
Метрики (Prometheus)	обязательный listener (`:9090`)	опционально, по умолчанию loopback	`listen.metrics` / `metrics`
OpenTelemetry (трейсы)	push в OTLP-коллектор	push в OTLP-коллектор	`otel`
Ротация логов	встроенная, без `logrotate`	встроенная, без `logrotate`	`logging.rotation`
Hot-reload конфига	`SIGHUP` + write-back для API-мутаций	`SIGHUP` (pull-демон)	`hot_reload`
Vault-интеграция	секреты + PKI + KV через `vault:`-ref	— (нет Vault-клиента)	`vault`
RBAC	каталог в PostgreSQL, управление через API	—	(в БД, не в конфиге)

Детали по каждой возможности — в соответствующих разделах keeper.yml и soul.yml.

Hot-reload и перезапуск

Не всякое изменение применяется без перезапуска. Общий принцип:

Без перезапуска меняются параметры конкретного прогона или итерации фоновой задачи: уровень логирования, таймауты, пороги, лимиты, политики плагинов.
Перезапуск нужен для изменений внешней поверхности процесса: адреса listener-ов, TLS-сертификаты, DSN PostgreSQL/Redis, пути лог-файлов.

Полные таблицы «reload-able / restart-required» по каждому блоку — в keeper.yml → Hot-reload и soul.yml → Hot-reload.

Где взять рабочий пример

Пакеты soul-stack-keeper и soul-stack-soul кладут закомментированный пример конфига рядом с исполняемым файлом. Минимальный валидный конфиг со всеми обязательными полями приведён в конце каждого справочника: