Плагины инвентаризации

Включение плагинов инвентаризации

Большинство плагинов инвентаризации, поставляемых с Ansible, включены по умолчанию или могут использоваться с плагином auto.

В некоторых случаях, например, если плагин инвентаризации не использует файл конфигурации YAML, может потребоваться включить конкретный плагин. Для этого задайте enable_plugins в файле ansible.cfg в разделе [inventory]. Это переопределит список плагинов, включённых по умолчанию. Ниже приведён список плагинов, включённых по умолчанию в Ansible:

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml

Если плагин входит в коллекцию и не обнаруживается директивой auto, можно добавить его полное квалифицированное имя:

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml, namespace.collection_name.inventory_plugin_name

Если это локальный плагин, например, сохранённый в каталоге, указанном в DEFAULT_INVENTORY_PLUGIN_PATH, на него можно сослаться следующим образом:

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml, my_plugin

Если вы используете плагин, поддерживающий источник конфигурации YAML, убедитесь, что его имя совпадает с именем, указанным в записи plugin файла источника инвентаризации. Для других плагинов необходимо либо сохранить их в одном из каталогов, заданных в ansible.cfg, и включить плагин, либо добавить его в коллекцию, а затем ссылаться на него по FQCN.

Использование плагинов инвентаризации

Чтобы использовать плагин инвентаризации, необходимо предоставить источник инвентаризации. Чаще всего это файл со сведениями об узлах или файл конфигурации YAML с параметрами плагина. Для указания источников инвентаризации можно использовать флаг -i или настроить путь к инвентаризации по умолчанию.

ansible hostname -i inventory_source -m ansible.builtin.ping

Чтобы начать использовать плагин инвентаризации с источником конфигурации YAML, создайте файл с именем, соответствующим схеме имён файлов, описанной для нужного плагина, а затем добавьте plugin: plugin_name. Если плагин входит в коллекцию, используйте полное квалифицированное имя.

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2

В документации каждого плагина должны быть указаны ограничения на имена. Кроме того, чтобы плагин auto включал файл конфигурации YAML по умолчанию, его имя должно иметь расширение yml или yaml (в противном случае см. раздел выше о включении плагинов).

Указав все необходимые параметры, вы можете просмотреть заполненную инвентаризацию с помощью ansible-inventory -i demo.aws_ec2.yml --graph:

@all:
  |--@aws_ec2:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@ungrouped:

Если вы используете плагин инвентаризации из коллекции, связанной с плейбуком, и хотите проверить конфигурацию с помощью ansible-inventory, используйте флаг --playbook-dir.

Источником инвентаризации может быть каталог с файлами конфигурации инвентаризации. Плагин constructed работает только с узлами, уже включёнными в инвентаризацию, поэтому может потребоваться обработать конфигурацию constructed в определённый момент (например, последней). Ansible рекурсивно обрабатывает каталог в алфавитном порядке. Настроить порядок обработки нельзя, поэтому задайте имена файлов так, чтобы добиться предсказуемого результата. Плагины инвентаризации, непосредственно расширяющие возможности constructed, позволяют обойти это ограничение: добавьте параметры constructed наряду с параметрами плагина инвентаризации. В противном случае можно использовать -i с несколькими источниками, чтобы задать определённый порядок, например -i demo.aws_ec2.yml -i clouds.yml -i constructed.yml.

С помощью параметра constructed keyed_groups можно создавать динамические группы на основе переменных узлов. Параметр groups также можно использовать для создания групп, а compose — для создания и изменения переменных узлов. Ниже приведён пример aws_ec2, использующий возможности constructed:

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-east-2
keyed_groups:
  # add hosts to tag_Name_value groups for each aws_ec2 host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
    separator: ""
  # If you have a tag called "Role" which has the value "Webserver", this will add the group
  # role_Webserver and add any hosts that have that tag assigned to it.
  - key: tags.Role
    prefix: role
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"
  # add hosts to the "private_only" group if the host doesn't have a public IP associated to it
  private_only: "public_ip_address is not defined"
compose:
  # use a private address where a public one isn't assigned
  ansible_host: public_ip_address|default(private_ip_address)
  # alternatively, set the ansible_host variable to connect with the private IP address without changing the hostname
  # ansible_host: private_ip_address
  # if you *must* set a string here (perhaps to identify the inventory source if you have multiple
  # accounts you want to use as sources), you need to wrap this in two sets of quotes, either ' then "
  # or " then '
  some_inventory_wide_string: '"Yes, you need both types of quotes here"'

Теперь результат выполнения ansible-inventory -i demo.aws_ec2.yml --graph:

@all:
  |--@aws_ec2:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |  |--...
  |--@development:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@role_Webserver
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |--@tag_Name_ECS_Instance:
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@tag_Name_Test_Server:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |--@ungrouped

Если у узла отсутствуют переменные, указанные в приведённой выше конфигурации (то есть tags.Name, tags, private_ip_address), он не будет добавлен в группы, созданные плагином инвентаризации, а переменная узла ansible_host не будет изменена.

Плагины инвентаризации с поддержкой кэширования могут использовать общие настройки кэша фактов, заданные в разделе [defaults] файла ansible.cfg, или определять настройки для конкретной инвентаризации в разделе [inventory]. Отдельные плагины могут задавать собственные параметры кэширования в файле конфигурации:

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2
cache: true
cache_plugin: ansible.builtin.jsonfile
cache_timeout: 7200
cache_connection: /tmp/aws_inventory
cache_prefix: aws_ec2

Ниже приведён пример настройки кэширования инвентаризации с некоторыми значениями по умолчанию для кэша фактов, используемого плагином кэширования, и времени ожидания в файле ansible.cfg:

[defaults]
fact_caching = ansible.builtin.jsonfile
fact_caching_connection = /tmp/ansible_facts
cache_timeout = 3600

[inventory]
cache = yes
cache_connection = /tmp/ansible_inventory

Список плагинов

Чтобы просмотреть список доступных плагинов, используйте ansible-doc -t inventory -l. Чтобы ознакомиться с документацией и примерами для конкретного плагина, используйте ansible-doc -t inventory <plugin name>.