SLS-файлы и YAML

SLS-файл (SaLt State file) — это единица кода в системе состояний Salt. Это текстовый файл с расширением .sls, который описывает набор состояний в формате 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 — одна зона ответственности. Ставить всё в один файл удобно первые два дня, но потом он становится нечитаемым. Раскладывайте 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