State-модули

State-модули представляют собой библиотеку «строительных блоков», из которых формируются SLS-файлы: pkg.installed, service.running, file.managed, user.present, cron.present и многие другие. Каждая функция state-модуля описывает один аспект целевого состояния системы и способна идемпотентно привести систему к этому состоянию. Не путайте их с execution-модулями: pkg.install (execution) безусловно запускает установку пакета, а pkg.installed (state) сначала проверяет, установлен ли пакет, и вызывает установку только при необходимости. State-модуль представляет собой идемпотентную обёртку над одним или несколькими execution-модулями, а также поддерживает режим test=True и отчёт об изменениях.

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

Функция state-модуля получает аргументы из SLS (после рендеринга и компиляции) и обязана вернуть стандартную структуру из четырёх полей: name, result (True/False/None), changes (словарь фактических изменений) и comment. Логика всегда одинакова: проверить текущее состояние через execution-модули → если всё уже соответствует, вернуть result: True с пустым changes → если запущено с test=True, вернуть result: None и описание планируемых изменений → иначе внести изменения и отчитаться. Многие модули кросс-платформенны за счёт «виртуальных» подложек: pkg.installed на Debian-миньоне работает через apt, на RHEL — через yum/dnf, выбор происходит автоматически по grains. Аргумент name задаёт объект управления (имя пакета, путь файла), а names позволяет размножить одно состояние на список объектов:

base_tools:
  pkg.installed:
    - pkgs:
      - git
      - htop
      - curl

Для пакетов предпочтителен именно pkgs — он ставит весь список одной транзакцией менеджера пакетов.

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

Ядро повседневной работы — четвёрка pkg, file, service, user: ими покрывается 80% типовой настройки серверов. Прежде чем писать что-то руками через cmd.run или cmd.script, проверьте индекс модулей в документации — почти для всего популярного (git-репозитории через git.latest, БД через mysql_*/postgres_*, Docker через docker_container) модуль уже существует. С релиза 3008 и «Great Module Migration» часть модулей живёт не в ядре, а в community-расширениях salt-extensions и доставляется через salt-pip install saltext-… — если знакомого модуля «нет», сначала поищите его как расширение. Собственный state-модуль (Python-файл в _states/) стоит писать, когда нужно идемпотентно управлять внутренним API или сервисом, для которого готового модуля нет.

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

Самая частая путаница — вызвать execution-функцию в SLS: pkg.install вместо pkg.installed упадёт с ошибкой «is not available», и наоборот, salt '*' pkg.installed из CLI не сработает. Вторая ошибка — не читать возвращаемый comment: модуль часто прямо пишет, почему состояние не применилось (пакет не найден в репозитории, сервис-юнит отсутствует). Третья — дублировать вызов одного модуля внутри одного ID-блока: YAML молча оставит последний ключ, и часть конфигурации потеряется. Наконец, в собственных модулях забывают обрабатывать __opts__['test'] — тогда test=True для них молчит или, хуже, реально меняет систему.

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

• Состояния (states)
• SLS-файлы и YAML
• Execution-модули
• Модули pkg, service, file
• Salt extensions