Руководство по переносу Ansible 2.5

В этом разделе обсуждаются изменения в поведении между Ansible 2.4 и Ansible 2.5.

Цель данного руководства — помочь обновить ваши playbook-файлы, плагины и другие части вашей инфраструктуры Ansible, чтобы они работали с этой версией Ansible.

Рекомендуется прочитать эту страницу вместе с Журналом изменений Ansible 2.5, чтобы понять, какие обновления вам могут потребоваться.

Этот документ является частью коллекции руководств по переносу. Полный список руководств по переносу можно найти по адресу руководствам по переносу.

Playbook
Устаревшие функции
- Jinja-тесты, используемые как фильтры
- Наименование пространства имён Ansible facts
Модули
Плагины
Перенос пользовательских скриптов
Сеть

Playbook

Динамические включения и наследование атрибутов

В версии Ansible 2.4 было введено понятие динамических включений (include_tasks) по сравнению со статическими импортами (import_tasks) для четкого определения различий в том, как include работает в динамических и статических случаях.

Все атрибуты, применяемые к динамическому include_*, применялись только к самому включению, тогда как атрибуты, применяемые к статическому import_*, наследуются задачами внутри него.

Это разделение было частично реализовано в Ansible 2.4. Начиная с Ansible 2.5, эта работа завершена, и разделение теперь работает как задумывалось; атрибуты, применённые к задаче include_*, не будут наследоваться задачами внутри неё.

Чтобы получить результат, аналогичный работе Ansible до версии 2.5, playbook-файлы должны использовать явное применение атрибута к нужным задачам или использовать блоки для применения атрибута ко многим задачам. Другой вариант — использовать статическое import_*, когда это возможно, вместо динамической задачи.

СТАРЫЙ Ansible 2.4:

- include_tasks: "{{ ansible_distribution }}.yml"
  tags:
    - distro_include

Включенный файл:

- block:
    - debug:
        msg: "In included file"

    - apt:
        name: nginx
        state: latest

НОВЫЙ Ansible 2.5:

Включение задачи:

- include_tasks: "{{ ansible_distribution }}.yml"
  tags:
    - distro_include

Включенный файл:

- block:
    - debug:
        msg: "In included file"

    - apt:
        name: nginx
        state: latest
  tags:
    - distro_include

Соответствующее изменение в этих примерах заключается в том, что в Ansible 2.5 включенный файл определяет тег distro_include снова. Тег не наследуется автоматически.

Исправленное обращение с ключевыми словами и встроенными переменными

Были внесены исправления в обработку ключевых слов и «встроенных переменных» для предотвращения их смешения. К сожалению, эти изменения означают, что при вызове ролей необходимо указать, является ли name ключевым словом или переменной. Если у вас есть playbook-файлы, которые выглядят так:

roles:
    - { role: myrole, name: Justin, othervar: othervalue, become: True}

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

roles:
    - { role: myrole, vars: {name: Justin, othervar: othervalue}, become: True}

Полный список ключевых слов см. в Ключевых словах Playbook.

Миграция с with_X на loop

С выпуском Ansible 2.5 рекомендуемым способом выполнения циклов является использование нового ключевого слова loop вместо циклов типа with_X.

Во многих случаях синтаксис loop лучше выражается с помощью фильтров, а не сложных конструкций query или lookup.

В следующих примерах показано, как преобразовать многие распространенные циклы типа with_ в циклы loop и фильтры.

with_list

with_list напрямую заменяется на loop.

- name: with_list
  debug:
    msg: "{{ item }}"
  with_list:
    - one
    - two

- name: with_list -> loop
  debug:
    msg: "{{ item }}"
  loop:
    - one
    - two

with_items

with_items заменяется на loop и фильтр flatten.

- name: with_items
  debug:
    msg: "{{ item }}"
  with_items: "{{ items }}"

- name: with_items -> loop
  debug:
    msg: "{{ item }}"
  loop: "{{ items|flatten(levels=1) }}"

with_indexed_items

with_indexed_items заменяется на loop, фильтр flatten и loop_control.index_var.

- name: with_indexed_items
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_indexed_items: "{{ items }}"

- name: with_indexed_items -> loop
  debug:
    msg: "{{ index }} - {{ item }}"
  loop: "{{ items|flatten(levels=1) }}"
  loop_control:
    index_var: index

with_flattened

with_flattened заменяется на loop и фильтр flatten.

- name: with_flattened
  debug:
    msg: "{{ item }}"
  with_flattened: "{{ items }}"

- name: with_flattened -> loop
  debug:
    msg: "{{ item }}"
  loop: "{{ items|flatten }}"

with_together

with_together заменяется на loop и фильтр zip.

- name: with_together
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_together:
    - "{{ list_one }}"
    - "{{ list_two }}"

- name: with_together -> loop
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ list_one|zip(list_two)|list }}"

with_dict

with_dict можно заменить на loop и либо фильтр dictsort, либо dict2items.

- name: with_dict
  debug:
    msg: "{{ item.key }} - {{ item.value }}"
  with_dict: "{{ dictionary }}"

- name: with_dict -> loop (option 1)
  debug:
    msg: "{{ item.key }} - {{ item.value }}"
  loop: "{{ dictionary|dict2items }}"

- name: with_dict -> loop (option 2)
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ dictionary|dictsort }}"

with_sequence

with_sequence заменяется на loop и функцию range, а также потенциально фильтр format.

- name: with_sequence
  debug:
    msg: "{{ item }}"
  with_sequence: start=0 end=4 stride=2 format=testuser%02x

- name: with_sequence -> loop
  debug:
    msg: "{{ 'testuser%02x' | format(item) }}"
  # range is exclusive of the end point
  loop: "{{ range(0, 4 + 1, 2)|list }}"

with_subelements

with_subelements заменяется на loop и фильтр subelements.

- name: with_subelements
  debug:
    msg: "{{ item.0.name }} - {{ item.1 }}"
  with_subelements:
    - "{{ users }}"
    - mysql.hosts

- name: with_subelements -> loop
  debug:
    msg: "{{ item.0.name }} - {{ item.1 }}"
  loop: "{{ users|subelements('mysql.hosts') }}"

with_nested/with_cartesian

with_nested и with_cartesian заменяются на loop и фильтр product.

- name: with_nested
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_nested:
    - "{{ list_one }}"
    - "{{ list_two }}"

- name: with_nested -> loop
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ list_one|product(list_two)|list }}"

with_random_choice

with_random_choice заменяется просто на использование фильтра random, без необходимости в loop.

- name: with_random_choice
  debug:
    msg: "{{ item }}"
  with_random_choice: "{{ my_list }}"

- name: with_random_choice -> loop (No loop is needed here)
  debug:
    msg: "{{ my_list|random }}"
  tags: random

Устаревшие функции

Jinja-тесты, используемые как фильтры

Использование Jinja-тестов Ansible в качестве фильтров будет удалено в Ansible 2.9.

До Ansible 2.5, Jinja-тесты Ansible часто использовались как фильтры. Ключевое различие состоит в том, что фильтры ссылаются как variable | filter_name , а Jinja-тесты - как variable is test_name.

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

Начиная с Ansible 2.5, использование Jinja-теста Ansible со синтаксисом фильтра будет выводить предупреждение об устаревании.

СТАРЫЙ Ansible 2.4 (и ранее):

when:
    - result | failed
    - not result | success

НОВЫЙ Ansible 2.5:

when:
    - result is failed
    - results is not successful

В дополнение к предупреждениям об устаревании, было введено множество новых тестов, являющихся алиасами старых тестов. Эти новые тесты грамматически более уместны в синтаксисе Jinja-тестов, например, новый тест successful, который является алиасом success.

when: result is successful

Дополнительную информацию см. в тестах.

Кроме того, был создан скрипт для помощи в преобразовании тестов, использующих синтаксис фильтра, в корректный синтаксис Jinja-теста. Этот скрипт использовался для преобразования всех интеграционных тестов Ansible в правильный формат. Существует несколько ограничений, и все изменения, внесённые этим скриптом, должны быть проверены на правильность перед выполнением изменённых playbook-файлов. Скрипт можно найти по адресу https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py.

Наименование пространства имён Ansible facts

Ansible facts, которые исторически были записаны с именами, такими как ansible_* в основном пространстве фактов, были размещены в новом пространстве имён ansible_facts.*. Например, fact ansible_distribution теперь лучше всего запрашивается через структуру переменных ansible_facts.distribution.

Новая конфигурационная переменная inject_facts_as_vars, была добавлена в ansible.cfg. Её значение по умолчанию «True» сохраняет поведение версии 2.4, при котором переменные фактов устанавливаются в старых ansible_* расположениях (одновременно записывая их в новое пространство имён). Ожидается, что в будущих версиях эта переменная будет установлена в значение «False». Когда inject_facts_as_vars установлено в False, вы должны ссылаться на ansible_facts через новое ansible_facts.* пространство имён.

Модули

Основные изменения в популярных модулях подробно описаны здесь.

github_release

В версиях Ansible 2.4 и более ранних, после создания релиза на GitHub с помощью состояния create_release, модуль github_release сообщал состояние как skipped. В версии Ansible 2.5 и более поздних, после создания релиза на GitHub с помощью состояния create_release, модуль github_release теперь сообщает состояние как changed.

Удаленные модули

Следующие модули больше не существуют:

nxos_mtu используйте опцию nxos_system’s system_mtu или nxos_interface вместо этого
cl_interface_policy используйте nclu вместо этого
cl_bridge используйте nclu вместо этого
cl_img_install используйте nclu вместо этого
cl_ports используйте nclu вместо этого
cl_license используйте nclu вместо этого
cl_interface используйте nclu вместо этого
cl_bond используйте nclu вместо этого
ec2_vpc используйте ec2_vpc_net вместе с поддерживающими модулями ec2_vpc_igw, ec2_vpc_route_table, ec2_vpc_subnet, ec2_vpc_dhcp_option, ec2_vpc_nat_gateway, ec2_vpc_nacl вместо этого.
ec2_ami_search используйте ec2_ami_facts вместо этого
docker используйте docker_container и docker_image вместо этого

Примечание

У этих модулей может больше не быть документации в текущей версии выпуска. Обратитесь к документации модулей Ansible 2.4, если вам нужно узнать, как они работали для переноса ваших playbook.

Замечания о устаревании

Следующие модули будут удалены в Ansible 2.9. Пожалуйста, обновите ваши playbook соответственно.

Модули aos_* Apstra устарели, так как они не работают с AOS 2.1 или более поздними версиями. См. новые модули по адресу https://github.com/apstra.
nxos_ip_interface используйте nxos_l3_interface вместо этого.
nxos_portchannel используйте nxos_linkagg вместо этого.
nxos_switchport используйте nxos_l2_interface вместо этого.
panos_security_policy используйте panos_security_rule вместо этого.
panos_nat_policy используйте panos_nat_rule вместо этого.
vsphere_guest используйте vmware_guest вместо этого.

Заметные изменения в модулях

Модули stat и win_stat изменили значение по умолчанию для опции get_md5 с true на false.

Эта опция будет удалена, начиная с версии Ansible 2.9. Опции get_checksum: True и checksum_algorithm: md5 по-прежнему могут быть использованы, если требуется контрольная сумма MD5.

Модуль osx_say был переименован в say.
Несколько модулей, которые могли обрабатывать символические ссылки, изменили значение по умолчанию своей опции follow в рамках функции стандартизации поведения follow:
- Модуль file module изменил значение по умолчанию с follow=False на follow=True, так как его цель состоит в изменении атрибутов файла, а большинство систем не позволяют применять атрибуты к символическим ссылкам, только к реальным файлам.
- У модуля replace module был удален параметр follow, потому что он изначально изменяет содержимое существующего файла, поэтому нет смысла работать с самой ссылкой.
- У модуля blockinfile module был удален параметр follow, потому что он изначально изменяет содержимое существующего файла, поэтому нет смысла работать с самой ссылкой.
- В Ansible-2.5.3 модуль template module стал более строгим в отношении файла src, требуя его правильного кодирования в UTF-8. Раньше не-UTF-8 содержимое в файле источника модуля template приводило к испорченному выходному файлу (символы не-UTF-8 заменялись универсальным символом замены). Теперь, на Python2, модуль выдаст ошибку с сообщением «Файлы шаблонов должны быть закодированы в UTF-8». На Python3 модуль сначала попытается пройти не-UTF-8 символы напрямую и завершится ошибкой, если это не сработает.

Плагины

Как разработчик, теперь вы можете использовать «фрагменты документации» для общих параметров конфигурации для типов плагинов, которые поддерживают новую систему конфигурации плагинов.

Инвентаризация

Плагины инвентаризации были доработаны, и мы начали добавлять некоторые общие возможности:

Возможность использования плагина кэша для избежания дорогостоящих запросов к API/БД по умолчанию отключена. Если вы используете скрипты инвентаризации, некоторые из них могут уже поддерживать кэш, но это находится вне зоны видимости и контроля Ansible. Переход к внутреннему кэшу позволит вам использовать существующие механизмы обновления/очистки кэша Ansible.
Новый плагин «auto», включённый по умолчанию, может автоматически определить правильный плагин для использования, ЕСЛИ этот плагин использует наш «общий формат конфигурации YAML». Предыдущие плагины host_list, script, yaml и ini по-прежнему работают так же, как и раньше, а плагин auto теперь используется в последнюю очередь. Если вы настраивали включённые плагины, вам следует пересмотреть настройки, чтобы включить новый плагин auto.

Shell

Плагины Shell были мигрированы в новую систему конфигурации плагинов. Теперь можно настроить больше параметров, а параметры, которые ранее были «глобальными», теперь также могут быть переопределены с помощью переменных, специфичных для хоста.

Например, system_temps — новая настройка, которая позволяет управлять тем, что Ansible будет рассматривать как «временную директорию системы». Это используется при повышении привилегий для пользователя, не имеющего прав администратора. Ранее это было жёстко закодировано в «/tmp», что некоторые системы не могут использовать для повышения привилегий. Теперь эта настройка по умолчанию [ '/var/tmp', '/tmp'].

Другая новая настройка admin_users позволяет указать список пользователей, которые будут считаться «администраторами». Ранее это было жёстко закодировано в root. Теперь оно имеет значение по умолчанию [root, toor, admin]. Эта информация используется при выборе между вашими каталогами remote_temp и system_temps.

Для получения полного списка ознакомьтесь с используемым вами плагином shell, плагин shell по умолчанию sh.

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

Фильтр

API плагина поиска теперь выдает ошибку, если из плагина возвращается неитерируемое значение. Ранее числа и другие неитерируемые типы, возвращаемые плагином, принимались без ошибок или предупреждений. Это изменение было сделано, потому что плагины всегда должны возвращать список. Обратите внимание, что плагины, возвращающие строки и другие несписочные итерируемые значения, не будут генерировать ошибку, но могут привести к непредсказуемому поведению. Если у вас есть пользовательский плагин поиска, который не возвращает список, вы должны изменить его, чтобы обернуть возвращаемые значения в список.

Поиск

Для плагинов поиска была добавлена новая глобальная опция error, которая позволяет управлять обработкой ошибок, генерируемых поиском, прежде чем эта опция всегда приводила к фатальной ошибке. Допустимые значения для этой опции — warn, ignore и strict. Дополнительные сведения см. на странице поиска.

Перенос пользовательских скриптов

Нет заметных изменений.

Сеть

Расширение документации

Мы расширяем документацию по сети. Есть новые материалы и новая стартовая страница Ansible Network. Мы будем продолжать развивать документацию, связанную с сетью.

Аргументы подключения верхнего уровня будут удалены в версии 2.9

Аргументы подключения верхнего уровня, такие как username, host, и password, устарели и будут удалены в версии 2.9.

СТАРЫЙ В Ansible < 2.4

- name: example of using top-level options for connection properties
  ios_command:
    commands: show version
    host: "{{ inventory_hostname }}"
    username: cisco
    password: cisco
    authorize: yes
    auth_pass: cisco

Предупреждения об устаревании отражают этот график. Задача выше, запущенная в Ansible 2.5, приведет к:

[DEPRECATION WARNING]: Param 'username' is deprecated. See the module docs for more information. This feature will be removed in version
2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
[DEPRECATION WARNING]: Param 'password' is deprecated. See the module docs for more information. This feature will be removed in version
2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
[DEPRECATION WARNING]: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9.
Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.

Мы рекомендуем использовать новые типы подключения network_cli и netconf (см. ниже), использовать стандартные свойства подключения Ansible и устанавливать эти свойства в инвентаре по группам. Обновляя файлы playbook и инвентаря, вы можете легко внести изменение на become для повышения привилегий (на платформах, которые это поддерживают). Дополнительные сведения см. в руководстве использования become с модулями сети и в документации по платформам.

Добавление типов постоянных подключений `network_cli` и `netconf`

Ansible 2.5 вводит два типа постоянных подключений верхнего уровня: network_cli и netconf. С connection: local, каждая задача передавала параметры подключения, которые нужно было хранить в ваших playbook. С network_cli и netconf playbook передает параметры подключения один раз, поэтому вы можете передать их в командной строке, если хотите. Мы рекомендуем использовать network_cli и netconf по возможности. Обратите внимание, что eAPI и NX-API по-прежнему требуют подключений local с provider словарями. Дополнительные сведения см. в документации по платформам. Если вам не нужно подключение local, обновите свои playbook, чтобы использовать network_cli или netconf и указать переменные подключения с помощью стандартных переменных подключения Ansible:

СТАРЫЙ В Ansible 2.4

---
vars:
    cli:
       host: "{{ inventory_hostname }}"
       username: operator
       password: secret
       transport: cli

tasks:
- nxos_config:
    src: config.j2
    provider: "{{ cli }}"
    username: admin
    password: admin

НОВЫЙ В Ansible 2.5

[nxos:vars]
ansible_connection=network_cli
ansible_network_os=nxos
ansible_user=operator
ansible_password=secret

tasks:
- nxos_config:
    src: config.j2

Использование словаря провайдера с network_cli или netconf приведет к предупреждению.

Разработчики: Общие утилиты модулей перемещены

Начиная с Ansible 2.5, общие утилиты модулей для модулей сети перемещены в ansible.module_utils.network.

Платформенно-независимые утилиты находятся в ansible.module_utils.network.common
Платформенно-специфические утилиты находятся в ansible.module_utils.network.{{ platform }}

Если ваш модуль использует общие утилиты модулей, вам необходимо обновить все ссылки. Например, измените: