Структура формулы

Конвенции задают формуле предсказуемый скелет, и это её главная ценность: открыв любую формулу, вы заранее знаете, где точка входа, где дефолты, где шаблоны конфигов. Типовое дерево репозитория nginx-formula выглядит так: каталог nginx/ с файлами init.sls, install.sls, config.sls, service.sls, map.jinja, defaults.yaml, подкаталог files/ для шаблонов, а рядом — pillar.example и README. Три файла образуют ядро паттерна: init.sls — точка входа, defaults.yaml — значения по умолчанию, map.jinja — слой, который превращает дефолты, grains и pillar в единый словарь настроек. Всё остальное — обычные SLS, читающие этот словарь.

Как это работает

init.sls почти никогда не содержит логики — он собирает формулу из частей:

include:
  - nginx.install
  - nginx.config
  - nginx.service

Обращение к nginx применяет nginx/init.sls, а к nginx.config — только nginx/config.sls; дробление на install/config/service позволяет, например, перегенерировать конфиг без переустановки пакета. defaults.yaml хранит дефолты формулы (имя пакета, пути, параметры конфига). map.jinja импортирует их и сливает с поправками по grains['os_family'] (в Debian пакет и путь одни, в RedHat другие) и с pillar-переопределениями пользователя; каждый SLS начинает с {% from "nginx/map.jinja" import nginx with context %} и дальше берёт значения только из nginx. Шаблоны конфигов лежат в files/ и подключаются через source: salt://nginx/files/nginx.conf.j2 с template: jinja. Хорошим тоном считаются также clean.sls (снести всё, что формула поставила) и pillar.example с полным списком поддерживаемых ключей.

Когда применять

Эту структуру стоит применять к любому собственному набору состояний сложнее двух-трёх ID — даже если «формулой» вы его не называете. Критерий гранулярности простой: отдельный SLS на каждую фазу жизненного цикла, которую захочется запускать отдельно. Практический выигрыш проявляется быстро: state.apply nginx.config в цикле правки конфигов работает секунды вместо полного прогона; map.jinja избавляет от {% if grains['os_family'] == 'RedHat' %} в каждом состоянии; defaults.yaml документирует все ручки формулы в одном месте. Для одноразового SLS из пары состояний городить полный скелет не нужно — структура должна расти вместе со сложностью, а не опережать её.

Типичные ошибки

Самая частая — захардкоженные значения в SLS в обход map.jinja: имя пакета прописано прямо в состоянии, и формула ломается на втором дистрибутиве. Вторая — путать роли defaults.yaml и pillar: дефолты — часть кода формулы и меняются коммитом, pillar — данные конкретной инсталляции; когда пользовательские настройки начинают коммитить в defaults.yaml, формула перестаёт быть переиспользуемой. Третья — свалить шаблоны рядом с SLS вместо files/: имена начинают конфликтовать, а salt://-пути превращаются в загадки. Ещё один антипаттерн — монолитный init.sls на сотни строк без дробления: его нельзя применить частично и тяжело читать; include и мелкие SLS с requisites между ними всегда выигрывают. И наконец — формула без релизов: версия в файле FORMULA годами остаётся 0.0.1, тегов нет, а потребители тянут движущуюся ветку — релизьте формулы тегами и фиксируйте версию на стороне потребителя.

Связанные понятия

• Формулы
• Паттерн map.jinja
• include и extend
• SLS-файлы и YAML
• Что такое grains