"Fossies" - the Fresh Open Source Software Archive 
Source code changes of the file "docs/docsite/rst/porting_guides/porting_guide_2.0.rst" between
ansible-2.14.0.tar.gz and ansible-2.14.1rc1.tar.gz
About: Ansible is an IT Configuration Management, Deployment & Orchestration tool. Release candidate.
| porting_guide_2.0.rst (ansible-2.14.0) | : | porting_guide_2.0.rst (ansible-2.14.1rc1) | ||
|---|---|---|---|---|
| skipping to change at line 23 | skipping to change at line 23 | |||
| This document is part of a collection on porting. The complete list of porting g uides can be found at :ref:`porting guides <porting_guides>`. | This document is part of a collection on porting. The complete list of porting g uides can be found at :ref:`porting guides <porting_guides>`. | |||
| .. contents:: Topics | .. contents:: Topics | |||
| Playbook | Playbook | |||
| ======== | ======== | |||
| This section discusses any changes you may need to make to your playbooks. | This section discusses any changes you may need to make to your playbooks. | |||
| * Syntax in 1.9.x | ||||
| .. code-block:: yaml | .. code-block:: yaml | |||
| # Syntax in 1.9.x | ||||
| - debug: | - debug: | |||
| msg: "{{ 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\ \\2') }}" | msg: "{{ 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\ \\2') }}" | |||
| # Syntax in 2.0.x | ||||
| * Syntax in 2.0.x | ||||
| .. code-block:: yaml | ||||
| - debug: | - debug: | |||
| msg: "{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}" | msg: "{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}" | |||
| # Output: | * Output: | |||
| .. code-block:: yaml | ||||
| "msg": "test1 1\\3" | "msg": "test1 1\\3" | |||
| To make an escaped string that will work on all versions you have two options:: | To make an escaped string that will work on all versions you have two options:: | |||
| - debug: msg="{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}" | - debug: msg="{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}" | |||
| uses key=value escaping which has not changed. The other option is to check for the ansible version:: | uses key=value escaping which has not changed. The other option is to check for the ansible version:: | |||
| "{{ (ansible_version|version_compare('2.0', 'ge'))|ternary( 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') , 'test1_junk 1\\\\3' | regex_replace ('(.*)_junk (.*)', '\\\\1 \\\\2') ) }}" | "{{ (ansible_version|version_compare('2.0', 'ge'))|ternary( 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') , 'test1_junk 1\\\\3' | regex_replace ('(.*)_junk (.*)', '\\\\1 \\\\2') ) }}" | |||
| * trailing newline When a string with a trailing newline was specified in the | * trailing newline When a string with a trailing newline was specified in the | |||
| playbook through yaml dict format, the trailing newline was stripped. When | playbook through yaml dict format, the trailing newline was stripped. When | |||
| specified in key=value format, the trailing newlines were kept. In v2, both | specified in key=value format, the trailing newlines were kept. In v2, both | |||
| methods of specifying the string will keep the trailing newlines. If you | methods of specifying the string will keep the trailing newlines. If you | |||
| relied on the trailing newline being stripped, you can change your playbook | relied on the trailing newline being stripped, you can change your playbook | |||
| using the following as an example:: | using the following as an example:: | |||
| # Syntax in 1.9.x | * Syntax in 1.9.x | |||
| .. code-block:: yaml | ||||
| vars: | vars: | |||
| message: > | message: > | |||
| Testing | Testing | |||
| some things | some things | |||
| tasks: | tasks: | |||
| - debug: | - debug: | |||
| msg: "{{ message }}" | msg: "{{ message }}" | |||
| # Syntax in 2.0.x | * Syntax in 2.0.x | |||
| .. code-block:: yaml | ||||
| vars: | vars: | |||
| old_message: > | old_message: > | |||
| Testing | Testing | |||
| some things | some things | |||
| message: "{{ old_message[:-1] }}" | message: "{{ old_message[:-1] }}" | |||
| - debug: | - debug: | |||
| msg: "{{ message }}" | msg: "{{ message }}" | |||
| # Output | ||||
| * Output | ||||
| .. code-block:: yaml | ||||
| "msg": "Testing some things" | "msg": "Testing some things" | |||
| * Behavior of templating DOS-type text files changes with Ansible v2. | * Behavior of templating DOS-type text files changes with Ansible v2. | |||
| A bug in Ansible v1 causes DOS-type text files (using a carriage return and ne wline) to be templated to Unix-type text files (using only a newline). In Ansibl e v2 this long-standing bug was finally fixed and DOS-type text files are preser ved correctly. This may be confusing when you expect your playbook to not show a ny differences when migrating to Ansible v2, while in fact you will see every DO S-type file being completely replaced (with what appears to be the exact same co ntent). | A bug in Ansible v1 causes DOS-type text files (using a carriage return and ne wline) to be templated to Unix-type text files (using only a newline). In Ansibl e v2 this long-standing bug was finally fixed and DOS-type text files are preser ved correctly. This may be confusing when you expect your playbook to not show a ny differences when migrating to Ansible v2, while in fact you will see every DO S-type file being completely replaced (with what appears to be the exact same co ntent). | |||
| * When specifying complex args as a variable, the variable must use the full jin ja2 | * When specifying complex args as a variable, the variable must use the full jin ja2 | |||
| variable syntax (```{{var_name}}```) - bare variable names there are no longer accepted. | variable syntax (```{{var_name}}```) - bare variable names there are no longer accepted. | |||
| In fact, even specifying args with variables has been deprecated, and will not be | In fact, even specifying args with variables has been deprecated, and will not be | |||
| allowed in future versions:: | allowed in future versions: | |||
| .. code-block:: yaml | ||||
| --- | --- | |||
| - hosts: localhost | - hosts: localhost | |||
| connection: local | connection: local | |||
| gather_facts: false | gather_facts: false | |||
| vars: | vars: | |||
| my_dirs: | my_dirs: | |||
| - { path: /tmp/3a, state: directory, mode: 0755 } | - { path: /tmp/3a, state: directory, mode: 0755 } | |||
| - { path: /tmp/3b, state: directory, mode: 0700 } | - { path: /tmp/3b, state: directory, mode: 0700 } | |||
| tasks: | tasks: | |||
| - file: | - file: | |||
| args: "{{item}}" # <- args here uses the full variable syntax | args: "{{item}}" | |||
| with_items: "{{my_dirs}}" | with_items: "{{my_dirs}}" | |||
| * porting task includes | * porting task includes | |||
| * More dynamic. Corner-case formats that were not supposed to work now do not, a s expected. | * More dynamic. Corner-case formats that were not supposed to work now do not, a s expected. | |||
| * variables defined in the yaml dict format see `issue 13324 <https://github.com /ansible/ansible/issues/13324>`_ | * variables defined in the yaml dict format see `issue 13324 <https://github.com /ansible/ansible/issues/13324>`_ | |||
| * templating (variables in playbooks and template lookups) has improved with reg ard to keeping the original instead of turning everything into a string. | * templating (variables in playbooks and template lookups) has improved with reg ard to keeping the original instead of turning everything into a string. | |||
| If you need the old behavior, quote the value to pass it around as a string. | If you need the old behavior, quote the value to pass it around as a string. | |||
| * Empty variables and variables set to null in yaml are no longer converted to e mpty strings. They will retain the value of `None`. | * Empty variables and variables set to null in yaml are no longer converted to e mpty strings. They will retain the value of `None`. | |||
| You can override the `null_representation` setting to an empty string in your config file by setting the :envvar:`ANSIBLE_NULL_REPRESENTATION` environment var iable. | You can override the `null_representation` setting to an empty string in your config file by setting the :envvar:`ANSIBLE_NULL_REPRESENTATION` environment var iable. | |||
| * Extras callbacks must be enabled in ansible.cfg. Copying is no longer necessar y but you must enable them in ansible.cfg. | * Extras callbacks must be enabled in ansible.cfg. Copying is no longer necessar y but you must enable them in ansible.cfg. | |||
| skipping to change at line 113 | skipping to change at line 133 | |||
| `environment` at the play level and depending on `ansible_env` existing. Previ ously this was ignored but now might issue an 'Undefined' error. | `environment` at the play level and depending on `ansible_env` existing. Previ ously this was ignored but now might issue an 'Undefined' error. | |||
| Deprecated | Deprecated | |||
| ---------- | ---------- | |||
| While all items listed here will show a deprecation warning message, they still work as they did in 1.9.x. Please note that they will be removed in 2.2 (Ansible always waits two major releases to remove a deprecated feature). | While all items listed here will show a deprecation warning message, they still work as they did in 1.9.x. Please note that they will be removed in 2.2 (Ansible always waits two major releases to remove a deprecated feature). | |||
| * Bare variables in ``with_`` loops should instead use the ``"{{ var }}"`` synta x, which helps eliminate ambiguity. | * Bare variables in ``with_`` loops should instead use the ``"{{ var }}"`` synta x, which helps eliminate ambiguity. | |||
| * The ansible-galaxy text format requirements file. Users should use the YAML fo rmat for requirements instead. | * The ansible-galaxy text format requirements file. Users should use the YAML fo rmat for requirements instead. | |||
| * Undefined variables within a ``with_`` loop's list currently do not interrupt the loop, but they do issue a warning; in the future, they will issue an error. | * Undefined variables within a ``with_`` loop's list currently do not interrupt the loop, but they do issue a warning; in the future, they will issue an error. | |||
| * Using dictionary variables to set all task parameters is unsafe and will be re | * Using dictionary variables to set all task parameters is unsafe and will be re | |||
| moved in a future version. For example:: | moved in a future version. Example of a deprecated variant: | |||
| .. code-block:: yaml | ||||
| - hosts: localhost | - hosts: localhost | |||
| gather_facts: no | gather_facts: no | |||
| vars: | vars: | |||
| debug_params: | debug_params: | |||
| msg: "hello there" | msg: "hello there" | |||
| tasks: | tasks: | |||
| # These are both deprecated: | ||||
| - debug: "{{debug_params}}" | - debug: "{{debug_params}}" | |||
| - debug: | - debug: | |||
| args: "{{debug_params}}" | args: "{{debug_params}}" | |||
| # Use this instead: | Example of a recommended variant: | |||
| .. code-block:: yaml | ||||
| - hosts: localhost | ||||
| gather_facts: no | ||||
| vars: | ||||
| debug_params: | ||||
| msg: "hello there" | ||||
| tasks: | ||||
| - debug: | - debug: | |||
| msg: "{{debug_params['msg']}}" | msg: "{{debug_params['msg']}}" | |||
| * Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) t o separate hosts/groups in the pattern. | * Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) t o separate hosts/groups in the pattern. | |||
| * Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y ]. | * Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y ]. | |||
| * Playbooks using privilege escalation should always use "become*" options rathe r than the old su*/sudo* options. | * Playbooks using privilege escalation should always use "become*" options rathe r than the old su*/sudo* options. | |||
| * The "short form" for vars_prompt is no longer supported. | * The "short form" for vars_prompt is no longer supported. | |||
| For example:: | For example:: | |||
| vars_prompt: | vars_prompt: | |||
| variable_name: "Prompt string" | variable_name: "Prompt string" | |||
| End of changes. 13 change blocks. | ||||
| 13 lines changed or deleted | 43 lines changed or added | |||