Обнаружение переменных: факты и магические переменные
С помощью Ansible можно получать или обнаруживать определённые переменные, содержащие сведения об удалённых системах или о самом Ansible. Переменные, связанные с удалёнными системами, называются фактами. С помощью фактов можно использовать поведение или состояние одной системы в качестве конфигурации для других систем. Например, IP-адрес одной системы можно использовать как значение конфигурации для другой системы. Переменные, связанные с Ansible, называются магическими переменными.
Факты Ansible
Факты Ansible — это данные об удалённых системах, включая операционные системы, IP-адреса, подключённые файловые системы и многое другое. Эти данные доступны в переменной ansible_facts. По умолчанию некоторые факты Ansible также доступны как переменные верхнего уровня с префиксом ansible_. Это поведение можно отключить с помощью настройки INJECT_FACTS_AS_VARS. Чтобы просмотреть все доступные факты, добавьте эту задачу в play:
- name: Print all available facts
ansible.builtin.debug:
var: ansible_facts
Если вы уже создали инвентарь и настроили рабочие учётные данные SSH, можно просмотреть «необработанную» информацию о любом узле инвентаря, выполнив в командной строке эту команду ansible в режиме ad-hoc:
ansible <hostname> -m ansible.builtin.setup
Факты содержат большое количество переменных данных, которые могут выглядеть так:
{
"ansible_all_ipv4_addresses": [
"REDACTED IP ADDRESS"
],
"ansible_all_ipv6_addresses": [
"REDACTED IPV6 ADDRESS"
],
"ansible_apparmor": {
"status": "disabled"
},
"ansible_architecture": "x86_64",
"ansible_bios_date": "11/28/2013",
"ansible_bios_version": "4.1.5",
"ansible_cmdline": {
"BOOT_IMAGE": "/boot/vmlinuz-3.10.0-862.14.4.el7.x86_64",
"console": "ttyS0,115200",
"no_timer_check": true,
"nofb": true,
"nomodeset": true,
"ro": true,
"root": "LABEL=cloudimg-rootfs",
"vga": "normal"
},
"ansible_date_time": {
"date": "2018-10-25",
"day": "25",
"epoch": "1540469324",
"hour": "12",
"iso8601": "2018-10-25T12:08:44Z",
"iso8601_basic": "20181025T120844109754",
"iso8601_basic_short": "20181025T120844",
"iso8601_micro": "2018-10-25T12:08:44.109968Z",
"minute": "08",
"month": "10",
"second": "44",
"time": "12:08:44",
"tz": "UTC",
"tz_offset": "+0000",
"weekday": "Thursday",
"weekday_number": "4",
"weeknumber": "43",
"year": "2018"
},
"ansible_default_ipv4": {
"address": "REDACTED",
"alias": "eth0",
"broadcast": "REDACTED",
"gateway": "REDACTED",
"interface": "eth0",
"macaddress": "REDACTED",
"mtu": 1500,
"netmask": "255.255.255.0",
"network": "REDACTED",
"type": "ether"
},
"ansible_default_ipv6": {},
"ansible_device_links": {
"ids": {},
"labels": {
"xvda1": [
"cloudimg-rootfs"
],
"xvdd": [
"config-2"
]
},
"masters": {},
"uuids": {
"xvda1": [
"cac81d61-d0f8-4b47-84aa-b48798239164"
],
"xvdd": [
"2018-10-25-12-05-57-00"
]
}
},
"ansible_devices": {
"xvda": {
"holders": [],
"host": "",
"links": {
"ids": [],
"labels": [],
"masters": [],
"uuids": []
},
"model": null,
"partitions": {
"xvda1": {
"holders": [],
"links": {
"ids": [],
"labels": [
"cloudimg-rootfs"
],
"masters": [],
"uuids": [
"cac81d61-d0f8-4b47-84aa-b48798239164"
]
},
"sectors": "83883999",
"sectorsize": 512,
"size": "40.00 GB",
"start": "2048",
"uuid": "cac81d61-d0f8-4b47-84aa-b48798239164"
}
},
"removable": "0",
"rotational": "0",
"sas_address": null,
"sas_device_handle": null,
"scheduler_mode": "deadline",
"sectors": "83886080",
"sectorsize": "512",
"size": "40.00 GB",
"support_discard": "0",
"vendor": null,
"virtual": 1
},
"xvdd": {
"holders": [],
"host": "",
"links": {
"ids": [],
"labels": [
"config-2"
],
"masters": [],
"uuids": [
"2018-10-25-12-05-57-00"
]
},
"model": null,
"partitions": {},
"removable": "0",
"rotational": "0",
"sas_address": null,
"sas_device_handle": null,
"scheduler_mode": "deadline",
"sectors": "131072",
"sectorsize": "512",
"size": "64.00 MB",
"support_discard": "0",
"vendor": null,
"virtual": 1
},
"xvde": {
"holders": [],
"host": "",
"links": {
"ids": [],
"labels": [],
"masters": [],
"uuids": []
},
"model": null,
"partitions": {
"xvde1": {
"holders": [],
"links": {
"ids": [],
"labels": [],
"masters": [],
"uuids": []
},
"sectors": "167770112",
"sectorsize": 512,
"size": "80.00 GB",
"start": "2048",
"uuid": null
}
},
"removable": "0",
"rotational": "0",
"sas_address": null,
"sas_device_handle": null,
"scheduler_mode": "deadline",
"sectors": "167772160",
"sectorsize": "512",
"size": "80.00 GB",
"support_discard": "0",
"vendor": null,
"virtual": 1
}
},
"ansible_distribution": "CentOS",
"ansible_distribution_file_parsed": true,
"ansible_distribution_file_path": "/etc/redhat-release",
"ansible_distribution_file_variety": "RedHat",
"ansible_distribution_major_version": "7",
"ansible_distribution_release": "Core",
"ansible_distribution_version": "7.5.1804",
"ansible_dns": {
"nameservers": [
"127.0.0.1"
]
},
"ansible_domain": "",
"ansible_effective_group_id": 1000,
"ansible_effective_user_id": 1000,
"ansible_env": {
"HOME": "/home/zuul",
"LANG": "en_US.UTF-8",
"LESSOPEN": "||/usr/bin/lesspipe.sh %s",
"LOGNAME": "zuul",
"MAIL": "/var/mail/zuul",
"PATH": "/usr/local/bin:/usr/bin",
"PWD": "/home/zuul",
"SELINUX_LEVEL_REQUESTED": "",
"SELINUX_ROLE_REQUESTED": "",
"SELINUX_USE_CURRENT_RANGE": "",
"SHELL": "/bin/bash",
"SHLVL": "2",
"SSH_CLIENT": "REDACTED 55672 22",
"SSH_CONNECTION": "REDACTED 55672 REDACTED 22",
"USER": "zuul",
"XDG_RUNTIME_DIR": "/run/user/1000",
"XDG_SESSION_ID": "1",
"_": "/usr/bin/python2"
},
"ansible_eth0": {
"active": true,
"device": "eth0",
"ipv4": {
"address": "REDACTED",
"broadcast": "REDACTED",
"netmask": "255.255.255.0",
"network": "REDACTED"
},
"ipv6": [
{
"address": "REDACTED",
"prefix": "64",
"scope": "link"
}
],
"macaddress": "REDACTED",
"module": "xen_netfront",
"mtu": 1500,
"pciid": "vif-0",
"promisc": false,
"type": "ether"
},
"ansible_eth1": {
"active": true,
"device": "eth1",
"ipv4": {
"address": "REDACTED",
"broadcast": "REDACTED",
"netmask": "255.255.224.0",
"network": "REDACTED"
},
"ipv6": [
{
"address": "REDACTED",
"prefix": "64",
"scope": "link"
}
],
"macaddress": "REDACTED",
"module": "xen_netfront",
"mtu": 1500,
"pciid": "vif-1",
"promisc": false,
"type": "ether"
},
"ansible_fips": false,
"ansible_form_factor": "Other",
"ansible_fqdn": "centos-7-rax-dfw-0003427354",
"ansible_hostname": "centos-7-rax-dfw-0003427354",
"ansible_interfaces": [
"lo",
"eth1",
"eth0"
],
"ansible_is_chroot": false,
"ansible_kernel": "3.10.0-862.14.4.el7.x86_64",
"ansible_lo": {
"active": true,
"device": "lo",
"ipv4": {
"address": "127.0.0.1",
"broadcast": "host",
"netmask": "255.0.0.0",
"network": "127.0.0.0"
},
"ipv6": [
{
"address": "::1",
"prefix": "128",
"scope": "host"
}
],
"mtu": 65536,
"promisc": false,
"type": "loopback"
},
"ansible_local": {},
"ansible_lsb": {
"codename": "Core",
"description": "CentOS Linux release 7.5.1804 (Core)",
"id": "CentOS",
"major_release": "7",
"release": "7.5.1804"
},
"ansible_machine": "x86_64",
"ansible_machine_id": "2db133253c984c82aef2fafcce6f2bed",
"ansible_memfree_mb": 7709,
"ansible_memory_mb": {
"nocache": {
"free": 7804,
"used": 173
},
"real": {
"free": 7709,
"total": 7977,
"used": 268
},
"swap": {
"cached": 0,
"free": 0,
"total": 0,
"used": 0
}
},
"ansible_memtotal_mb": 7977,
"ansible_mounts": [
{
"block_available": 7220998,
"block_size": 4096,
"block_total": 9817227,
"block_used": 2596229,
"device": "/dev/xvda1",
"fstype": "ext4",
"inode_available": 10052341,
"inode_total": 10419200,
"inode_used": 366859,
"mount": "/",
"options": "rw,seclabel,relatime,data=ordered",
"size_available": 29577207808,
"size_total": 40211361792,
"uuid": "cac81d61-d0f8-4b47-84aa-b48798239164"
},
{
"block_available": 0,
"block_size": 2048,
"block_total": 252,
"block_used": 252,
"device": "/dev/xvdd",
"fstype": "iso9660",
"inode_available": 0,
"inode_total": 0,
"inode_used": 0,
"mount": "/mnt/config",
"options": "ro,relatime,mode=0700",
"size_available": 0,
"size_total": 516096,
"uuid": "2018-10-25-12-05-57-00"
}
],
"ansible_nodename": "centos-7-rax-dfw-0003427354",
"ansible_os_family": "RedHat",
"ansible_pkg_mgr": "yum",
"ansible_processor": [
"0",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"1",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"2",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"3",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"4",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"5",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"6",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz",
"7",
"GenuineIntel",
"Intel(R) Xeon(R) CPU E5-2670 0 @ 2.60GHz"
],
"ansible_processor_cores": 8,
"ansible_processor_count": 8,
"ansible_processor_nproc": 8,
"ansible_processor_threads_per_core": 1,
"ansible_processor_vcpus": 8,
"ansible_product_name": "HVM domU",
"ansible_product_serial": "REDACTED",
"ansible_product_uuid": "REDACTED",
"ansible_product_version": "4.1.5",
"ansible_python": {
"executable": "/usr/bin/python2",
"has_sslcontext": true,
"type": "CPython",
"version": {
"major": 2,
"micro": 5,
"minor": 7,
"releaselevel": "final",
"serial": 0
},
"version_info": [
2,
7,
5,
"final",
0
]
},
"ansible_python_version": "2.7.5",
"ansible_real_group_id": 1000,
"ansible_real_user_id": 1000,
"ansible_selinux": {
"config_mode": "enforcing",
"mode": "enforcing",
"policyvers": 31,
"status": "enabled",
"type": "targeted"
},
"ansible_selinux_python_present": true,
"ansible_service_mgr": "systemd",
"ansible_ssh_host_key_ecdsa_public": "REDACTED KEY VALUE",
"ansible_ssh_host_key_ed25519_public": "REDACTED KEY VALUE",
"ansible_ssh_host_key_rsa_public": "REDACTED KEY VALUE",
"ansible_swapfree_mb": 0,
"ansible_swaptotal_mb": 0,
"ansible_system": "Linux",
"ansible_system_capabilities": [
""
],
"ansible_system_capabilities_enforced": "True",
"ansible_system_vendor": "Xen",
"ansible_uptime_seconds": 151,
"ansible_user_dir": "/home/zuul",
"ansible_user_gecos": "",
"ansible_user_gid": 1000,
"ansible_user_id": "zuul",
"ansible_user_shell": "/bin/bash",
"ansible_user_uid": 1000,
"ansible_userspace_architecture": "x86_64",
"ansible_userspace_bits": "64",
"ansible_virtualization_role": "guest",
"ansible_virtualization_type": "xen",
"gather_subset": [
"all"
],
"module_setup": true
}
В шаблоне или playbook можно обратиться к модели первого диска из фактов, показанных выше, следующим образом:
{{ ansible_facts['devices']['xvda']['model'] }}
Чтобы обратиться к имени узла системы:
{{ ansible_facts['nodename'] }}
Обратите внимание, что префикс ansible_, показанный в выводе модуля setup, не используется при обращении к этим переменным.
Факты можно использовать в условных выражениях (см. раздел Условные выражения), а также в шаблонах. Кроме того, с помощью фактов можно создавать динамические группы узлов, соответствующих определённым критериям. Подробности см. в документации модуля group_by.
Примечание
Поскольку ansible_date_time создаётся и кэшируется при сборе фактов Ansible перед каждым запуском playbook, при длительном выполнении playbook эти данные могут устареть. Если выполнение playbook занимает много времени, используйте фильтр pipe (например, lookup('pipe', 'date +%Y-%m-%d.%H:%M:%S')) или now() с шаблоном Jinja 2 вместо ansible_date_time.
Требования к пакетам для сбора фактов
В некоторых дистрибутивах могут отсутствовать значения фактов или факты могут содержать значения по умолчанию, поскольку пакеты, необходимые для сбора этих фактов, не установлены по умолчанию. Необходимые пакеты можно установить на удалённых узлах с помощью менеджера пакетов ОС. Известные зависимости:
- Сбор сетевых фактов в Linux — зависит от двоичного файла
ip, который обычно входит в пакетiproute2.
Кэширование фактов
Как и зарегистрированные переменные, факты по умолчанию хранятся в памяти. Однако, в отличие от зарегистрированных переменных, факты можно собирать независимо и кэшировать для повторного использования. Благодаря кэшированным фактам можно обращаться к фактам одной системы при настройке другой, даже если Ansible сначала выполняет текущий play на второй системе. Например:
{{ hostvars['asdf.example.com']['ansible_facts']['os_family'] }}
Кэшированием управляют плагины кэша. По умолчанию Ansible использует плагин кэша в памяти, который хранит факты в течение текущего запуска playbook. Чтобы сохранять факты Ansible для повторного использования, выберите другой плагин кэша. Подробности см. в разделе Плагины кэша.
Кэширование фактов может повысить производительность. Если вы управляете тысячами узлов, можно настроить сбор фактов на каждую ночь, а затем периодически в течение дня управлять конфигурацией меньшего набора серверов. Благодаря кэшированным фактам вам доступны переменные и сведения обо всех узлах, даже если вы управляете лишь небольшим числом серверов.
Отключение сбора фактов
По умолчанию Ansible собирает факты в начале каждого play. Если собирать факты не требуется (например, если все сведения о системах известны централизованно), можно отключить сбор фактов на уровне play, чтобы повысить масштабируемость. Отключение сбора фактов может особенно повысить производительность в режиме отправки при работе с очень большим количеством систем или при использовании Ansible на экспериментальных платформах. Чтобы отключить сбор фактов:
- hosts: whatever gather_facts: false
Добавление пользовательских фактов
Модуль setup в Ansible автоматически обнаруживает стандартный набор фактов о каждом узле. Чтобы добавить собственные значения в факты, можно написать пользовательский модуль фактов, задать временные факты с помощью задачи ansible.builtin.set_fact или предоставить постоянные пользовательские факты через каталог facts.d.
facts.d или локальные факты
Добавлено в версии 1.3.
Статические пользовательские факты можно добавлять с помощью статических файлов в facts.d, а динамические — с помощью исполняемых скриптов в facts.d. Например, чтобы добавить в факты список всех пользователей узла, можно создать и запустить скрипт в facts.d.
Чтобы использовать facts.d, создайте каталог /etc/ansible/facts.d на удалённом узле или узлах. Если нужен другой каталог, создайте его и укажите с помощью ключевого слова play fact_path. Добавьте файлы с пользовательскими фактами в этот каталог. Имена всех файлов должны заканчиваться на .fact. Файлы могут быть в формате JSON или INI либо исполняемыми файлами, возвращающими JSON.
Чтобы добавить статические факты, просто добавьте файл с расширением .fact. Например, создайте /etc/ansible/facts.d/preferences.fact со следующим содержимым:
[general] asdf=1 bar=2
Примечание
Убедитесь, что файл не является исполняемым, иначе модуль ansible.builtin.setup перестанет работать.
При следующем сборе фактов в них появится хеш-переменная факта с именем general и элементами asdf и bar. Чтобы проверить это, выполните следующую команду:
ansible <hostname> -m ansible.builtin.setup -a "filter=ansible_local"
В результате появится добавленный пользовательский факт:
{
"ansible_local": {
"preferences": {
"general": {
"asdf" : "1",
"bar" : "2"
}
}
}
}
Пространство имён ansible_local отделяет пользовательские факты, созданные через facts.d, от системных фактов и переменных, определённых в других местах playbook, поэтому переменные не будут переопределять друг друга. К этому пользовательскому факту можно обратиться в шаблоне или playbook следующим образом:
{{ ansible_local['preferences']['general']['asdf'] }}
Примечание
Ключевая часть пар key=value в переменной ansible_local преобразуется в нижний регистр. В приведённом выше примере, если бы INI-файл содержал XYZ=3 в секции [general], обращаться к нему следовало бы так: {{ ansible_local['preferences']['general']['xyz'] }}, а не так: {{ ansible_local['preferences']['general']['XYZ'] }}. Это связано с тем, что Ansible использует ConfigParser из Python, который передаёт все имена параметров методу optionxform. Реализация этого метода по умолчанию преобразует имена параметров в нижний регистр.
Кроме того, с помощью facts.d можно выполнить скрипт на удалённом узле и создать динамические пользовательские факты в пространстве имён ansible_local. Например, можно создать факт со списком всех пользователей удалённого узла. Чтобы создать динамические пользовательские факты с помощью facts.d:
- Напишите и протестируйте скрипт, который создаёт нужные данные JSON.
- Сохраните скрипт в каталоге facts.d.
- Убедитесь, что расширение файла скрипта —
.fact. - Убедитесь, что пользователь, от имени которого выполняется подключение Ansible, может запускать скрипт.
- Соберите факты, чтобы выполнить скрипт и добавить вывод JSON в ansible_local.
По умолчанию сбор фактов выполняется один раз в начале каждого play. Если создать пользовательский факт с помощью facts.d в playbook, он станет доступен в следующем play, в котором собираются факты. Чтобы использовать его в том же play, где он был создан, необходимо явно запустить модуль setup повторно. Например:
- hosts: webservers
tasks:
- name: Create directory for ansible custom facts
ansible.builtin.file:
state: directory
recurse: true
path: /etc/ansible/facts.d
- name: Install custom ipmi fact
ansible.builtin.copy:
src: ipmi.fact
dest: /etc/ansible/facts.d
- name: Re-read facts after adding custom fact
ansible.builtin.setup:
filter: ansible_local
Если вы часто используете такой подход, пользовательский модуль фактов будет эффективнее, чем facts.d.
Информация об Ansible: магические переменные
С помощью «магических» переменных можно получить сведения об операциях Ansible, включая используемую версию Python, узлы и группы в инвентаре, а также каталоги playbook и ролей. Как и переменные подключения, магические переменные относятся к специальным переменным. Имена магических переменных зарезервированы — не задавайте переменные с такими именами. Переменная environment также зарезервирована.
Чаще всего используются магические переменные hostvars, groups, group_names и inventory_hostname. С помощью hostvars можно в любой момент playbook получать доступ к переменным, определённым для любого узла текущего play. Также можно обращаться к фактам Ansible через переменную hostvars, но только после сбора (или кэширования) фактов. Обратите внимание, что переменные, определённые на уровне объектов play, не привязаны к конкретным узлам и поэтому не отображаются в hostvars.
Если вы хотите настроить сервер базы данных, используя значение «факта» с другого узла или значение переменной инвентаря, назначенной другому узлу, используйте hostvars в шаблоне или строке действия:
{{ hostvars['test.example.com']['ansible_facts']['distribution'] }}
С помощью groups — списка всех групп (и узлов) в инвентаре — можно перечислить все узлы в группе. Например:
{% for host in groups['app_servers'] %}
# something that applies to all app servers.
{% endfor %}
С помощью groups и hostvars можно найти все IP-адреса в группе.
{% for host in groups['app_servers'] %}
{{ hostvars[host]['ansible_facts']['eth0']['ipv4']['address'] }}
{% endfor %}
Этот подход можно использовать, чтобы указать серверу обратного прокси-сервера интерфейсной части все узлы группы серверов приложений, настроить необходимые правила межсетевого экрана между серверами и так далее. Перед задачей, которая формирует шаблон, необходимо либо кэшировать факты, либо собрать факты для этих узлов.
С помощью group_names — списка (массива) всех групп, в которые входит текущий узел, — можно создавать шаблонные файлы, содержимое которых зависит от принадлежности узла к группе (или роли):
{% if 'webserver' in group_names %}
# some part of a configuration file that only applies to webservers
{% endif %}
Если сбор фактов отключён, вместо ansible_hostname можно использовать магическую переменную inventory_hostname — имя узла, заданное в инвентаре. Если используется полное доменное имя (FQDN), можно обратиться к inventory_hostname_short, которая содержит часть имени до первой точки, без остальной части домена.
Другие полезные магические переменные относятся к текущему play или playbook. Они могут пригодиться для заполнения шаблонов с несколькими именами узлов или для передачи списка в правила балансировщика нагрузки.
ansible_play_hosts — список всех узлов, которые всё ещё активны в текущем play.
ansible_play_batch — список имён узлов, входящих в текущую «порцию» play.
Размер порции определяется переменной serial. Если она не задана, размер равен всему play (то есть совпадает с ansible_play_hosts).
ansible_playbook_python — путь к исполняемому файлу Python, используемому для запуска инструмента командной строки Ansible.
inventory_dir — путь к каталогу, содержащему файл узлов инвентаря Ansible.
inventory_file — путь и имя файла узлов инвентаря Ansible.
playbook_dir содержит базовый каталог playbook.
role_path содержит путь к текущей роли и работает только внутри роли.
ansible_check_mode — логическое значение, равное True, если Ansible запущен с параметром --check.
Версия Ansible
Добавлено в версии 1.8.
Чтобы адаптировать поведение playbook к разным версиям Ansible, можно использовать переменную ansible_version, имеющую следующую структуру:
{
"ansible_version": {
"full": "2.10.1",
"major": 2,
"minor": 10,
"revision": 1,
"string": "2.10.1"
}
}
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_vars_facts.html
