Keeper

Центральный сервер Soul Stack. Stateless-кластер поверх общих PostgreSQL и Redis; масштабируется горизонтально — добавление инстанса не требует репликации состояния между ними.

Что делает Keeper

• Хранит реестры — управляемых хостов (souls), операторов (operators), каталог сервисов. Авторитетное состояние живёт в PostgreSQL.
• Рендерит Destiny на своей стороне. Шаблонизация (CEL для YAML-выражений + Go text/template для файлов) выполняется на Keeper-е; агенту уходит уже отрендеренный набор задач. Агент не тянет шаблонизатор, vault-клиент и логику резолва — это упрощает и обезопасивает хост.
• Диспетчит прогоны. Решает, какие задачи на каких хостах применить (таргетинг по covens и предикатам), доставляет их и собирает отчёты.
• Ведёт RBAC и аудит. Каждый вызов Operator API проходит проверку прав оператора и пишется в аудит-журнал.
• Фоновые подсистемы — например, очистка реестра от просроченных записей и согласование presence с фактом живых стримов.

Listener-ы и порты

Keeper поднимает несколько независимых listener-ов:

Порт	Listener	Протокол	Назначение
8080	Operator API	HTTP / OpenAPI	первичный интерфейс оператора, health-check /readyz, вьювер спеки /docs, встроенный web-UI /ui
8081	MCP	HTTP	интерфейс для MCP-клиентов (опциональный listener)
9090	метрики	HTTP	Prometheus scrape (/metrics)
9442	gRPC bootstrap	server-only TLS	онбординг агента (soul init): обмен токена + CSR на mTLS-идентичность
8443	gRPC EventStream	mTLS	долгоживущий bidi-стрим к агенту (soul run): доставка задач, отчёты

Порт EventStream: прод 8443, dev 9443

Прод-дефолт EventStream — 8443. Quick Start использует dev-значение 9443. Порт задаётся в конфиге Keeper-а (listen.grpc.event_stream) и должен совпадать с event_stream_port в конфиге агента. Bootstrap-порт 9442 одинаков в dev и проде.

Метрики — pull, OpenTelemetry — push

/metrics (порт 9090) Prometheus скрейпит сам (pull). У Keeper-а нет входящего listener-порта для OpenTelemetry: при включении OTel Keeper сам пушит трейсы в указанный вами OTLP-коллектор (push), ничего не слушая.

Агенты сами инициируют соединение к Keeper-у — на управляемых хостах входящие порты открывать не нужно.

HA и масштабирование

Keeper-инстансы stateless: всё авторитетное состояние — в общей PostgreSQL, presence и координация — в общем Redis. Поэтому:

• несколько инстансов Keeper работают за L4-балансировщиком (для probe достаточно TCP-проверки порта EventStream);
• любой инстанс обслуживает любой запрос оператора и любой стрим агента;
• горизонтальное масштабирование — это просто добавление инстансов на тот же PostgreSQL + Redis.

Каждый инстанс в кластере имеет собственный идентификатор (kid в конфиге), уникальный в пределах кластера.

Первичный интерфейс оператора

Основной способ работы с Keeper-ом — Operator API (HTTP/OpenAPI) и MCP. CLI soulctl — тонкая обёртка над теми же эндпоинтами. Полную OpenAPI-спеку с поиском и кнопкой «Try It» Keeper отдаёт в браузере по GET /docs.

Дополнительно Keeper отдаёт встроенный операторский web-UI по GET /ui — он включён в исполняемый файл и доступен сразу после старта, без отдельного деплоя (на том же порту 8080). UI включён по умолчанию; его можно выключить тогглом в конфиге, не затрагивая Operator API. Это надстройка над тем же Operator API — всё, что делает UI, доступно и через CLI/MCP/OpenAPI.

Установка и запуск

Keeper ставится из пакета soul-stack-keeper, бинарного релиза или сборки. Bootstrap первого оператора — административная подкоманда keeper init. Полная процедура (провижининг Vault, TLS-материал, конфиг, запуск через systemd) — Установка из пакетов.