Использование переменных

Определение простых переменных

Простую переменную можно определить с помощью стандартного синтаксиса YAML. Например:

remote_install_path: /opt/my_app_config

Обращение к простым переменным

Определив переменную, используйте синтаксис Jinja2, чтобы обратиться к ней. В переменных Jinja2 используются двойные фигурные скобки. Например, выражение My amp goes to {{ max_amp_value }} демонстрирует простейшую форму подстановки переменной. Синтаксис Jinja2 можно использовать в плейбуках. В следующем примере показана переменная, задающая расположение файла, которое может различаться в разных системах:

ansible.builtin.template:
  src: foo.cfg.j2
  dest: '{{ remote_install_path }}/foo.cfg'

Ansible поддерживает циклы и условные операторы Jinja2 в шаблонах, но не в плейбуках. Создать цикл задач нельзя. Плейбуки Ansible — это чистый машиночитаемый YAML.

Определение переменных в виде списков

Переменные с несколькими значениями можно определить с помощью списков YAML. Например:

region:
  - northeast
  - southeast
  - midwest

Обращение к переменным-спискам

Если переменная определена как список (также называемый массивом), можно использовать отдельные элементы этого списка. Первый элемент списка имеет индекс 0, второй — индекс 1 и так далее. Например:

region: "{{ region[0] }}"

Значением этого выражения будет «northeast».

Определение переменных в виде словарей «ключ-значение»

Более сложные переменные можно определять с помощью словарей YAML. Словарь YAML сопоставляет ключи со значениями. Например:

foo:
  field1: one
  field2: two

Обращение к переменным-словарям «ключ-значение»

Если переменная определена как словарь «ключ-значение» (также называемый хешем), можно обращаться к отдельным элементам этого словаря, используя квадратные скобки или точечную нотацию:

foo['field1']
foo.field1

Оба примера обращаются к одному и тому же значению («one»). Нотация с квадратными скобками работает всегда. Точечная нотация может вызывать проблемы, поскольку некоторые ключи совпадают с атрибутами и методами словарей Python. Используйте нотацию с квадратными скобками, если ключи начинаются и заканчиваются двумя символами подчёркивания, которые зарезервированы в Python для специальных значений, или совпадают с одним из известных открытых атрибутов:

add, append, as_integer_ratio, bit_length, capitalize, center, clear, conjugate, copy, count, decode, denominator, difference, difference_update, discard, encode, endswith, expandtabs, extend, find, format, fromhex, fromkeys, get, has_key, hex, imag, index, insert, intersection, intersection_update, isalnum, isalpha, isdecimal, isdigit, isdisjoint, is_integer, islower, isnumeric, isspace, issubset, issuperset, istitle, isupper, items, iteritems, iterkeys, itervalues, join, keys, ljust, lower, lstrip, numerator, partition, pop, popitem, real, remove, replace, reverse, rfind, rindex, rjust, rpartition, rsplit, rstrip, setdefault, sort, split, splitlines, startswith, strip, swapcase, symmetric_difference, symmetric_difference_update, title, translate, union, update, upper, values, viewitems, viewkeys, viewvalues, zfill.

Объединение переменных-списков

Чтобы объединить списки в новую переменную merged_list, можно использовать модуль set_fact следующим образом:

vars:
  list1:
  - apple
  - banana
  - fig

  list2:
  - peach
  - plum
  - pear

tasks:
- name: Combine list1 and list2 into a merged_list var
  ansible.builtin.set_fact:
    merged_list: "{{ list1 + list2 }}"

Объединение переменных-словарей

Для объединения словарей используйте фильтр combine. Например:

vars:
  dict1:
    name: Leeroy Jenkins
    age: 25
    occupation: Astronaut

  dict2:
    location: Galway
    country: Ireland
    postcode: H71 1234

tasks:
- name: Combine dict1 and dict2 into a merged_dict var
  ansible.builtin.set_fact:
    merged_dict: "{{ dict1 | ansible.builtin.combine(dict2) }}"

Дополнительные сведения см. в разделе ansible.builtin.combine .

Использование lookup-плагина merge_variables

Чтобы объединить переменные, соответствующие заданным префиксам, суффиксам или регулярным выражениям, можно использовать lookup-плагин community.general.merge_variables. Например:

merged_variable: "{{ lookup('community.general.merge_variables', '__my_pattern', pattern_type='suffix') }}"

Дополнительные сведения и примеры использования см. в документации по lookup-плагину community.general.merge_variables.

Определение переменных в инвентаре

Для каждого узла можно определить отдельные переменные или задать общие переменные для группы узлов в инвентаре. Например, если все компьютеры в группе [boston] используют ‘boston.ntp.example.com’ в качестве сервера NTP, можно задать переменную группы. На странице Как составить инвентарь приведены сведения о задании переменных узлов и переменных групп в инвентаре.

Определение переменных в play

Переменные можно определять непосредственно в play плейбука:

- hosts: webservers
  vars:
    http_port: 80

Переменные, определённые в play, видны только задачам, выполняемым в этом play.

Определение переменных во включаемых файлах и ролях

Переменные можно определять в повторно используемых файлах переменных или в повторно используемых ролях. Если определять переменные в повторно используемых файлах переменных, конфиденциальные переменные будут отделены от плейбуков. Это разделение позволяет хранить плейбуки в системе контроля версий и даже делиться ими без риска раскрыть пароли и другие конфиденциальные персональные данные. Сведения о создании повторно используемых файлов и ролей см. в разделе Повторное использование артефактов Ansible.

В этом примере показано, как включить переменные, определённые во внешнем файле:

---

- hosts: all
  remote_user: root
  vars:
    favcolor: blue
  vars_files:
    - /vars/external_vars.yml

  tasks:

  - name: This is just a placeholder
    ansible.builtin.command: /bin/echo foo

Содержимое каждого файла переменных представляет собой простой словарь YAML. Например:

---
# in the above example, this would be vars/external_vars.yml
somevar: somevalue
password: magic

Переменные для отдельных узлов и групп можно хранить в аналогичных файлах. Сведения об упорядочивании переменных см. в разделе Организация переменных узлов и групп.

Определение переменных во время выполнения

Переменные можно задавать при запуске плейбука, передавая их в командной строке с помощью аргумента --extra-vars (или -e). Также можно запросить ввод данных пользователем с помощью vars_prompt (см. раздел Интерактивный ввод: запросы). При передаче переменных в командной строке используйте одну строку в кавычках, содержащую одну или несколько переменных в одном из приведённых ниже форматов.

ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"

ansible-playbook release.yml --extra-vars '{"version":"1.23.45","other_variable":"foo"}'
ansible-playbook arcade.yml --extra-vars '{"pacman":"mrs","ghosts":["inky","pinky","clyde","sue"]}'

ansible-playbook arcade.yml --extra-vars "{\"name\":\"Conan O\'Brien\"}"
ansible-playbook arcade.yml --extra-vars '{"name":"Conan O'\\\''Brien"}'
ansible-playbook script.yml --extra-vars "{\"dialog\":\"He said \\\"I just can\'t get enough of those single and double-quotes"\!"\\\"\"}"

ansible-playbook release.yml --extra-vars "@some_file.json"
ansible-playbook release.yml --extra-vars "@some_file.yaml"

Разбираемся в приоритете переменных

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

1. Значения командной строки (например, -u my_user; это не переменные)
2. Значения по умолчанию для ролей (как определено в разделе Структура каталогов роли) [1]
3. Групповые переменные из файла инвентаря или скрипта [2]
4. Inventory group_vars/all [3]
5. Playbook group_vars/all [3]
6. Inventory group_vars/* [3]
7. Playbook group_vars/* [3]
8. Переменные узлов из файла инвентаря или скрипта [2]
9. Inventory host_vars/* [3]
10. Playbook host_vars/* [3]
11. Факты узлов и кэшированные set_facts [4]
12. Переменные плейбука
13. Переменные запроса play vars_prompt
14. Файлы переменных play vars_files
15. Переменные ролей (как определено в разделе Структура каталогов роли)
16. Переменные блока (только для задач в блоке)
17. Переменные задачи (только для этой задачи)
18. include_vars
19. Зарегистрированные переменные и set_facts
20. Параметры роли (и include_role)
21. Параметры include
22. Дополнительные переменные (например, -e "user=my_user") (всегда имеют наивысший приоритет)

В целом Ansible отдаёт приоритет переменным, которые были определены позднее, активнее и в более явной области видимости. Переменные в каталоге defaults внутри роли легко переопределить. Всё, что находится в каталоге vars роли, переопределяет предыдущие значения этой переменной в пространстве имён. Переменные узла или инвентаря переопределяют значения по умолчанию для ролей, но явные включения, например каталог vars или задача include_vars, переопределяют переменные инвентаря.

Ansible объединяет переменные, заданные в разных частях инвентаря, так что более конкретные настройки переопределяют общие. Например, ansible_ssh_user, заданная как group_var, переопределяется переменной ansible_user, заданной как host_var. Сведения о приоритете переменных, заданных в инвентаре, см. в разделе Как объединяются переменные.

Сноски

В предыдущем тексте описана конфигурация hash_behavior=replace по умолчанию. Переключитесь на merge, чтобы переопределять настройки только частично.

Области видимости переменных

Вы можете выбрать место для задания переменной в зависимости от требуемой области видимости её значения. В Ansible есть три основные области видимости:

• Глобальная: задаётся конфигурацией, переменными среды и командной строкой
• Плейбук: каждый плей и содержащиеся в нём структуры, записи vars (vars; vars_files; vars_prompt), значения по умолчанию для ролей и переменные ролей.
• Узел: переменные, непосредственно связанные с узлом, например переменные инвентаря, include_vars, факты или результаты зарегистрированных задач

В шаблоне автоматически доступны все переменные, находящиеся в области видимости узла, а также зарегистрированные переменные, факты и магические переменные.

Советы по размещению переменных

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

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

Задавайте общие значения по умолчанию в файле group_vars/all. Подробнее об организации переменных узлов и групп в инвентаре см. в разделе Организация переменных узлов и групп. Как правило, групповые переменные размещают рядом с файлом инвентаря, но их также может возвращать динамический инвентарь (см. раздел Работа с динамическим инвентарём) или их можно определить в AWX либо в Red Hat Ansible Automation Platform через интерфейс или API:

---
# file: /etc/ansible/group_vars/all
# this is the site wide default
ntp_server: default-time.example.com

Задавайте переменные, зависящие от местоположения, в файлах group_vars/my_location. Все группы являются дочерними по отношению к группе all, поэтому переменные, заданные здесь, переопределяют переменные, заданные в group_vars/all:

---
# file: /etc/ansible/group_vars/boston
ntp_server: boston-time.example.com

Если для одного узла используется другой NTP-сервер, его можно задать в файле host_vars, и тогда он переопределит групповую переменную:

---
# file: /etc/ansible/host_vars/xyz.boston.example.com
ntp_server: override.example.com

Задавайте значения по умолчанию в ролях, чтобы избежать ошибок, связанных с неопределёнными переменными. Если вы предоставляете свои роли другим пользователям, они смогут использовать разумные значения по умолчанию, заданные вами в файле roles/x/defaults/main.yml, или легко переопределить эти значения в инвентаре либо командной строке. Дополнительные сведения см. в разделе Роли. Например:

---
# file: roles/x/defaults/main.yml
# if no other value is supplied in inventory or as a parameter, this value will be used
http_port: 80

Задавайте переменные в ролях, чтобы гарантировать использование значения в этой роли и не допустить его переопределения переменными инвентаря. Если вы не делитесь ролью с другими, таким способом можно определять специфичные для приложения параметры, например порты, в roles/x/vars/main.yml. Если вы делитесь ролями с другими, переменные, заданные здесь, будет сложнее переопределить, хотя их всё же можно переопределить, передав параметр роли или задав переменную с помощью -e:

---
# file: roles/x/vars/main.yml
# this will absolutely be used in this role
http_port: 80

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

roles:
   - role: apache
     vars:
        http_port: 8080

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

roles:
   - role: app_user
     vars:
        myname: Ian
   - role: app_user
     vars:
       myname: Terry
   - role: app_user
     vars:
       myname: Graham
   - role: app_user
     vars:
       myname: John

Переменные, заданные в одной роли, доступны последующим ролям. Вы можете задать переменные в каталоге vars роли (как определено в разделе Структура каталогов роли) и использовать их в других ролях и в других местах плейбука:

roles:
   - role: common_settings
   - role: something
     vars:
       foo: 12
   - role: something_else

Предусмотрены некоторые механизмы защиты, позволяющие не задавать пространство имён для переменных. В этом примере переменные, определённые в ‘common_settings’, доступны задачам ‘something’ и ‘something_else’, но для задач в ‘something’ переменная foo имеет значение 12, даже если в ‘common_settings’ для foo задано значение 20.

Вместо того чтобы беспокоиться о приоритете переменных, при выборе места для переменной рекомендуем подумать о том, насколько легко или часто вы захотите её переопределять. Если вы не уверены, какие другие переменные определены, и вам нужно конкретное значение, используйте --extra-vars (-e), чтобы переопределить все остальные переменные.