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

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

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

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

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

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

OLD В Ansible 2.4:

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

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

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

    - apt:
        name: nginx
        state: latest

NEW В 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 ключевым словом или переменной. Если у вас есть playbooks, которые выглядят так:

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 вместо циклов типа with_X. Синтаксис loop обычно лучше всего выражается с помощью фильтров вместо более сложного использования query или lookup.

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

with_list

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

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

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

with_items

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

- name: with_items
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_items: "{{ items }}"

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

with_indexed_items

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

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

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

with_flattened

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

- name: with_flattened
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_flattened: "{{ items }}"

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

with_together

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

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

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

Другой пример со сложными данными

- name: with_together -> loop
  ansible.builtin.debug:
    msg: "{{ item.0 }} - {{ item.1 }} - {{ item.2 }}"
  loop: "{{ data[0]|zip(*data[1:])|list }}"
  vars:
    data:
      - ['a', 'b', 'c']
      - ['d', 'e', 'f']
      - ['g', 'h', 'i']

with_dict

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

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

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

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

with_sequence

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

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

- name: with_sequence -> loop
  ansible.builtin.debug:
    msg: "{{ 'testuser%02x' | format(item) }}"
  loop: "{{ range(0, 4 + 1, 2)|list }}"

Диапазон цикла не включает конечную точку.

with_subelements

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

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

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

with_nested/with_cartesian

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

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

- name: with_nested -> loop
  ansible.builtin.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
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_random_choice: "{{ my_list }}"

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

Использование тестов Jinja в качестве фильтров

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

Перед Ansible 2.5 тесты Jinja, включенные в Ansible, чаще всего использовались в качестве фильтров. Существенная разница в использовании заключается в том, что к фильтрам обращаются как к variable | filter_name, а к тестам Jinja как к variable is test_name.

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

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

СТАРЫЙ В Ansible 2.4 (и ранее) использование включенного в Ansible теста Jinja, вероятно, выглядело так:

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 в правильный формат. Существуют некоторые документированные ограничения, и все изменения, внесённые этим скриптом, следует проверить на правильность перед выполнением изменённых playbooks. Скрипт можно найти по адресу https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py.

Пространства имён фактов Ansible

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

Была добавлена новая конфигурационная переменная inject_facts_as_vars, в ansible.cfg. Её значение по умолчанию «True» сохраняет поведение Ansible 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.9. Пожалуйста, соответствующим образом обновите свои playbooks.

• Модули 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 изменил значение по умолчанию опции follow=False на follow=True, так как его цель заключается в изменении атрибутов файла, а большинство систем не позволяют применять атрибуты к символическим ссылкам, а только к реальным файлам.
  • У модуля replace был удалён параметр follow, так как он изначально изменяет содержимое существующего файла, поэтому не имеет смысла работать с самой ссылкой.
  • У модуля blockinfile был удалён параметр follow, так как он изначально изменяет содержимое существующего файла, поэтому не имеет смысла работать с самой ссылкой.
  • В Ansible-2.5.3 модуль template стал более строгим в отношении файла src, ожидая правильного кодирования utf-8. Раньше не utf-8 содержимое в файле шаблона src модуля 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, по умолчанию используется плагин sh.

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

Фильтр

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

Lookup

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

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

Мы расширяем документацию по сети. Есть новые материалы и новая стартовая страница 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 и устанавливая эти свойства в инвентаризации по группам. При обновлении плейбуков и файлов инвентаризации вы можете легко внести изменения в become для повышения привилегий (на платформах, которые это поддерживают). Более подробную информацию см. в руководстве использования become с модулями сети и в документации по платформам.

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

Ansible 2.5 добавляет два постоянных типа подключений верхнего уровня, network_cli и netconf. С connection: local, каждая задача передавала параметры подключения, которые нужно было хранить в плейбуках. С network_cli и netconf плейбук передает параметры подключения один раз, поэтому вы можете передать их в командной строке, если предпочитаете. Мы рекомендуем использовать network_cli и netconf всякий раз, когда это возможно. Обратите внимание, что eAPI и NX-API по-прежнему требуют подключений local с provider словарями. См. документацию по платформам для получения дополнительной информации. Если вам не нужно подключение local, обновите свои плейбуки, чтобы использовать 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 }}

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

СТАРЫЙ В Ansible 2.4

from ansible.module_utils.vyos import get_config, load_config

НОВЫЙ В Ansible 2.5

from ansible.module_utils.network.vyos.vyos import get_config, load_config

См. руководство по утилитам модулей, см. Использование и разработка утилит модулей для получения дополнительной информации.