Каталог core-модулей

Core-модуль — единица работы, которую применяет один шаг Destiny или Scenario. Core-модули статически встроены в исполняемые файлы (Soul-side — в soul, Keeper-side — в keeper): отдельная установка не нужна, версия модуля = версия сборки. Кастомные модули подключаются как отдельные исполняемые файлы-плагины через gRPC и здесь не описываются.

Форма имени

Шаг адресует модуль и его состояние в форме core.<module>.<state>:

- name: Install nginx package
  module: core.pkg.installed
  params:
    name: nginx

• core.<module> — имя модуля в реестре (например core.pkg, core.file).
• <state> — желаемое состояние (installed / present / running) либо verb (run / shell / probe / fetched / extracted / read). Verb-формы используют тот же механизм, просто без declarative-семантики «привести к состоянию» — они что-то делают или читают факт.

Идемпотентность

Каждый declarative-state идемпотентен: модуль сначала проверяет текущее состояние хоста и меняет его, только если оно отличается от желаемого. Результат шага — changed=true (состояние поменялось) или changed=false (уже было таким).

changed-статус — сигнал для зависимостей между шагами (например, «перезапусти сервис, только если изменился конфиг» — через onchanges:). Подробнее — в разделе про Destiny.

Verb-модули устроены иначе:

• read-probe (core.http.probe, core.augur.fetch, core.vault.kv-read) — changed=false всегда, конструктивно: чтение не меняет хост.
• command (core.exec.run, core.cmd.shell) — changed=true по умолчанию (verb «выполнить»), понижается guard-параметрами creates / unless / onlyif.
• core.service.restarted — changed=true всегда намеренно: рестарт запрошен явно.

Сторона исполнения: Soul-side и Keeper-side

Сторона	Где исполняется	Как адресуется
Soul-side	На управляемом хосте soul-агентом. Применяются одинаково в pull (демон) и push (oneshot).	on: опущен или Coven-метки.
Keeper-side	На стороне сервера в процессе keeper. Работают с реестрами / облаком / Vault, а не с файловой системой хоста.	on: keeper (обязательно — иначе ошибка валидации).

Soul-side core-модули

Группировка по назначению:

Модуль	Что делает	States / verbs
Пакеты и репозитории
core.pkg	Пакеты OS через native pkg-mgr (apt / dnf / yum / apk).	installed · absent · latest
core.repo	Пакетный репозиторий OS (с GPG-ключом для apt).	present · absent
Файлы
core.file	Файл с содержимым / из шаблона / каталог / удаление.	present · absent · rendered · directory
core.line	In-place построчная правка файла (lineinfile).	present · absent
core.archive	Распаковка архивов (tar / tar.gz / tar.bz2 / zip).	extracted
Сервисы и процессы
core.service	Сервис OS через systemd / openrc / sysv.	running · stopped · restarted · enabled
core.exec	Команда напрямую через exec() — без shell.	run
core.cmd	Shell-строка через sh -c (pipes, redirects).	shell
core.cron	Cron-задачи через /etc/cron.d/.	present · absent
Пользователи и группы
core.user	Локальные пользователи OS.	present · absent
core.group	Локальные группы OS.	present · absent
Система
core.mount	Точки монтирования и /etc/fstab.	present · absent · mounted · unmounted
core.sysctl	Kernel-параметры (vm.* / kernel.* / net.*).	present · applied
core.firewall	Одно правило файрвола (ufw / firewalld).	present · absent
Сеть и внешние данные
core.git	Клонирование / обновление git-репозитория.	cloned · pulled
core.url	Загрузка файла по URL (checksum-верификация).	fetched
core.http	Read-probe HTTP (health-check / readiness).	probe
core.augur	Read-probe живого доступа к внешней системе.	fetch
Утилита
core.noop	No-op / barrier-якорь: ничего не делает, всегда успех без change. Точка ожидания нескольких предыдущих шагов (через register.*) или placeholder / носитель output:-проекции.	run

core.noop — конструктивно changed=false (как read-probe-ы): params: без схемы (любые игнорируются). Назначение — barrier-якорь (задача, обращающаяся к register.* нескольких предыдущих, даёт точку их завершения) и пустой шаг-носитель output:.

Keeper-side core-модули

Диспетчер on: keeper. Выполняются на сервере, работают с реестрами / облаком / Vault.

Модуль	Что делает	States / verbs
core.soul.registered	Привязка хоста (SID) к Coven-меткам реестра.	registered
core.cloud (адрес core.cloud.created / .destroyed / .resized)	Создание / удаление / расширение cloud-инстансов через драйвер провайдера.	created · destroyed · resized
core.choir.present	Членство хоста в Choir-е инкарнации.	present · absent
core.vault.kv-read	Чтение секрета из Vault KV (v1/v2) с audit-event-ом.	read

Примечание по core.cloud: operator-flow доступен — Cloud-Provider и Cloud-Profile регистрируются через Operator API (REST /v1/providers, /v1/profiles, MCP-паритет, web-UI) под RBAC provider.* / profile.* с audit-журналом. На roadmap остаются готовые soul-cloud-* драйверы: в базовую поставку они пока не входят, провайдер обслуживается своим CloudDriver-плагином. Подробнее — core.cloud.

Безопасные дефолты

Часть модулей строится по принципу secure-by-default + явный opt-out: безопасное поведение по умолчанию, ослабление — отдельным явным флагом, который оператор видит в результате применения (поле warnings).

• core.url / core.http — по умолчанию только https://, SSRF-guard, проверка TLS-цепочки; снимаются флагами allow_http / allow_private / insecure_skip_verify.
• core.url — checksum-верификация до появления файла в целевом пути.
• core.repo — gpg_check включён по умолчанию; http://-зеркало и отключённая проверка дают обязательный warning.
• core.firewall — никогда не трогает default policy и не включает файрвол целиком (чтобы не отрезать управление хостом).
• core.archive — защита от zip-slip / zip-bomb, маскировка setuid/setgid при распаковке.

Каждая per-module страница содержит раздел Безопасность с конкретными инвариантами.

Что дальше

• Destiny — как собрать шаги в желаемое состояние одного хоста.
• Scenario — оркестрация по кластеру (on: / where:).
• Essence — откуда берутся значения параметров.