add porting guide for bare vars in conditionals (#60943)
This commit is contained in:
parent
36774ceb40
commit
0b7d478200
1 changed files with 101 additions and 2 deletions
|
@ -12,7 +12,8 @@ We suggest you read this page along with `Ansible Changelog for 2.8 <https://git
|
||||||
|
|
||||||
This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
|
This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
|
||||||
|
|
||||||
.. contents:: Topics
|
.. contents::
|
||||||
|
:local:
|
||||||
|
|
||||||
Playbook
|
Playbook
|
||||||
========
|
========
|
||||||
|
@ -62,12 +63,110 @@ Beginning in version 2.8, Ansible will warn if a module expects a string, but a
|
||||||
|
|
||||||
This behavior can be changed to be an error or to be ignored by setting the ``ANSIBLE_STRING_CONVERSION_ACTION`` environment variable, or by setting the ``string_conversion_action`` configuration in the ``defaults`` section of ``ansible.cfg``.
|
This behavior can be changed to be an error or to be ignored by setting the ``ANSIBLE_STRING_CONVERSION_ACTION`` environment variable, or by setting the ``string_conversion_action`` configuration in the ``defaults`` section of ``ansible.cfg``.
|
||||||
|
|
||||||
|
|
||||||
Command line facts
|
Command line facts
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
``cmdline`` facts returned in system will be deprecated in favor of ``proc_cmdline``. This change handles special case where Kernel command line parameter contains multiple values with the same key.
|
``cmdline`` facts returned in system will be deprecated in favor of ``proc_cmdline``. This change handles special case where Kernel command line parameter contains multiple values with the same key.
|
||||||
|
|
||||||
|
Bare variables in conditionals
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
In Ansible 2.7 and earlier, top-level variables sometimes treated boolean strings as if they were boolean values. This led to inconsistent behavior in conditional tests built on top-level variables defined as strings. Ansible 2.8 began changing this behavior. For example, if you set two conditions like this:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- include_tasks: teardown.yml
|
||||||
|
when: teardown
|
||||||
|
|
||||||
|
- include_tasks: provision.yml
|
||||||
|
when: not teardown
|
||||||
|
|
||||||
|
based on a variable you define **as a string** (with quotation marks around it):
|
||||||
|
|
||||||
|
* In Ansible 2.7 and earlier, the two conditions above evaluated as ``True`` and ``False`` respectively if ``teardown: 'true'``
|
||||||
|
* In Ansible 2.7 and earlier, both conditions evaluated as ``False`` if ``teardown: 'false'``
|
||||||
|
* In Ansible 2.8 and later, you have the option of disabling conditional bare variables, so ``when: teardown`` always evaluates as ``True`` and ``when: not teardown`` always evaluates as ``False`` when ``teardown`` is a non-empty string (including ``'true'`` or ``'false'``)
|
||||||
|
|
||||||
|
Ultimately, ``when: 'string'`` will always evaluate as ``True`` and ``when: not 'string'`` will always evaluate as ``False``, as long as ``'string'`` is not empty, even if the value of ``'string'`` itself looks like a boolean. For users with playbooks that depend on the old behavior, we added a config setting that preserves it. You can use the ``ANSIBLE_CONDITIONAL_BARE_VARS`` environment variable or ``conditional_bare_variables`` in the ``defaults`` section of ``ansible.cfg`` to select the behavior you want on your control node. The default setting is ``true``, which preserves the old behavior. Set the config value or environment variable to ``false`` to start using the new option.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
In 2.10 the default setting for ``conditional_bare_variables`` will change to ``false``. In 2.12 the old behavior will be deprecated.
|
||||||
|
|
||||||
|
Updating your playbooks
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
To prepare your playbooks for the new behavior, you must update your conditional statements so they accept only boolean values. For variables, you can use the ``bool`` filter to evaluate the string ``'false'`` as ``False``:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
vars:
|
||||||
|
teardown: 'false'
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- include_tasks: teardown.yml
|
||||||
|
when: teardown | bool
|
||||||
|
|
||||||
|
- include_tasks: provision.yml
|
||||||
|
when: not teardown | bool
|
||||||
|
|
||||||
|
Alternatively, you can re-define your variables as boolean values (without quotation marks) instead of strings:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
vars:
|
||||||
|
teardown: false
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- include_tasks: teardown.yml
|
||||||
|
when: teardown
|
||||||
|
|
||||||
|
- include_tasks: provision.yml
|
||||||
|
when: not teardown
|
||||||
|
|
||||||
|
For dictionaries and lists, use the ``length`` filter to evaluate the presence of a dictionary or list as ``True``:
|
||||||
|
|
||||||
|
.. code-block:: yaml+jinja
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
when: my_list | length > 0
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
when: my_dictionary | length > 0
|
||||||
|
|
||||||
|
Do not use the ``bool`` filter with lists or dictionaries. If you use ``bool`` with a list or dict, Ansible will always evaluate it as ``False``.
|
||||||
|
|
||||||
|
Double-interpolation
|
||||||
|
^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The ``conditional_bare_variables`` setting also affects variables set based on other variables. The old behavior unexpectedly double-interpolated those variables. For example:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
vars:
|
||||||
|
double_interpolated: 'bare_variable'
|
||||||
|
bare_variable: false
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- debug:
|
||||||
|
when: double_interpolated
|
||||||
|
|
||||||
|
* In Ansible 2.7 and earlier, ``when: double_interpolated`` evaluated to the value of ``bare_variable``, in this case, ``False``. If the variable ``bare_variable`` is undefined, the conditional fails.
|
||||||
|
* In Ansible 2.8 and later, with bare variables disabled, Ansible evaluates ``double_interpolated`` as the string ``'bare_variable'``, which is ``True``.
|
||||||
|
|
||||||
|
To double-interpolate variable values, use curly braces:
|
||||||
|
|
||||||
|
.. code-block:: yaml+jinja
|
||||||
|
|
||||||
|
vars:
|
||||||
|
double_interpolated: "{{ other_variable }}"
|
||||||
|
other_variable: false
|
||||||
|
|
||||||
|
Nested variables
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The ``conditional_bare_variables`` setting does not affect nested variables. Any string value assigned to a subkey is already respected and not treated as a boolean. If ``complex_variable['subkey']`` is a non-empty string, then ``when: complex_variable['subkey']`` is always ``True`` and ``when: not complex_variable['subkey']`` is always ``False``. If you want a string subkey like ``complex_variable['subkey']`` to be evaluated as a boolean, you must use the ``bool`` filter.
|
||||||
|
|
||||||
Python Interpreter Discovery
|
Python Interpreter Discovery
|
||||||
============================
|
============================
|
||||||
|
|
Loading…
Reference in a new issue