opensourcemirror
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[2.4]Update EOL Docs - batch fix for 2.4 (#72759) 

* manually stub out old porting guides

* manually remove Edit on Github
This commit is contained in:
Sandra McCann 2020-12-01 12:43:10 -05:00 committed by GitHub
parent cb400c84e9
commit d02215d4d5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 14 additions and 829 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/docsite/_themes/srtd/breadcrumbs.html
View File

@ -1,11 +1,5 @@
<ul class="wy-breadcrumbs">
<li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
<li><a href="">{{ title }}</a></li>
{% if not pagename.endswith('_module') and (not 'list_of' in pagename) and (not 'category' in pagename) %}
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/{{ pagename }}.rst" class="icon icon-github"> Edit on GitHub</a>
</li>
{% endif %}
</ul>
<hr/>

391
docs/docsite/rst/porting_guide_2.0.rst
View File

@ -4,393 +4,8 @@
Ansible 2.0 Porting Guide
*************************
This section discusses the behavioral changes between Ansible 1.x and Ansible 2.0.
Ansible Porting Guides are maintained in the ``devel`` branch only. Please go to `the devel Ansible 2.0 Porting guide <https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.0.html>`_ for up to date information.
It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.
We suggest you read this page along with `Ansible Changelog <https://github.com/ansible/ansible/blob/devel/CHANGELOG.md#2.0>`_ to understand what updates you may need to make.
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
Playbook
========
This section discusses any changes you may need to make to your playbooks.
.. code-block:: yaml
# Syntax in 1.9.x
- debug:
msg: "{{ 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') }}"
# Syntax in 2.0.x
- debug:
msg: "{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}"
# Output:
"msg": "test1 1\\3"
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') }}"
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') ) }}"
* trailing newline When a string with a trailing newline was specified in the
playbook via yaml dict format, the trailing newline was stripped. When
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
relied on the trailing newline being stripped, you can change your playbook
using the following as an example::
# Syntax in 1.9.x
vars:
message: >
Testing
some things
tasks:
- debug:
msg: "{{ message }}"
# Syntax in 2.0.x
vars:
old_message: >
Testing
some things
message: "{{ old_messsage[:-1] }}"
- debug:
msg: "{{ message }}"
# Output
"msg": "Testing some things"
* 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 newline) to be templated to Unix-type text files (using only a newline). In Ansible v2 this long-standing bug was finally fixed and DOS-type text files are preserved correctly. This may be confusing when you expect your playbook to not show any differences when migrating to Ansible v2, while in fact you will see every DOS-type file being completely replaced (with what appears to be the exact same content).
* When specifying complex args as a variable, the variable must use the full jinja2
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
allowed in future versions::
---
- hosts: localhost
connection: local
gather_facts: false
vars:
my_dirs:
- { path: /tmp/3a, state: directory, mode: 0755 }
- { path: /tmp/3b, state: directory, mode: 0700 }
tasks:
- file:
args: "{{item}}" # <- args here uses the full variable syntax
with_items: "{{my_dirs}}"
* porting task includes
* More dynamic. Corner-case formats that were not supposed to work now do not, as expected.
* variables defined in the yaml dict format https://github.com/ansible/ansible/issues/13324
* templating (variables in playbooks and template lookups) has improved with regard 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.
* Empty variables and variables set to null in yaml are no longer converted to empty 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 variable.
* Extras callbacks must be whitelisted in ansible.cfg. Copying is no longer necessary but whitelisting in ansible.cfg must be completed.
* dnf module has been rewritten. Some minor changes in behavior may be observed.
* win_updates has been rewritten and works as expected now.
* from 2.0.1 onwards, the implicit setup task from gather_facts now correctly inherits everything from play, but this might cause issues for those setting
`environment` at the play level and depending on `ansible_env` existing. Previously this was ignored but now might issue an 'Undefined' error.
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).
* Bare variables in ``with_`` loops should instead use the ``"{ {var }}"`` syntax, which helps eliminate ambiguity.
* The ansible-galaxy text format requirements file. Users should use the YAML format 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.
* Using dictionary variables to set all task parameters is unsafe and will be removed in a future version. For example::
- hosts: localhost
gather_facts: no
vars:
debug_params:
msg: "hello there"
tasks:
# These are both deprecated:
- debug: "{{debug_params}}"
- debug:
args: "{{debug_params}}"
# Use this instead:
- debug:
msg: "{{debug_params['msg']}}"
* Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) to separate hosts/groups in the pattern.
* Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y].
* Playbooks using privilege escalation should always use "become*" options rather than the old su*/sudo* options.
* The "short form" for vars_prompt is no longer supported.
For example::
vars_prompt:
variable_name: "Prompt string"
* Specifying variables at the top level of a task include statement is no longer supported. For example::
- include_tasks: foo.yml
a: 1
Should now be::
- include_tasks: foo.yml
vars:
a: 1
* Setting any_errors_fatal on a task is no longer supported. This should be set at the play level only.
* Bare variables in the `environment` dictionary (for plays/tasks/etc.) are no longer supported. Variables specified there should use the full variable syntax: '{{foo}}'.
* Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task.
For example::
- include_tasks: foo.yml tags=a,b,c
Should be::
- include_tasks: foo.yml
tags: [a, b, c]
* The first_available_file option on tasks has been deprecated. Users should use the with_first_found option or lookup ('first_found', …) plugin.
Other caveats
-------------
Here are some corner cases encountered when updating. These are mostly caused by the more stringent parser validation and the capture of errors that were previously ignored.
* Bad variable composition::
with_items: myvar_{{rest_of_name}}
This worked 'by accident' as the errors were retemplated and ended up resolving the variable, it was never intended as valid syntax and now properly returns an error, use the following instead::
hostvars[inventory_hostname]['myvar_' + rest_of_name]
* Misspelled directives::
- task: dostuf
becom: yes
The task always ran without using privilege escalation (for that you need `become`) but was also silently ignored so the play 'ran' even though it should not, now this is a parsing error.
* Duplicate directives::
- task: dostuf
when: True
when: False
The first `when` was ignored and only the 2nd one was used as the play ran w/o warning it was ignoring one of the directives, now this produces a parsing error.
* Conflating variables and directives::
- role: {name=rosy, port=435 }
# in tasks/main.yml
- wait_for: port={{port}}
The `port` variable is reserved as a play/task directive for overriding the connection port, in previous versions this got conflated with a variable named `port` and was usable
later in the play, this created issues if a host tried to reconnect or was using a non caching connection. Now it will be correctly identified as a directive and the `port` variable
will appear as undefined, this now forces the use of non conflicting names and removes ambiguity when adding settings and variables to a role invocation.
* Bare operations on `with_`::
with_items: var1 + var2
An issue with the 'bare variable' features, which was supposed only template a single variable without the need of braces ({{ )}}, would in some versions of Ansible template full expressions.
Now you need to use proper templating and braces for all expressions everywhere except conditionals (`when`)::
with_items: "{{var1 + var2}}"
The bare feature itself is deprecated as an undefined variable is indistinguishable from a string which makes it difficult to display a proper error.
Porting plugins
===============
In ansible-1.9.x, you would generally copy an existing plugin to create a new one. Simply implementing the methods and attributes that the caller of the plugin expected made it a plugin of that type. In ansible-2.0, most plugins are implemented by subclassing a base class for each plugin type. This way the custom plugin does not need to contain methods which are not customized.
Lookup plugins
--------------
* lookup plugins ; import version
Connection plugins
------------------
* connection plugins
Action plugins
--------------
* action plugins
Callback plugins
----------------
Although Ansible 2.0 provides a new callback API the old one continues to work
for most callback plugins. However, if your callback plugin makes use of
:attr:`self.playbook`, :attr:`self.play`, or :attr:`self.task` then you will
have to store the values for these yourself as ansible no longer automatically
populates the callback with them. Here's a short snippet that shows you how:
.. code-block:: python
import os
from ansible.plugins.callback import CallbackBase
class CallbackModule(CallbackBase):
def __init__(self):
self.playbook = None
self.playbook_name = None
self.play = None
self.task = None
def v2_playbook_on_start(self, playbook):
self.playbook = playbook
self.playbook_name = os.path.basename(self.playbook._file_name)
def v2_playbook_on_play_start(self, play):
self.play = play
def v2_playbook_on_task_start(self, task, is_conditional):
self.task = task
def v2_on_any(self, *args, **kwargs):
self._display.display('%s: %s: %s' % (self.playbook_name,
self.play.name, self.task))
Connection plugins
------------------
* connection plugins
Hybrid plugins
==============
In specific cases you may want a plugin that supports both ansible-1.9.x *and* ansible-2.0. Much like porting plugins from v1 to v2, you need to understand how plugins work in each version and support both requirements.
Since the ansible-2.0 plugin system is more advanced, it is easier to adapt your plugin to provide similar pieces (subclasses, methods) for ansible-1.9.x as ansible-2.0 expects. This way your code will look a lot cleaner.
You may find the following tips useful:
* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``).
* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (e.g. importing specific methods).
* Use the existence of these methods as a qualifier to what version of Ansible you are running. So rather than using version checks, you can do capability checks instead. (See examples below)
* Document for each if-then-else case for which specific version each block is needed. This will help others to understand how they have to adapt their plugins, but it will also help you to remove the older ansible-1.9.x support when it is deprecated.
* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (e.g. cases where you expect misconfigurations).
* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes, and methods are available.
Lookup plugins
--------------
As a simple example we are going to make a hybrid ``fileglob`` lookup plugin.
.. code-block:: python
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
import os
import glob
try:
# ansible-2.0
from ansible.plugins.lookup import LookupBase
except ImportError:
# ansible-1.9.x
class LookupBase(object):
def __init__(self, basedir=None, runner=None, **kwargs):
self.runner = runner
self.basedir = self.runner.basedir
def get_basedir(self, variables):
return self.basedir
try:
# ansible-1.9.x
from ansible.utils import (listify_lookup_plugin_terms, path_dwim, warning)
except ImportError:
# ansible-2.0
from __main__ import display
warning = display.warning
class LookupModule(LookupBase):
# For ansible-1.9.x, we added inject=None as valid argument
def run(self, terms, inject=None, variables=None, **kwargs):
# ansible-2.0, but we made this work for ansible-1.9.x too !
basedir = self.get_basedir(variables)
# ansible-1.9.x
if 'listify_lookup_plugin_terms' in globals():
terms = listify_lookup_plugin_terms(terms, basedir, inject)
ret = []
for term in terms:
term_file = os.path.basename(term)
# For ansible-1.9.x, we imported path_dwim() from ansible.utils
if 'path_dwim' in globals():
# ansible-1.9.x
dwimmed_path = path_dwim(basedir, os.path.dirname(term))
else:
# ansible-2.0
dwimmed_path = self._loader.path_dwim_relative(basedir, 'files', os.path.dirname(term))
globbed = glob.glob(os.path.join(dwimmed_path, term_file))
ret.extend(g for g in globbed if os.path.isfile(g))
return ret
.. Note:: In the above example we did not use the ``warning()`` method as we had no direct use for it in the final version. However we left this code in so people can use this part during development/porting/use.
Connection plugins
------------------
* connection plugins
Action plugins
--------------
* action plugins
Callback plugins
----------------
* callback plugins
Connection plugins
------------------
* connection plugins
Porting custom scripts
======================
Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to: :doc:`dev_guide/developing_api`
.. note::
This link takes you to a different version of the Ansible documentation. Use the version selection on the left or your browser back button to return to this version of the documentation.

219
docs/docsite/rst/porting_guide_2.3.rst
View File

@ -4,221 +4,8 @@
Ansible 2.3 Porting Guide
*************************
This section discusses the behavioral changes between Ansible 2.2 and Ansible 2.3.
Ansible Porting Guides are maintained in the ``devel`` branch only. Please go to `the devel Ansible 2.3 Porting guide <https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.3.html>`_ for up to date information.
It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.
.. note::
We suggest you read this page along with `Ansible Changelog <https://github.com/ansible/ansible/blob/devel/CHANGELOG.md#2.3>`_ to understand what updates you may need to make.
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
Playbook
========
Restructued async to work with action plugins
---------------------------------------------
In Ansible 2.2 (and possibly earlier) the `async:` keyword could not be used in conjunction with the action plugins such as `service`. This limitation has been removed in Ansible 2.3
**NEW** In Ansible 2.3:
.. code-block:: yaml
- name: Install nginx asynchronously
service:
name: nginx
state: restarted
async: 45
OpenBSD version facts
---------------------
The `ansible_distribution_release` and `ansible_distribution_version` facts on OpenBSD hosts were reversed in Ansible 2.2 and earlier. This has been changed so that version has the numeric portion and release has the name of the release.
**OLD** In Ansible 2.2 (and earlier)
.. code-block:: yaml
"ansible_distribution": "OpenBSD"
"ansible_distribution_release": "6.0",
"ansible_distribution_version": "release",
**NEW** In Ansible 2.3:
.. code-block:: yaml
"ansible_distribution": "OpenBSD",
"ansible_distribution_release": "release",
"ansible_distribution_version": "6.0",
Names Blocks
------------
Blocks can now have names, this allows you to avoid the ugly `# this block is for...` comments.
**NEW** In Ansible 2.3:
.. code-block:: yaml
- name: Block test case
hosts: localhost
tasks:
- name: Attempt to setup foo
block:
- debug: msg='I execute normally'
- command: /bin/false
- debug: msg='I never execute, cause ERROR!'
rescue:
- debug: msg='I caught an error'
- command: /bin/false
- debug: msg='I also never execute :-('
always:
- debug: msg="this always executes"
Use of multiple tags
--------------------
Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last specified tag overriding all the other specified tags. This behaviour is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behaviour.
In 2.4, the default will be to merge the tags. You can enable the old overwriting behavior via the config option.
In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behaviour.
Other caveats
-------------
Here are some rare cases that might be encountered when updating. These are mostly caused by the more stringent parser validation and the capture of errors that were previously ignored.
* Made ``any_errors_fatal`` inheritable from play to task and all other objects in between.
Modules
=======
No major changes in this version.
Modules removed
---------------
No major changes in this version.
Deprecation notices
-------------------
The following modules will be removed in Ansible 2.5. Please update your playbooks accordingly.
* :ref:`ec2_vpc <ec2_vpc>`
* :ref:`cl_bond <cl_bond>`
* :ref:`cl_bridge <cl_bridge>`
* :ref:`cl_img_install <cl_img_install>`
* :ref:`cl_interface <cl_interface>`
* :ref:`cl_interface_policy <cl_interface_policy>`
* :ref:`cl_license <cl_license>`
* :ref:`cl_ports <cl_ports>`
* :ref:`nxos_mtu <nxos_mtu>` use :ref:`nxos_system <nxos_system>` instead
Noteworthy module changes
-------------------------
AWS lambda
^^^^^^^^^^
Previously ignored changes that only affected one parameter. Existing deployments may have outstanding changes that this bug fix will apply.
Mount
^^^^^
Mount: Some fixes so bind mounts are not mounted each time the playbook runs.
Plugins
=======
No major changes in this version.
Porting custom scripts
======================
No major changes in this version.
Networking
==========
There have been a number of changes to number of changes to how Networking Modules operate.
Playbooks should still use ``connection: local``.
The following changes apply to:
* dellos6
* dellos9
* dellos10
* eos
* ios
* iosxr
* junos
* sros
* vyos
Deprecation of top-level connection arguments
---------------------------------------------
**OLD** In Ansible 2.2:
.. code-block:: yaml
- 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
Will result in:
.. code-block:: yaml
[WARNING]: argument username has been deprecated and will be removed in a future version
[WARNING]: argument host has been deprecated and will be removed in a future version
[WARNING]: argument password has been deprecated and will be removed in a future version
**NEW** In Ansible 2.3:
.. code-block:: yaml
- name: Gather facts
eos_facts:
gather_subset: all
provider:
username: myuser
password: "{{ networkpassword }}"
transport: cli
host: "{{ ansible_host }}"
delegate_to vs ProxyCommand
---------------------------
The new connection framework for Network Modules in Ansible 2.3 no longer supports the use of the
``delegate_to`` directive. In order to use a bastion or intermediate jump host
to connect to network devices, network modules now support the use of
``ProxyCommand``.
To use ``ProxyCommand`` configure the proxy settings in the Ansible inventory
file to specify the proxy host via ``ansible_ssh_common_args``.
For details on how to do this see the :ref:`network proxy guide <network_delegate_to_vs_ProxyCommand>`.
This link takes you to a different version of the Ansible documentation. Use the version selection on the left or your browser back button to return to this version of the documentation.

220
docs/docsite/rst/porting_guide_2.4.rst
View File

@ -1,224 +1,14 @@
:orphan:
.. _porting_2.4_guide:
*************************
Ansible 2.4 Porting Guide
*************************
This section discusses the behavioral changes between Ansible 2.3 and Ansible 2.4.
It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.
We suggest you read this page along with `Ansible Changelog <https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md#2.4>`_ to understand what updates you may need to make.
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
Python version
==============
Ansible will not support Python 2.4 or 2.5 on the target hosts anymore. Going forward, Python 2.6+ will be required on targets, as already is the case on the controller.
Inventory
=========
Inventory has been refactored to be implemented via plugins and now allows for multiple sources. This change is mostly transparent to users.
One exception is the ``inventory_dir``, which is now a host variable; previously it could only have one value so it was set globally.
This means you can no longer use it early in plays to determine ``hosts:`` or similar keywords.
This also changes the behaviour of ``add_hosts`` and the implicit localhost;
because they no longer automatically inherit the global value, they default to ``None``. See the module documentation for more information.
The ``inventory_file`` remains unchanged, as it was always host specific.
A bug was fixed with the inventory path/directory, which was defaulting to the current working directory. This caused ``group_vars`` and ``host_vars`` to be picked up from the current working directory instead of just adjacent to the playbook or inventory directory when a host list (comma separated host names) was provided as inventory.
Initial playbook relative group_vars and host_vars
--------------------------------------------------
In Ansible versions prior to 2.4, the inventory system would maintain the context of the initial playbook that was executed. This allowed successively included playbooks from other directories to inherit group_vars and host_vars placed relative to the top level playbook file.
Due to some behavioral inconsistencies, this functionality will not be included in the new
inventory system starting with Ansible version 2.4.
Similar functionality can still be achieved by using vars_files, include_vars, or group_vars and host_vars placed relative to the inventory file.
Deprecated
==========
Specifying Inventory sources
-----------------------------
Use of ``--inventory-file`` on the command line is now deprecated. Use ``--inventory`` or ``-i``.
The associated ini configuration key, ``hostfile``, and environment variable, :envvar:`ANSIBLE_HOSTS`,
are also deprecated. Replace them with the configuration key ``inventory`` and environment variable :envvar:`ANSIBLE_INVENTORY`.
Use of multiple tags
--------------------
Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last one overriding all the previous ones. This behavior is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behavior.
In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior via the config option.
In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behavior.
Other caveats
-------------
No major changes in this version.
Modules
=======
Major changes in popular modules are detailed here
* The :ref:`win_shell <win_shell>` and :ref:`win_command <win_command>` modules now properly preserve quoted arguments in the command-line. Tasks that attempted to work around the issue by adding extra quotes/escaping may need to be reworked to remove the superfluous escaping. See `Issue 23019 <https://github.com/ansible/ansible/issues/23019>`_ for additional detail.
Modules removed
---------------
The following modules no longer exist:
* None
Deprecation notices
-------------------
The following modules will be removed in Ansible 2.8. Please update update your playbooks accordingly.
* :ref:`azure <azure>`, use :ref:`azure_rm_virtualmachine <azure_rm_virtualmachine>`, which uses the new Resource Manager SDK.
* :ref:`win_msi <win_msi>`, use :ref:`win_package <win_package>` instead
Noteworthy module changes
-------------------------
* The :ref:`win_get_url <win_get_url>` module has the dictionary ``win_get_url`` in its results deprecated, its content is now also available directly in the resulting output, like other modules. This dictionary will be removed in Ansible 2.8.
* The :ref:`win_unzip <win_unzip>` module no longer includes the dictionary ``win_unzip`` in its results; the contents are now included directly in the resulting output, like other modules.
* The :ref:`win_package <win_package>` module return values ``exit_code`` and ``restart_required`` have been deprecated in favour of ``rc`` and ``reboot_required`` respectively. The deprecated return values will be removed in Ansible 2.6.
Plugins
=======
A new way to configure and document plugins has been introduced. This does not require changes to existing setups but developers should start adapting to the new infrastructure now. More details will be available in the developer documentation for each plugin type.
Vars plugin changes
-------------------
There have been many changes to the implementation of vars plugins, but both users and developers should not need to change anything to keep current setups working. Developers should consider changing their plugins take advantage of new features.
The most notable difference to users is that vars plugins now get invoked on demand instead of at inventory build time. This should make them more efficient for large inventories, especially when using a subset of the hosts.
Ansible Porting Guides are maintained in the ``devel`` branch only. Please go to `the devel Ansible 2.4 Porting guide <https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.4.html>`_ for up to date information.
.. note::
- This also creates a difference with group/host_vars when using them adjacent to playbooks. Before, the 'first' playbook loaded determined the variables; now the 'current' playbook does. We are looking to fix this soon, since 'all playbooks' in the path should be considered for variable loading.
- In 2.4.1 we added a toggle to allow you to control this behaviour, 'top' will be the pre 2.4, 'bottom' will use the current playbook hosting the task and 'all' will use them all from top to bottom.
Inventory plugins
-----------------
Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work via the ``script`` inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts.
Both users and developers should look into the new plugins because they are intended to alleviate the need for many of the hacks and workarounds found in the dynamic inventory scripts.
Callback plugins
----------------
Users:
* Callbacks are now using the new configuration system. Users should not need to change anything as the old system still works,
but you might see a deprecation notice if any callbacks used are not inheriting from the built in classes. Developers need to update them as stated below.
Developers:
* If your callback does not inherit from ``CallbackBase`` (directly or indirectly via another callback), it will still work, but issue a deprecation notice.
To avoid this and ensure it works in the future change it to inherit from ``callbackBase`` so it has the new options handling methods and properties.
You can also implement the new options handling methods and properties but that won't automatically inherit changes added in the future. You can look at ``CallbackBase`` itself and/or ``AnsiblePlugin`` for details.
* Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options
as the parent or the options won't be available. This is noted in the developer guide.
Template lookup plugin: Escaping Strings
----------------------------------------
Prior to Ansible 2.4, backslashes in strings passed to the template lookup plugin would be escaped
automatically. In 2.4, users are responsible for escaping backslashes themselves. This change
brings the template lookup plugin inline with the template module so that the same backslash
escaping rules apply to both.
If you have a template lookup like this::
- debug:
msg: '{{ lookup("template", "template.j2") }}'
**OLD** In Ansible 2.3 (and earlier) :file:`template.j2` would look like this:
.. code-block:: jinja
{{ "name surname" | regex_replace("^[^\s]+\s+(.*)", "\1") }}
**NEW** In Ansible 2.4 it should be changed to look like this:
.. code-block:: jinja
{{ "name surname" | regex_replace("^[^\\s]+\\s+(.*)", "\\1") }}
Tests
=====
Tests succeeded/failed
-----------------------
Prior to Ansible version 2.4, a task return code of ``rc`` would override a return code of ``failed``. In version 2.4, both ``rc`` and ``failed`` are used to calculate the state of the task. Because of this, test plugins ``succeeded``/``failed``` have also been changed. This means that overriding a task failure with ``failed_when: no`` will result in ``succeeded``/``failed`` returning ``True``/``False``. For example:
- command: /bin/false
register: result
failed_when: no
- debug:
msg: 'This is printed on 2.3'
when: result|failed
- debug:
msg: 'This is printed on 2.4'
when: result|succeeded
- debug:
msg: 'This is always printed'
when: result.rc != 0
As we can see from the example above, in Ansible 2.3 ``succeeded``/``failed`` only checked the value of ``rc``.
Networking
==========
There have been a number of changes to how Networking Modules operate.
Playbooks should still use ``connection: local``.
Persistent Connection
---------------------
The configuration variables ``connection_retries`` and ``connect_interval`` which were added in Ansible 2.3 are now deprecated. For Ansible 2.4 and later use ``connection_retry_timeout``.
To control timeouts use ``command_timeout`` rather than the previous top level ``timeout`` variable under ``[default]``
See :ref:`Ansible Network debug guide <network_debug_troubleshooting>` for more information.
Configuration
=============
The configuration system has had some major changes. Users should be unaffected except for the following:
* All relative paths defined are relative to the `ansible.cfg` file itself. Previously they varied by setting. The new behavior should be more predictable.
* A new macro ``{{CWD}}`` is available for paths, which will make paths relative to the 'current working directory',
this is unsafe but some users really want to rely on this behaviour.
Developers that were working directly with the previous API should revisit their usage as some methods (for example, ``get_config``) were kept for backwards compatibility but will warn users that the function has been deprecated.
The new configuration has been designed to minimize the need for code changes in core for new plugins. The plugins just need to document their settings and the configuration system will use the documentation to provide what they need. This is still a work in progress; currently only 'callback' and 'connection' plugins support this. More details will be added to the specific plugin developer guides.
This link takes you to a different version of the Ansible documentation. Use the version selection on the left or your browser back button to return to this version of the documentation.

7
docs/docsite/rst/porting_guides.rst
View File

@ -4,9 +4,8 @@
Ansible Porting Guides
**********************
This section lists porting guides that can help you playbooks, plugins and other parts of your Ansible infrastructure from one version of Ansible to the next. Please note that this is not a complete list. If you believe any extra information would be useful in these pages, you can edit by clicking `Edit on GitHub` on the top right, or raising an issue.
Ansible Porting Guides are maintained in the ``devel`` branch only. Please go to `the devel porting guides <https://docs.ansible.com/ansible/devel/porting_guides/porting_guides.html>`_ for up to date information.
.. note::
* :ref:`Ansible 1.x to 2.0 porting guide <porting_2.0_guide>`
* :ref:`Ansible 2.2 to 2.3 porting guide <porting_2.3_guide>`
* :ref:`Ansible 2.3 to 2.4 porting guide <porting_2.4_guide>`
This link takes you to a different version of the Ansible documentation. Use the version selection on the left or your browser back button to return to this version of the documentation.