Инвентарь

Инвентарь#

В коллекцию ansible.builtin входят следующие расширения описания инвентаря:

  • advanced_host_list;

  • auto;

  • constructed;

  • generator;

  • host_list;

  • ini;

  • script;

  • toml;

  • yaml.

Подробности о применении расширений этого типа см. его описание.

advanced_host_list#

Это расширение позволяет задавать список узлов в виде строки с диапазонами адресов. Поддерживает генерацию описания нескольких узлов по шаблону с использованием конструкции вида host[1:10].

Поддерживаемые виды диапазонов представлены в таблице.

Тип диапазона

Запись

Список названий узлов

Числовой

web[1:3]

  • web1

  • web2

  • web3

Числовой с шагом приращения

node[1:9:2]

  • node1

  • node3

  • node5

  • node7

  • node9

Буквенный

db-[a:c].example.com

  • db-a.example.com

  • db-b.example.com

  • db-c.example.com

Расширение удобно использовать для быстрого задания простых конфигураций без необходимости создания отдельных файлов инвентаря.

Примечание

ansible.builtin.advanced_host_list обрабатывает только строки, содержащие хотя бы одну запятую. Расширение не обрабатывает путь к файлу.

Пример
ansible-inventory -i "web[1:3],db[01:02].example.com" --list

Результат выполнения команды:

{
  "_meta": {
    "hostvars": {}
  },
  "all": {
    "children": [
      "ungrouped"
    ]
  },
  "ungrouped": {
    "hosts": [
      "web1",
      "web2",
      "web3",
      "db01.example.com",
      "db02.example.com"
    ]
  }
}

auto#

ansible.builtin.auto автоматически определяет, какое расширение использовать для обработки заданного источника инвентаря.

При передаче пути к файлу или каталогу Ansible анализирует его содержимое и поочередно пытается применить доступные расширения, пока не найдет подходящее. Такое поведение упрощает работу с инвентарями: пользователю не нужно явно указывать название расширения.

По умолчанию ansible.builtin.auto включено в список используемых расширений, если в файле конфигурации ansible.cfg не задано иное.

Если расширение не может быть определено автоматически, выполните следующие действия:

  1. В файле инвентаря явно укажите используемое расширение:

    plugin: yaml
# ...

  2. Убедитесь, что нужное расширение включено. Для этого проверьте значение параметра enable_plugins в секции [inventory] файла ansible.cfg:

    [inventory]
enable_plugins = auto, yaml, ini

constructed#

Это расширение позволяет динамически формировать группы узлов и переменные узлов с помощью выражений Jinja2 на основе уже существующих описаний инвентаря.

ansible.builtin.constructed полезно в следующих ситуациях:

  • создание логических групп;

  • составление значений переменных;

  • выполнение фильтрации узлов на основе их свойств, определенных другими источниками инвентаря.

Важно

ansible.builtin.constructed не загружает новое описание, а работает с уже имеющимся описанием узлов, полученным из других источников. Поэтому его необходимо указывать после других источников.

Расширение принимает следующие параметры:

plugin#

Обязательный параметр.

Название расширения описания инвентаря.

Возможные значения:

  • ansible.builtin.constructed (рекомендуется);

  • constructed.

compose#

Определение переменных узла на основе выражений Jinja2. Каждая пара ключ-значение в словаре соответствует названию переменной и шаблону, который будет вычислен.

Значение по умолчанию: {}.

Пример использования compose#
compose:
  server_type: "ansible_hostname | regex_replace('(.{6})(.{2}).*', '\\2')"
groups#

Добавление узлов в группы, если условие на основе выражения Jinja2 возвращает true. Ключ – название создаваемой группы, значение – условие.

Значение по умолчанию: {}.

Пример использования groups#
groups:
  webservers: inventory_hostname.startswith('web')
  multi_group: "(group_names | intersect(['alpha', 'beta', 'omega'])) | length >= 2"
keyed_groups#

Создание группы по значению переменной. Один элемент списка соответствует одному правилу генерации групп.

Поддерживаемые ключи:

default_value#

Значение переменной по умолчанию, если не задано иное.

key#

Ключ из словаря входных данных с названием узла.

parent_group#

Название родительской группы, в которую будет вложена сгенерированная группа.

prefix#

Префикс, добавляемый в начало названия группы.

Значение по умолчанию: "".

separator#

Разделитель между префиксом и значением ключа для создания названия группы.

Значение по умолчанию: _.

trailing_separator#

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

Возможные значения:

  • true – добавление разделителя при пустом значении переменной.

    Важно

    Если параметр keyed_groups[].separator установлен в значение true, установка keyed_groups[].default_value не допускается. Совместное использование указанных параметров приведет к конфликту.

  • false – при пустом значении переменной разделитель не используется.

leading_separator#

Добавление разделителя в начало названия группы, если для keyed_groups не задан префикс (prefix) и используется стандартный разделитель (separator).

По умолчанию группа с ключом, для которой не указан префикс или разделитель, будет иметь название, начинающееся с подчеркивания (_). Это связано с тем, что префиксом по умолчанию является "", а разделителем по умолчанию – _. Задайте для этого параметра значение false для пропуска начального разделителя, если префикс не указан.

Если название группы получено из сопоставления, для объединения элементов по-прежнему используется разделитель. Чтобы вообще не использовать разделитель в названии группы, вместо него установите для группы с ключом пустую строку.

Возможные значения:

  • false – отключение добавления разделителя в начало названия группы;

  • true – добавление разделителя в начало названия группы.

Значение по умолчанию: true.

strict#

Управление поведением расширения при обработке выражений, которые невозможно вычислить из-за отсутствия переменных или фактов.

Возможные значения:

  • false – игнорирование ошибок при вычислении выражений;

  • true – прерывание выполнения при возникновении ошибки.

Значение по умолчанию: false.

use_extra_vars#

Управление переменными, переданными через --extra-vars. Параметр определяет, следует ли включать их в пространство переменных, доступных при вычислении выражений в блоке compose.

Эти переменные будут иметь наивысший приоритет среди всех других источников переменных.

Параметр может быть задан следующими способами:

  • Конфигурационный файл ansible.cfg:

    [inventory_plugins]
use_extra_vars = False

  • Переменная окружения: ANSIBLE_INVENTORY_USE_EXTRA_VARS.

Возможные значения:

  • false – отключение использования в логике инвентаря переменных, переданных через --extra-vars.

  • true – включение использования в логике инвентаря переменных, переданных через --extra-vars.

Значение по умолчанию: false

use_vars_plugins#

Использование расширений переменных (vars plugins) во время обработки инвентаря, а не на более поздних этапах.

По умолчанию Ansible использует расширения переменных до тех пор, пока все источники инвентаря не будут обработаны. Установка значения true для этого параметра позволяет использовать данные из расширений переменных уже на этапе построения описания инвентаря.

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

Такое поведение может повлиять на производительность и порядок применения переменных.

Для применения переменных к неявным группам, таким как all или ungrouped, эти группы должны быть явно определены в предыдущем источнике инвентаря, иначе соответствующие переменные из group_vars/ не будут загружены.

Возможные значения:

  • false – применение расширений переменных в обычном порядке;

  • true – применение расширений переменных во время построения инвентаря.

Значение по умолчанию: false.

generator#

ansible.builtin.generator позволяет создавать узлы и группы узлов на основе шаблонов с использованием Jinja2 и файла конфигурации в формате YAML. Оно генерирует описание инвентаря, комбинируя заданные слои (layers) значений. Таким образом, по заранее заданным шаблонам формируются названия узлов и групп, а также их иерархия.

Расширение принимает следующие параметры:

plugin#

Обязательный параметр.

Название расширения описания инвентаря.

Возможные значения:

  • ansible.builtin.generator (рекомендуется);

  • generator.

hosts#

Настройка шаблонов, на основе которых создаются узлы и их родительские группы.

Принимает следующие аргументы:

  • name – шаблон названия узла в формате Jinja2.

    В шаблоне могут быть использованы переменные, определенные в параметре layers. Каждое уникальное сочетание значений слоев создает отдельный узел.

  • parents – список родительских групп, в которые будет включен узел.

    Каждая группа может иметь собственных родителей и переменные.

layers#

Слои (переменные), которые участвуют в формировании названий узлов и групп.

Пример

Конфигурация:

inventory.config#
---
plugin: ansible.builtin.generator

hosts:
  name: "{{ stage }}_{{ app }}_{{ env }}_host"
  parents:
    - name: "{{ stage }}_{{ app }}_{{ env }}"
      parents:
        - name: "{{ stage }}_{{ app }}"
          parents:
            - name: "{{ stage }}"
        - name: "{{ app }}_{{ env }}"
          parents:
            - name: "{{ app }}"
            - name: "{{ env }}"
    - name: base_group

layers:
  stage:
    - build
    - deploy
    - test
  app:
    - web
    - api
  env:
    - dev
    - prod

Данная конфигурация выполняет следующие действия:

  • Генерирует узлы с шаблонными названиями, например, build_web_dev_host. Всего будет создано 3 (этапа) × 2 (приложения) × 2 (окружения) = 12 узлов.

  • Строит иерархию групп. Каждый узел включается в группы, которые отражают его принадлежность к конкретному приложению, окружению и этапу. Например, узел build_web_dev_host будет включен в группы build_web_dev, build_web, build, web_dev, web, dev и base_group.

Запуск генерации инвентаря:

ansible-inventory -i inventory.config --graph

Результат:

@all
├──@base_group
│  ├──build_web_dev_host
│  ├──build_web_prod_host
│  ├──build_api_dev_host
│  ├──build_api_prod_host
│  ├──deploy_web_dev_host
│  ├──deploy_web_prod_host
│  ├──deploy_api_dev_host
│  ├──deploy_api_prod_host
│  ├──test_web_dev_host
│  ├──test_web_prod_host
│  ├──test_api_dev_host
│  └──test_api_prod_host
├──@build
│  ├──@build_api
│  │  ├──@build_api_dev
│  │  │  └──build_api_dev_host
│  │  └──@build_api_prod
│  │     └──build_api_prod_host
│  └──@build_web
│     ├──@build_web_dev
│     │  └──build_web_dev_host
│     └──@build_web_prod
│        └──build_web_prod_host
├──@deploy
│  ├──@deploy_api
│  │  ├──@deploy_api_dev
│  │  │  └──deploy_api_dev_host
│  │  └──@deploy_api_prod
│  │     └──deploy_api_prod_host
│  └──@deploy_web
│     ├──@deploy_web_dev
│     │  └──deploy_web_dev_host
│     └──@deploy_web_prod
│        └──deploy_web_prod_host
├──@test
│  ├──@test_api
│  │  ├──@test_api_dev
│  │  │  └──test_api_dev_host
│  │  └──@test_api_prod
│  │     └──test_api_prod_host
│  └──@test_web
│     ├──@test_web_dev
│     │  └──test_web_dev_host
│     └──@test_web_prod
│        └──test_web_prod_host
├──@web
│  ├──@web_dev
│  │  ├──build_web_dev_host
│  │  ├──deploy_web_dev_host
│  │  └──test_web_dev_host
│  └──@web_prod
│     ├──build_web_prod_host
│     ├──deploy_web_prod_host
│     └──test_web_prod_host
├──@api
│  ├──@api_dev
│  │  ├──build_api_dev_host
│  │  ├──deploy_api_dev_host
│  │  └──test_api_dev_host
│  └──@api_prod
│     ├──build_api_prod_host
│     ├──deploy_api_prod_host
│     └──test_api_prod_host
├──@dev
│  ├──@web_dev
│  │  ├──build_web_dev_host
│  │  ├──deploy_web_dev_host
│  │  └──test_web_dev_host
│  └──@api_dev
│     ├──build_api_dev_host
│     ├──deploy_api_dev_host
│     └──test_api_dev_host
├──@prod
│  ├──@web_prod
│  │  ├──build_web_prod_host
│  │  ├──deploy_web_prod_host
│  │  └──test_web_prod_host
│  └──@api_prod
│     ├──build_api_prod_host
│     ├──deploy_api_prod_host
│     └──test_api_prod_host
└──@ungrouped

host_list#

ansible.builtin.host_list позволяет задать список узлов в виде строки, разделенной запятыми.

Расширение активируется автоматически, если при запуске утилит Ansible в значении параметра -i указана строка, содержащая хотя бы одну запятую.

Пример
Запуск модуля ansible.builtin.ping на двух удаленных узлах#
ansible -i '10.10.2.6,10.10.2.4' -m ansible.builtin.ping all

ini#

ansible.builtin.ini позволяет использовать файл инвентаря в формате INI. Такой инвентарь организован по секциям:

  • Группы узлов задаются секциями с произвольными названиями:

    [web]
server1
server2

    Здесь web – это название группы, а server1 и server2 – узлы, входящие в нее.

  • Переменные группы указываются в секции с модификатором :vars:

    [web:vars]
ansible_user=deployer
env=prod

    Такие переменные применяются ко всем узлам группы web.

  • Дочерние группы описываются в секции с модификатором :children:

    [backend:children]
api
db

    Здесь группа backend становится родительской для групп api и db.

  • Переменные отдельных узлов можно задавать прямо в строке с названием узла:

    server1 ansible_host=192.168.1.10 ansible_user=root

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

Расширение ansible.builtin.ini включено по умолчанию. Однако, оно не всегда однозначно интерпретирует типы переменных, что может привести к ошибкам. Поэтому рекомендуется использовать альтернативный формат YAML, где типы данных определяются более предсказуемо.

script#

ansible.builtin.script позволяет использовать внешний сценарий в качестве источника инвентаря.

Такой сценарий должен:

  • возвращать структуру данных в формате JSON, совместимом с Ansible;

  • поддерживать аргумент --list для вывода полной структуры инвентаря;

  • поддерживать аргумент --host <hostname> для вывода переменных конкретного узла.

Сценарии, подключаемые через это расширение, могут быть написаны на любом языке, но обязаны быть исполняемыми и корректно обрабатывать аргументы. Результат работы не кешируется: вся ответственность за кеширование (если оно необходимо) ложится на реализацию сценария.

ansible.builtin.script поддерживает единственный параметр – always_show_stderr. Он определяет, следует ли отображать содержимое стандартного потока ошибок stderr сценария в случае его успешного выполнения.

Возможные значения:

  • true – stderr будет показан всегда;

  • false – stderr отображается только при ошибке.

Значение по умолчанию: true.

Значение параметра always_show_stderr можно задать следующими способами:

  • Конфигурационный файл ansible.cfg:

    [inventory_plugin_script]
always_show_stderr = True

  • Переменная окружения: ANSIBLE_INVENTORY_PLUGIN_SCRIPT_STDERR.

Примечание

Вместо использования сценариев для динамического инвентаря, рекомендуется использовать расширения, так как они более интегрированы и удобны в работе с Ansible. Сценарии, в том числе ansible.builtin.script, могут быть полезны в случаях, когда необходимо использовать другой язык программирования или для совместимости с устаревшими системами.

toml#

ansible.builtin.toml позволяет использовать файл в формате TOML в качестве источника инвентаря. Файл должен иметь расширение .toml и содержать корректную структуру, отражающую группы, узлы и переменные.

Для корректной работы расширения требуется наличие одной из следующих библиотек Python:

  • toml;

  • tomli;

  • tomllib.

Пример
inventory.toml#
[all.vars]
has_java = false

[web]
children = ["apache", "nginx"]
vars = { http_port = 8080, myvar = 23 }

[web.hosts]
host1 = {}
host2 = { ansible_port = 222 }

[apache.hosts]
tomcat1 = {}
tomcat2 = { myvar = 34 }
tomcat3 = { mysecret = "03#pa33w0rd" }

[nginx.hosts]
jenkins1 = {}

[nginx.vars]
has_java = true
Использование в CLI#
ansible -i inventory.toml all -m ansible.builtin.ping

yaml#

ansible.builtin.yaml позволяет использовать файл в формате YAML в качестве источника инвентаря. Такой файл должен начинаться с группы all и может содержать секции hosts, vars и children. Вложенность позволяет строить сложную иерархию, а переменные можно назначать как на уровне узлов, так и на уровне групп.

ansible.builtin.yaml поддерживает единственный параметр – yaml_extensions. Он определяет список допустимых расширений файлов, содержащих данные.

Значение по умолчанию: ['.yaml', '.yml', '.json']

Значение параметра можно задать следующими способами:

  • Конфигурационный файл ansible.cfg:

    [defaults]
yaml_valid_extensions = .yaml, .yml, .json

    [inventory_plugin_yaml]
yaml_valid_extensions = .yaml, .yml, .json

  • Переменные окружения:

    • ANSIBLE_YAML_FILENAME_EXT;

    • ANSIBLE_INVENTORY_PLUGIN_EXTS.