diff options
author | John R Barker <john@johnrbarker.com> | 2017-09-16 12:10:12 +0100 |
---|---|---|
committer | Toshio Kuratomi <a.badger@gmail.com> | 2017-09-16 10:42:45 -0700 |
commit | 6e77a3ac3a3fd3c9458e3172ee769b7350a84175 (patch) | |
tree | 4cd4b6c38c4cd8d113904d298550947505ae7852 | |
parent | f5e237d03836502fb3072d38b9b05613538ec04c (diff) | |
download | ansible-6e77a3ac3a3fd3c9458e3172ee769b7350a84175.tar.gz |
Porting Guides 2.4 (#24539)
* Porting Guides for Ansible Versions
Improve the user facing documentation.
Tell people what changes they need to make
* More porting guides
* Link porting guides from TOC
* Link porting guides from CHANGELOG.md
* typo in link
* Review feedback
* Better CHANGELOG links
* Better links
* code blocks
* Minor changes
* Correct links, comment out network section in 2.4
* Typos
* Revert non 2.4 changes
* Add placeholders for other items
* multiple inventory
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* Update porting_guide_2.4.rst
* add win_command/win_shell escaping notes
* Added some windows porting info
* Edit for grammar
* Correct links, delete Net Platform Agnostic
* 2.5 link
* Network changes in 2.4
* facts_namespacing was pushed back to 2.5
Due to lack of time we pushed this back to 2.5 so that the facts in the namespace could be shortened.
* Python version
* Remove FIXMEs - move to seperate PR
(cherry picked from commit 785e604c57573ff587ca306182969c133af56152)
-rw-r--r-- | docs/docsite/rst/porting_guide_2.4.rst | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/docs/docsite/rst/porting_guide_2.4.rst b/docs/docsite/rst/porting_guide_2.4.rst new file mode 100644 index 0000000000..f27eab6d59 --- /dev/null +++ b/docs/docsite/rst/porting_guide_2.4.rst @@ -0,0 +1,115 @@ +.. _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 nor 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. + +Playbook +======== + +Multiple inventory +------------------ + +**NEW** In Ansible 2.4: + + +.. code-block:: shell + + ansible-playbook -i /path/to/inventory1, /some/other/path/inventory2 + + +Deprecated +========== + +Inventory argument +------------------------- + +Use of ``--inventory-file`` is now deprecated. Use ``--inventory`` or ``-i``. + + +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. + + +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 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. + |