Руководство по переносу Ansible-core 2.19

Пример — неявное преобразование в логический тип

Это выражение полагается на неявную оценку inventory_hostname как истинного значения. Вместо этого следует использовать явный предикат с логическим результатом, например | length > 0 или is truthy.

- assert:
    that: inventory_hostname

Сообщение об ошибке:

Conditional result was 'localhost' of type 'str', which evaluates to True. Conditionals must have a boolean result.

Исправить это можно, выполнив явное преобразование в логическое значение:

- assert:
    that: inventory_hostname | length > 0

Пример — непреднамеренное истинное условие

Вторая часть этого условия ошибочно заключена в кавычки. Заключенная в кавычки часть становится результатом выражения (который оценивается как истинный), поэтому выражение никогда не может быть False.

- assert:
    that: inventory_hostname is defined and 'inventory_hostname | length > 0'

Сообщение об ошибке:

Conditional result was 'inventory_hostname | length > 0' of type 'str', which evaluates to True. Conditionals must have a boolean result.

Исправить это можно, убрав лишние кавычки:

- assert:
    that: inventory_hostname is defined and inventory_hostname | length > 0

Пример — синтаксическая ошибка в выражении

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

- assert:
    that: 1 == 2,
#               ^ invalid comma

Сообщение об ошибке:

Syntax error in expression: chunk after expression

Исправить это можно, удалив недопустимую запятую после выражения.

Пример — порядок операций в Jinja

В этом выражении используется оператор конкатенации ~, который выполняется после проверки contains. Результатом всегда является непустая строка, которая считается истинной.

- assert:
    that: inventory_hostname is contains "local" ~ "host"

Сообщение об ошибке:

Conditional result was 'Truehost' of type 'str', which evaluates to True. Conditionals must have a boolean result.

Исправить это можно, добавив скобки, чтобы выполнить операцию конкатенации до проверки contains:

- assert:
    that: inventory_hostname is contains("local" ~ "host")

Пример — словарь в качестве условия

Это условие следовало заключить в кавычки. В элементе списка YAML строка без кавычек, содержащая пробел после двоеточия, интерпретируется анализатором YAML как отображение. Непустые отображения всегда считаются истинными.

- assert:
    that:
     - result.msg == "some_key: some_value"
#                             ^^ colon+space == problem

Сообщение об ошибке:

Conditional expressions must be strings.

Исправить это можно, заключив все выражение утверждения в кавычки:

- assert:
    that:
     - 'result.msg == "some_key: some_value"'

Пример — ненужный шаблон в выражении

В этом условии переменная указывается с помощью шаблона вместо прямого обращения к ней в выражении.

- assert:
    that: 1 + {{ value }} == 2
  vars:
    value: 1

Сообщение об ошибке:

Syntax error in expression. Template delimiters are not supported in expressions: expected token ':', got '}'

Исправить это можно, обратившись к переменной без шаблона:

- assert:
    that: 1 + value == 2
  vars:
    value: 1

Пример — динамическое построение выражения

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

- assert:
    that: inventory_hostname {{ comparison }} 'localhost'
  vars:
    comparison: ==

Сообщение об ошибке:

Syntax error in expression. Template delimiters are not supported in expressions: chunk after expression

Динамическое построение выражений в плейбуках небезопасно и не поддерживается.

Пример — отсутствующий default(omit)

Следующая задача пытается передать omit из цикла в задачу, но значение не определено, поскольку оно было пропущено:

- debug:
    msg: "{{ item.msg }}"  # 'msg' is undefined
  loop:
   - msg: "{{ omit }}"  # 'msg' will be omitted from the loop item

В этой обновленной задаче для отсутствующего значения используется default(omit), чтобы оно было пропущено при обработке задачи:

- debug:
    msg: "{{ item.msg | default(omit) }}"  # 'msg' is undefined, use 'default(omit)' to turn it into an omit
  loop:
   - msg: "{{ omit }}"  # passed through in earlier versions, this value is now omitted from the loop item

Инверсия модели доверия шаблонам

Ранее ansible-core неявно считал все строковые значения доверенными и обрабатывал их как шаблоны Jinja, но строки из недоверенных источников (например, результаты модулей) оборачивал в объект «небезопасной» строки. Механизм обработки шаблонов молча игнорировал строки в такой оболочке, поскольку многие операции с шаблонами могут выполнять произвольный код на управляющем узле от имени пользователя, запускающего ansible-core. Поэтому любой код, работающий со строками, должен был правильно передавать объект-оболочку, что привело к появлению многочисленных уязвимостей RCE (удаленного выполнения кода), достойных присвоения CVE.

В этом выпуске предыдущая модель доверия инвертирована. Обрабатывать как шаблоны можно только строки, помеченные как загруженные из доверенного источника. На недоверенные значения, как и раньше, можно ссылаться в шаблонах, но само выражение шаблона всегда должно быть доверенным. Хотя при таком изменении по-прежнему необходимо учитывать передачу маркеров доверия при работе со строками, их отсутствие теперь приводит к утрате возможности обработки шаблона, а не к потенциально серьезной проблеме безопасности.

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

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

В большинстве случаев совместимое с предыдущими версиями поведение доверия к шаблонам применяется автоматически. Например, шаблоны в плейбуках, ролях, файлах переменных и большинстве встроенных плагинов инвентаризации будут считаться доверенными. Пользовательским плагинам, получающим строки шаблонов из источников, потребуется использовать новые общедоступные API для применения доверия там, где это необходимо.

Дополнительные сведения см. в разделах API плагинов и Диагностика проблем с недоверенными шаблонами.

Обязательный нативный режим Jinja

Предыдущие версии поддерживали два режима обработки шаблонов:

• Исходный режим обработки строк в Jinja преобразовывал результат каждой операции обработки шаблона в строку.
• Нативный режим Jinja обычно сохранял типы переменных в результатах шаблонов.

В обоих режимах ansible-core вычислял результаты обработки конечных строк шаблонов как литералы Python, а в случае ошибки возвращал исходную строку. Выбор режима обработки шаблонов задавался конфигурацией; по умолчанию использовался исходный режим обработки строк Jinja.

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

Сохранение нативных типов при обработке шаблонов улучшено, чтобы устранить пробелы в предыдущей реализации; заключительный этап вычисления литералов полностью удален (он часто вызывал путаницу, ошибки и проблемы с производительностью). В редких случаях, когда плейбуки полагались на неявное преобразование объектов из строк, потребуется явное преобразование.

Некоторые существующие шаблоны могут непреднамеренно преобразовывать значения, не являющиеся строками, в строки. В предыдущих версиях это преобразование могло маскироваться вычислением строк в качестве литералов Python.

- debug:
    msg: "{{ ['test1', 'test2'] | replace('test', 'prod') }}"

ok: [localhost] => {
    "msg": "['prod1', 'prod2']"
}

- debug:
    msg: "{{ ['test1', 'test2'] | map('replace', 'test', 'prod') }}"

ok: [localhost] => {
    "msg": [
        "prod1",
        "prod2"
    ]
}

- set_fact:
    # If 'foo' is not defined, the else branch basically evaluates to None.
    # So value_none will not be an empty string, but None:
    value_none: |-
      {% if foo is defined %}foo is defined{% endif %}

- set_fact:
    # Explicitly return an empty string in the 'else' branch.
    # The value is always a string: either "foo is defined" or "".
    value_none: |-
      {% if foo is defined %}foo is defined{% else %}{{ "" }}{% endif %}

Отложенная обработка шаблонов

Интерфейс Ansible к механизму обработки шаблонов Jinja был существенно усовершенствован, что значительно повысило производительность многих сложных операций с шаблонами. Ранее глубоко вложенные, рекурсивные или ссылающиеся на себя операции обработки шаблонов всегда вычислялись полностью при каждом обращении, в том числе при повторном обращении к одним и тем же данным в рамках одной операции обработки шаблона. Это приводило к затратному повторному вычислению одних и тех же шаблонов в рамках одной логической операции, даже если шаблоны находились глубоко во вложенных структурах данных и к ним не обращались напрямую. Новый механизм шаблонов откладывает практически всю рекурсию и обработку до момента обращения к значениям или до момента, когда становится известно, что они покидают механизм обработки шаблонов. Промежуточные вложенные или косвенно обработанные результаты шаблонов кэшируются на время выполнения операции, что сокращает количество повторных вычислений. В реальных сценариях со сложными шаблонами эти изменения обеспечили экспоненциальный рост производительности.

Единообразная обработка range

Результат использования глобальной функции Jinja range() сильно зависел от контекста ее вызова и от того, был ли включен нативный режим Jinja. Чтобы сохранить возможность использовать очень большие диапазоны в цепочках фильтров, теперь функция всегда возвращает объект range. Это означает, что его нельзя вернуть из шаблона без предварительного преобразования в возвращаемый тип.

- debug:
  loop: "{{ range(0, 2) }}"

Error rendering template: Type 'range' is unsupported for variable storage.

- debug:
  loop: "{{ range(0, 2) | list }}"

- debug:
    msg: "{{ [range(0,2), range(7,10)] }}"

ok: [localhost] => {
    "msg": "[range(0, 2), range(7, 10)]"
}

- debug:
    msg: "{{ [range(0,2), range(7,10)] | string }}"

- debug:
    msg: "{{ [range(0,2), range(7,10)] | map('list') }}"

Контекстные предупреждения и ошибки

Изменения внутренней обработки ошибок в ansible-core будут заметны во многих ситуациях, приводящих к предупреждению или ошибке. В большинстве случаев в сообщениях для пользователей указываются операционный контекст (что происходило в момент возникновения ошибки или предупреждения) и задействованные элементы данных. Ошибки и предупреждения, возникающие во время выполнения задачи, более последовательно включаются в результат задачи. Полная информация доступна обработчикам обратных вызовов, а в случае ошибок краткое сообщение об ошибке содержится в поле msg результата. Из-за стандартизированного характера обработки ошибок в некоторых сообщениях могут встречаться кажущиеся избыточными элементы. Со временем они будут улучшаться по мере доработки обработки ошибок, но сейчас необходимы для обеспечения правильного контекста во всех ситуациях возникновения ошибок. Содержимое сообщений об ошибках не считается стабильным, поэтому по возможности не следует создавать автоматизацию, зависящую от него.

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

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

Предупреждения об устаревании при обращении к значениям

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

Например, обращение к устаревшей магической переменной play_hosts вызовет предупреждение об устаревании с рекомендацией использовать вместо нее переменную ansible_play_batch.

Улучшенная обработка ошибок модулей Ansible

Обработку исключений для модулей Ansible, реализованных на Python, теперь обеспечивает оболочка AnsiballZ. В предыдущих версиях ansible-core необработанные исключения в модуле Ansible просто выводили трассировку стека и завершали работу без стандартного ответа модуля. В результате задача получала общее сообщение MODULE FAILURE и любой необработанный текстовый вывод модуля.

Для решения этой проблемы в модулях часто реализовывали ненужные блоки try/except вокруг большей части кода, для которого нельзя было предусмотреть специальную обработку ошибок, только чтобы вызвать AnsibleModule.fail_json с общим сообщением о сбое. Теперь такой подход не нужен: все необработанные исключения в модулях Ansible на Python перехватываются оболочкой AnsiballZ и возвращаются в виде структурированного результата модуля. Если контроллер включил соответствующую настройку, информация о трассировке стека добавляется автоматически.

Улучшенная обработка неопределенных значений

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

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

- stat:
    path: /does-not-exist
  register: result
  failed_when: result.exists is false
  #                   ^ missing reference to stat

- stat:
    path: /does-not-exist
  register: result
  failed_when: result.stat.exists is false

Отображение трассировок стека

В предыдущих версиях ansible-core трассировки стека для некоторых ошибок на стороне контроллера можно было получить, увеличив подробность вывода с помощью параметра -vvv, но доступность этой функции и ее поведение были непоследовательными. Кроме того, функция работала только для ошибок.

Обработка ошибок, предупреждений и уведомлений об устаревании в большей части кодовой базы ansible-core теперь стандартизирована. С помощью переменной среды ANSIBLE_DISPLAY_TRACEBACK можно включить сбор и отображение трассировок стека для всех исключений, а также в месте возникновения ошибок, предупреждений или уведомлений об устаревании (в том числе в коде модулей).

Допустимые значения:

• always — трассировки стека отображаются всегда. Этот параметр имеет приоритет над всеми приведенными ниже.
• never — трассировки стека никогда не отображаются. Этот параметр имеет приоритет над всеми приведенными ниже.
• error — трассировки стека отображаются для ошибок.
• warning — трассировки стека отображаются для всех предупреждений, кроме предупреждений об устаревании.
• deprecated — трассировки стека отображаются для предупреждений об устаревании.

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

Предупреждение при наличии неопределенных переменных в файлах vars

В предыдущих версиях ansible-core неопределенные переменные, использовавшиеся при указании путей к файлам в vars_files, молча игнорировались и не вызывали предупреждений. Теперь поведение изменено: при обнаружении неопределенных переменных во время указания путей к файлам в vars_files будет выводиться предупреждение.

- hosts: all
  vars_files:
    - "{{ inventory_dir }}/vars_files/bar.yml"

PLAYBOOK: foo.yml ************************************************************************
1 plays in foo.yml
[WARNING]: skipping vars_file item due to an undefined variable
Origin: /examples/foo.yml:6:7

4
5   vars_files:
6     - "{{ inventory_dir }}/vars_files/bar.yml"
        ^ column 7

В приведенном выше примере предупреждение отображается, поскольку inventory_dir — это переменная уровня узла, вычисляемая на уровне задачи, а не на уровне плейбука, где обрабатывается vars_files. Хотя inventory_dir не работает в vars_files, ее можно использовать в переменных уровня задачи, где уже доступны переменные из vars_files.