Pillar top file

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

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

Структура файла — вложенный 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