Основы Pillars

Сценарии использования Pillar

В отличие от grains, которые генерируются клиентом, pillar — это данные, генерируемые master-сервером.

Подобно файлам состояний, данные pillar организованы в виде дерева pillar, а top.sls выполняет координацию данных pillar для окружений и клиентов с доступом к данным.

Конфиденциальные данные:

• Информация, передаваемая через pillar, имеет словарь, сгенерированный для целевого клиента и зашифрованный ключом этого клиента для безопасной передачи данных. Таким образом, данные pillar можно применять для управления защищаемой информацией, например, криптографическими ключами и паролями.
• Данные pillar шифруются индивидуально для каждого клиента.
• Модули выполнения могут использовать для конфигурирования приложений информацию о конфигурации, сохранённую в pillar.

Конфигурация клиентов:

• Модули выполнения, состояния и модули отправки результатов (returners) можно конфигурировать с помощью данных, хранящихся в pillar.
• Данные pillar нацеливаются на клиентов с помощью top-файла pillar.

примечание

По умолчанию содержимое основного файла конфигурации не загружается в данные pillar для всех клиентов, но это поведение настраивается с помощью параметра pillar_opts: False в основной конфигурации. Если параметр включен (True), то основной файл конфигурации будет использован для глобальной настройки клиентов.

Общие сведения

Файлы состояния pillar могут содержать структуры YAML любого типа:

/srv/pillar/top.sls

 base:
   '*':
     - example

/srv/pillar/example.sls

 pillar1: value
 pillar2:
   - value
   - value
 pillar3:
   sub_key:
     - value
     - value

Замечания о структурах pillar:

• Данные pillars могут быть определены в файлах состояния pillar.
• Данные pillar должны представлять собой сериализованные структуры данных, такие как строки, списки и словари.
• Данные pillar обычно определяются и представляются в формате YAML.

Рендеринг pillar

Для просмотра данных pillar используйте модуль выполнения pillar. Этот модуль включает в себя несколько функций, каждая из которых имеет свое назначение.

В таблице 1 приведён перечень функций для просмотра данных pillar.

Таблица 1. Функции для просмотра данных pillar

Имя функции	Назначение
pillar.item	Извлекает значения одного или нескольких ключей из данных pillar, хранящихся в памяти.
pillar.items	Компилирует и возвращает новый словарь pillar, оставляя данные pillar в памяти неизменными. Однако, если в эту функцию передаются ключи pillar, она действует как функция pillar.item и возвращает их значения из данных pillar, хранящихся в памяти.
pillar.raw	Как и pillar.items, функкция возвращает весь словарь pillar, но из данных pillar в памяти, а не компилирует новые данные pillar.
pillar.get	Назначение функции подробно описано ниже.

Функция pillar.get работает во многом так же, как метод get в словаре Python, с дополнительной особенностью, заключающейся в возможности обхода вложенных словарей с использованием двоеточия в качестве разделителя.

Если в pillar присутствует подобная структура:

foo:
  bar:
    baz: qux

то её извлечение из исходного pillar выполняется следующим образом:

{{ pillar['foo']['bar']['baz'] }}

С помощью функции pillar.get можно получить данные и задать значение по умолчанию, если значение недоступно. Это значительно упрощает обработку вложенных структур:

{{ salt['pillar.get']('foo:bar:baz', 'fallback value') }}

примечание

О функциях pillar.get() и salt['pillar.get']():

Обратите внимание, что внутри шаблона переменная pillar — это просто словарь. Это означает, что вызов pillar.get() внутри шаблона будет использовать стандартную функцию словаря .get(), которая не поддерживает дополнительную функциональность с двоеточием в качестве разделителя. Чтобы воспользоваться функцией Salt, необходимо вызывать её, используя синтаксис, приведённый выше:
(salt['pillar.get']('foo:bar:baz', 'qux')).

Параметры конфигурации

Конфигурация для pillar_roots в основной конфигурации идентична по поведению и функциям конфигурации file_roots:

/etc/salt/master.d/pillar.conf

 pillar_roots:
   base:
     - /srv/pillar

В этом примере конфигурации указано, что базовое окружение будет находиться в каталоге /srv/pillar.

Замечания об окружениях pillar:

• Сервер Salt Master поддерживает настройку pillar_roots, которая соответствует структуре file_roots, используемой на файловом сервере Salt.
• Аналогично файловому серверу Salt, опция pillar_roots в основной конфигурации основана на сопоставлении окружений с каталогами.
• Затем данные pillar сопоставляются с клиентами на основе сопоставителей (matchers) в top-файле, который имеет ту же структуру, что и top-файл для состояний.
• Pillars могут использовать те же типы сопоставителей, что и стандартный top-файл, за исключением сопоставления по pillar.

Данные в памяти и данные по запросу

Поскольку компиляция данных pillar является вычислительно затратной операцией, клиент будет хранить копию данных pillar в памяти. Это позволяет избежать необходимости каждый раз запрашивать у master-сервера перекомпиляцию и отправку клиенту копии данных pillar. Именно эти данные pillar в памяти возвращаются функциями pillar.item, pillar.get и pillar.raw.

Разработчики собственных модулей выполнения и контрибьюторы, вносящие вклад в существующие модули выполнения Salt, могут использовать словарь __pillar__ для доступа к данным pillar в памяти.

Данные pillar в памяти генерируются при запуске клиента и могут быть обновлены с помощью функции saltutil.refresh_pillar:

salt \* saltutil.refresh_pillar

Эта функция запускает асинхронное обновление клиентом данных pillar в памяти и всегда возвращает None.

В отличие от данных pillar, хранящихся в памяти, определенные действия запускают компиляцию данных pillar для обеспечения доступности самых актуальных данных Pillar. К таким действиям относятся:

• Выполнение состояний
• Вызов pillar.items

предупреждение

Выполнение этих действий не обновляет данные pillar в памяти. Если состояния выполняются после изменений данных pillar, то состояниям доступны обновленные данные pillar. В то же время, функциям pillar.item, pillar.get и pillar.raw обновлённые данные не будут доступны, пока pillar в памяти не будут обновлены с помощью saltutil.refresh_pillar.

Внешние pillar

Salt предоставляет механизм для генерации данных Pillar посредством вызова внешних сервисов.

Salt может загрузить любые внешние модули pillar из указанного каталога extension_modules, а также модули, установленные с Salt по умолчанию.

После задания директории и загрузки кода для внешнего pillar необходимо настроить master-сервер.

Установите ext_pillar в /etc/salt/master.d/ext_pillar.conf:

ext_pillar:
  - pgsql:
      user: salt
      password: secret
      db: salt_pillar
      host: 127.0.0.1
      port: 5432
      query: "SELECT key, value FROM pillar_data WHERE minion_id = '{minion_id}'"
  - rest:
      url: "https://api.example.com/pillar/{minion_id}"
      token: "API_TOKEN"
  - git:
      master: https://github.com/example/pillar-data.git
      root: pillar
      env: base

Пространство имён pillar

Отдельные файлы pillar объединяются в единый словарь пар ключ:значение. Файлы pillar применяются в порядке их перечисления в top-файле, поэтому при наличии конфликтующих ключей более ранние будут перезаписаны.

/srv/salt/pillar/top.sls

 base:
   '*':
     - packages
     - services

/srv/salt/pillar/packages.sls

 bind: bind9

/srv/salt/pillar/services.sls

 bind: named

В этом сценарии запрос ключа bind в pillar вернет только named. Значение bind9 будет потеряно, поскольку services.sls был обработан позже.

При работе с большими объемами данных pillar иерархическая структура файлов pillar поможет избегать конфликтов имен и более эффективно сопоставлять переменные с переменными Jinja в файлах состояний. Например, Вы можете переработать файл pillar и сделать вложенной любую пару ключ:значение таким образом, чтобы она была уникальной:

/srv/salt/pillar/packages.sls

 packages:
   bind: bind9

Такая структура файла делает ключ packages:bind уникальным, поскольку он вложенный, и этот ключ не будет конфликтовать с ключом services:bind.

Объединение данных pillar

Если один и тот же ключ pillar определен в нескольких файлах pillar, и ключи в обоих файлах ссылаются на вложенные словари, то содержимое этих словарей будет рекурсивно объединено.

Для демонстрации этого возьмем структуру pillar top.sls и изменим структуру словарей packages.sls и services.sls так, чтобы в них отсутствовали конфликты вложенных ключ:значение:

/srv/salt/pillar/top.sls

 base:
   '*':
     - packages
     - services

/srv/salt/pillar/packages.sls

 bind:
   package-name: bind9
   version: 9.9.5

/srv/salt/pillar/services.sls

 bind:
   port: 53
   listen-on: any

В результате объединения pillar services.sls и packages.sls получится следующий словарь pillar:

salt-call pillar.get bind

local:
 ----------
 listen-on:
     any
 package-name:
     bind9
 port:
     53
 version:
     9.9.5

Поскольку оба файла pillar содержали ключ bind, который, в свою очередь, содержал вложенный словарь, ключ bind словаря pillar содержит объединенное содержимое ключей bind обоих файлов.

Вложенные pillar

Файлы pillar могут включать другие файлы pillar, аналогично файлам состояний. Для оператора вложения include доступны два типа синтаксиса: простой и полный.

Простой include добавляет дополнительный pillar, как если бы он был частью того же файла:

include:
  - users

Полный include позволяет использовать две дополнительные опции:

• Передача значений по умолчанию механизму шаблонизации для включаемого pillar-файла.
• Добавление необязательного ключа, под которым будут вложены результаты включаемого pillar.

include:
  - users:
      defaults:
        sudo: ['bob', 'paul']
      key: users

В этой формуле users.sls будет вложен в ключ users скомпилированного pillar. Кроме того, значение sudo будет доступно в качестве переменной шаблона для users.sls.

Кеширование pillar

Если при публикации команды возникает неприемлемая задержка из-за времени рендеринга pillar, можно включить кеширование pillar на стороне master-сервера.

Эта опция сокращает время выполнения команды, но вносит неудобства, которые необходимо учитывать.

Кеширование на master-сервере

Если время рендеринга pillar слишком велико, можно установить pillar_cache: True. В памяти или на диске master-сервера создаётся кеш данных pillar, позволяющий исключить затраты времени на рендеринг pillar для каждого клиента при каждом запросе:

/etc/salt/master.d/pillar.conf

pillar_cache: True

Время жизни кеша

TTL кеша устанавливает время в секундах до истечения срока действия кеша и перекомпиляции pillar в новый кеш:

/etc/salt/master.d/pillar.conf

pillar_cache_ttl: 3600

Хранилище кеша

Включая использование кеша, Вы можете указать место его хранения: диск или оперативную память:

/etc/salt/master.d/pillar.conf

 # Value can be "disk" or "memory"
 # This example uses "disk"
 pillar_cache_backend: disk

disk:

• Это хранилище по умолчанию.
• Рендерированные pillar сериализуются и десериализуются как структуры msgpack для повышения скорости.

предупреждение

Существенный риск безопасности может представлять то, что pillar хранятся в НЕЗАШИФРОВАННОМ виде. Убедитесь, что для главного кеша установлены соответствующие разрешения.

memory:

• Использует структуру данных Python в памяти для максимальной производительности.
• Каждый рабочий процесс master содержит свой собственный кеш в памяти.
• Нет гарантии согласованности кеша между запросами клиентов.
• Этот тип хранилища лучше применять в ситуациях, когда данные pillar меняется редко или неизменны.

предупреждение

Существенный риск безопасности может представлять то, что НЕЗАШИФРОВАННЫЕ данные pillar будут доступны любому процессу, который может исследовать память salt-master.

Окружения pillar

При использовании нескольких окружений pillar по умолчанию данные pillar из всех окружений объединяются. Таким образом, словарь данных pillar будет содержать ключи из всех настроенных окружений.

Чтобы клиент учитывал конфигурацию pillar только из одного окружения, используется параметр конфигурации клиента pillarenv. Этот параметр может быть полезен в случаях, когда необходимо запускать состояния с альтернативными данными pillar либо в различных тестовых средах.

Предположим, например, что в файле конфигурации клиента установлен параметр:

pillarenv: base

При такой настройке клиент при компиляции данных pillar в памяти будет игнорировать все окружения pillar, кроме base. При запуске состояний для переопределения значения конфигурации pillarenv клиента можно использовать аргумент CLI pillarenv:

salt \* state.apply mystates pillarenv=testing

Приведенная выше команда запустит состояния с данными pillar, полученными исключительно из среды testing, без изменения данных pillar в памяти.

примечание

При запуске состояний с параметром CLI pillarenv установка параметра pillarenv в файле конфигурации клиента не требуется. Параметр pillarenv=testing, заданный в CLI при запуске состояний, в любом случае ограничит данные pillar, принимаемые состояниями, только окружением testing.

Можно привязать pillarenv к используемому saltenv с помощью параметра конфигурации клиента pillarenv_from_saltenv. Если установить его в True, то при указании конкретного saltenv при выполнении состояний соответствующее значение pillarenv будет идентичным. По сути, это делает следующие две команды эквивалентными:

salt \* state.apply mystates saltenv=dev

salt \* state.apply mystates saltenv=dev pillarenv=dev

Однако, явное указание pillarenv переопределит данное поведение. Так, указанная ниже команда будет использовать окружение pillar qa, но при этом загружать SLS-файлы из saltenv dev:

salt \* state.apply mystates saltenv=dev pillarenv=qa

Таким образом, если pillarenv задан в конфигурационном файле клиента, параметр pillarenv_from_saltenv будет игнорироваться, а указание pillarenv в CLI временно переопределит действие pillarenv_from_saltenv.

Шаблоны Jinja в pillar

Простой пример — настроить в pillar сопоставления имён пакетов для различных дистрибутивов Linux:

/srv/pillar/pkg/init.sls

 pkgs:
   {% if grains['os_family'] == 'RedHat' %}
   apache: httpd
   vim: vim-enhanced
   {% elif grains['os_family'] == 'Debian' %}
   apache: apache2
   vim: vim
   {% elif grains['os'] == 'Arch' %}
   apache: apache
   vim: vim
   {% endif %}

State-файлы с данными из pillar

Следовательно, эти данные можно использовать внутри модулей, рендереров и файлов состояний через общий словарь pillar:

apache:
  pkg.installed:
    - name: {{ pillar['apache'] }}

git:
  pkg.installed:
    - name: {{ pillar['git'] }}

Наконец, приведённые выше состояния могут использовать значения, предоставленные им через pillar. Все значения pillar, назначенные конкретному клиенту, доступны через словарь pillar. Как показано в приведенном выше примере, для доступа к ключам и значениям словаря pillar можно использовать подстановки Jinja.

Обратите внимание, что в top.sls нельзя просто перечислять пары ключ/значение. Вместо этого необходимо сопоставить клиент с файлом pillar, а уже в самом файле pillar задать ключи и значения:

/srv/pillar/top.sls

 base:
   '*':
     - updates
   'load-balancer-minion':
     - ibm-cloud-keys

---

Translated excerpt from "Salt User Guide".

Original work:
Copyright 2021-2025 VMware, Inc.

Licensed under the Apache License, Version 2.0
http://www.apache.org/licenses/LICENSE-2.0

Translation and additional text © 2026 Salt.Box Project Authors This is an unofficial translation. In case of inconsistencies, the original English version shall prevail.