include и extend

include и extend — два механизма композиции SLS-файлов. include подключает содержимое других SLS в текущий: все их состояния попадают в общую компиляцию, как будто написаны здесь, — так формулы собираются из частей, а ваши SLS переиспользуют чужие. extend идёт дальше: он позволяет из текущего файла изменить состояние, объявленное в подключённом SLS, — добавить requisite, поменять параметр — не редактируя сам файл. Вместе они дают слоистую архитектуру: базовые SLS описывают общее, специализированные подключают их и точечно докручивают. При этом extend — инструмент тонкий, и злоупотребление им быстро делает конфигурацию нечитаемой.

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

include пишется первым блоком SLS и использует точечную нотацию путей от корня окружения: ssh.banner — это ssh/banner.sls. Точка в начале — относительный путь: .config внутри nginx/init.sls означает nginx/config.sls, что делает формулу переносимой. Повторное включение безопасно: каждый SLS компилируется один раз, сколько бы файлов его ни подключали. После include на состояния подключённых файлов можно ссылаться в requisites — в том числе целиком на файл: require: [{sls: ssh}]. Блок extend (один на SLS) модифицирует включённые состояния по их ID:

include:
  - ssh

extend:
  ssh_config:
    file:
      - watch_in:
        - service: my_custom_service

Требование жёсткое: расширяемый ID обязан присутствовать через include, иначе компиляция падает. Для частого случая «добавить зависимость» есть более простая альтернатива — requisites с суффиксом _in (watch_in, require_in) прямо в вашем состоянии, без блока extend.

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

include — повседневный инструмент: init.sls формулы включает install/config/service; профильный SLS «веб-сервер» включает nginx и certbot; общий базовый слой (common) включается везде. Правило хорошего тона — SLS должен сам включать всё, от чего зависит, а не надеяться, что нужное подключит top file. extend уместен, когда нужно чуть изменить поведение чужого кода без форка: типовой случай — заставить сервис из community-формулы перезапускаться при изменении вашего дополнительного конфига. Но прежде чем тянуться к extend, проверьте два более простых пути: параметризацию через pillar (если формула её предусматривает) и _in-requisites — оба локальнее и читаются легче.

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

Классическая ошибка — extend без include: рендер падает с ошибкой о недоступном ID. Вторая — вместо extend объявить состояние с тем же ID заново: компилятор отвергнет дубликат ID (conflicting ID), а при разных ID вы получите два состояния, управляющие одним файлом и перетирающие друг друга. Третья — незаметная нелокальность: поведение состояния описано в одном файле, а изменено extend из другого; при отладке человек смотрит в исходный SLS и не понимает, откуда взялся лишний watch — поэтому расширения документируют комментарием и держат к минимуму. Наконец, помните, что extend меняет параметры, но не выполняет слияние списков во всех случаях одинаково интуитивно — после правок проверяйте результат через state.show_sls.

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

• SLS-файлы и YAML
• Requisites: require и watch
• Структура формулы
• top.sls и highstate