include и extend

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

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

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

Блок extend модифицирует включённые состояния по их ID:

include:
  - ssh

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

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

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

include используется повседневно: init.sls формулы включает install/config/service, профильный SLS «веб-сервер» включает nginx и certbot, а общий базовый слой (common) включается везде. Следует придерживаться правила, что SLS должен сам включать всё, от чего зависит, а не надеяться на подключение через top file.

extend уместен, когда нужно изменить поведение чужого кода без форка, например, заставить сервис из community-формулы перезапускаться при изменении дополнительного конфига. Однако перед использованием extend стоит проверить возможности параметризации через pillar или _in-requisites, которые более локальны и легче читаются.

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

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

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

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