SLS-файлы и YAML

SLS-файл (SaLt State file) — единица кода в системе состояний Salt: текстовый файл с расширением .sls, который описывает набор состояний в формате YAML. По умолчанию перед парсингом YAML файл проходит через Jinja-шаблонизатор (рендерер jinja|yaml), поэтому внутри доступны переменные, условия и данные из grains и pillar. Важно понимать: YAML здесь — не «конфиг», а сериализованная структура данных, которую компилятор состояний превращает в задания для state-модулей. Как только вы начинаете читать SLS как словари и списки, а не как магический синтаксис, ошибки отступов и странные сообщения парсера перестают быть загадкой.

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

SLS-файлы лежат в file_roots мастера (обычно /srv/salt), и их имена образуют пространство имён: файл webserver/init.sls адресуется как webserver, а webserver/config.sls — как webserver.config. Внутри файла — набор блоков:

/etc/nginx/nginx.conf:
  file.managed:
    - source: salt://webserver/files/nginx.conf
    - user: root
    - mode: "0644"

Верхний ключ (/etc/nginx/nginx.conf) — ID-декларация, уникальный идентификатор состояния в рамках прогона; по умолчанию он же подставляется в аргумент name. Ниже — «модуль.функция» (file.managed) и список аргументов. Один ID может содержать несколько state-модулей, но не два вызова одного модуля — для этого нужны отдельные ID с явным name. Цепочка обработки на миньоне: Jinja рендерит текст → YAML-парсер строит структуру → компилятор собирает из неё high data, разворачивает include и requisites и передаёт функциям state-модулей. Директива include подключает другие SLS по тем же точечным именам, что позволяет собирать конфигурацию из небольших переиспользуемых файлов.

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

Правило деления простое: один SLS — одна зона ответственности. Ставить всё в единый гигантский файл удобно первые два дня, потом он становится нечитаемым; раскладывайте по каталогам с init.sls (nginx/init.sls, nginx/config.sls) — эта структура затем естественно вырастает в формулу. Чистый YAML без Jinja предпочтителен, пока хватает статики: его проще читать и ревьюить. Jinja добавляйте точечно — для различий между дистрибутивами или подстановки значений из pillar. Если логики становится больше, чем разметки, выносите данные в паттерн map.jinja вместо размазывания {% if %} по всему файлу. Альтернативные рендереры (например, чистый Python #!py) оправданы в редких случаях по-настоящему динамической генерации состояний.

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

Больше всего времени съедают отступы: YAML требует строго два пробела на уровень, табы запрещены, а - require: с неправильной вложенностью молча меняет смысл структуры. Классика — забытые кавычки вокруг восьмеричных прав (mode: 0644 без кавычек YAML прочитает как число 420; пишите mode: "0644") и «boolean-ловушки» вроде голых yes/no. Дубли ID-деклараций в пределах одного прогона вызывают ошибку компиляции — типично при include двух файлов с одинаковыми ID. Ошибки Jinja возникают до парсинга YAML, поэтому сообщение может указывать не на ту строку: отлаживайте рендер командой salt-call --local slsutil.renderer salt://nginx/init.sls, чтобы увидеть итоговый YAML глазами.

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

• Состояния (states)
• State-модули
• Jinja в SLS
• file_roots и salt://
• include и extend