Pillar top file

Pillar top file — это файл top.sls в корне дерева pillar (/srv/pillar/top.sls при стандартном pillar_roots), который определяет, какие данные получит каждый миньон. Синтаксис аналогичен top-файлу состояний, но функционально они различаются: top file состояний определяет действия при highstate, а pillar top file определяет данные, доступные миньонам. Ошибка в таргетинге может привести к тому, что хост не получит необходимые данные или секреты окажутся у неправильных машин.

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

Файл имеет вложенную структуру YAML: окружение, выражения таргетинга и списки pillar-SLS. Минимальный рабочий пример:

base:
  '*':
    - common
  'web*':
    - nginx
  'G@os_family:Debian':
    - match: compound
    - apt

Здесь каждый миньон получает common.sls, хосты с id на web — дополнительно nginx.sls, а Debian-подобные системы — apt.sls через compound-таргетинг (строка - match: compound переключает тип матчинга; доступны также grain, pcre, list и другие). Когда миньон запрашивает pillar, мастер проходит по top file, собирает все совпавшие записи, рендерит каждый SLS и объединяет словари в один. При пересечении ключей действует стратегия слияния из опции pillar_source_merging_strategy (по умолчанию smart): вложенные словари объединяются рекурсивно, а конфликтующие скалярные значения перезаписываются — полагаться на порядок здесь не стоит, лучше не дублировать ключи между файлами.

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

Top file — обязательная часть любого дерева pillar. Рабочий паттерн: common для всех через '*', далее файлы по ролям (web, db, monitoring) с таргетингом по id или grains и, при необходимости, точечные записи для отдельных хостов по полному minion id. Для различий stage/prod удобнее отдельные подкаталоги (- prod.db против - stage.db) с таргетингом по соответствующему grain или отдельные pillar-окружения через pillarenv. Таргетинг по кастомным grains в pillar top file допустим только для несекретных данных: значения grains задаёт сам миньон, и скомпрометированный хост может «переехать» в чужую роль. Секреты назначайте по minion id — его подделать нельзя, он закреплён принятым ключом.

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

Классика — перепутать два top-файла и положить назначение pillar в /srv/salt/top.sls (или наоборот): синтаксис одинаковый, ошибка не бросается в глаза, а данные не приходят. Вторая — таргетить секретные pillar по grains: миньон контролирует свои grains и может подобрать значения, чтобы получить чужие ключи. Третья — дублировать один ключ в нескольких SLS для одного миньона и удивляться результату слияния. Четвёртая — забыть saltutil.refresh_pillar после правки top file: назначение изменилось, но миньоны живут со старой копией в памяти. Диагностика простая: salt <id> pillar.items показывает итог именно для этого миньона.

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

• Pillar
• Что такое pillar
• top.sls и highstate
• Таргетинг миньонов
• Секреты в pillar