From 0b7d478200676e66598cf16411a13d1ed0596a3f Mon Sep 17 00:00:00 2001 From: Sloane Hertel Date: Thu, 29 Aug 2019 08:08:29 -0400 Subject: [PATCH] add porting guide for bare vars in conditionals (#60943) --- .../rst/porting_guides/porting_guide_2.8.rst | 103 +++++++++++++++++- 1 file changed, 101 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index 2829002bcc2..7267a78c2c7 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -12,7 +12,8 @@ We suggest you read this page along with `Ansible Changelog for 2.8 `. -.. contents:: Topics +.. contents:: + :local: 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``. - 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. +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 ============================