2.3portingguide (#27671)

* Docs porting guides 2.0 &  2.3 (#27632)

* Create new "Porting Guide" section

Create new landing page
Add porting_guide_2.3

* correct CHANGELOG

* Document blocks

* Document named blocks

* OpenBSD & async action plugins

* OpenBSD & async action plugins

* versioadded for name

* review comments

(cherry picked from commit df58d943d37b69bb49dcddb42c4a1102523ecfe9)

* Correct merge

5 files changed, 336 insertions, 62 deletions

diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst
index dc503191c6..02e12c97b6 100644
--- a/docs/docsite/rst/index.rst
+++ b/docs/docsite/rst/index.rst
@@ -7,7 +7,7 @@ About Ansible
 Welcome to the Ansible documentation!
 
 Ansible is an IT automation tool.  It can configure systems, deploy software, and orchestrate more advanced IT tasks
-such as continuous deployments or zero downtime rolling updates.  
+such as continuous deployments or zero downtime rolling updates.
 
 Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
 
@@ -16,7 +16,7 @@ We believe simplicity is relevant to all sizes of environments, so we design for
 Ansible manages machines in an agent-less manner. There is never a question of how to
 upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled.  Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems.
 
-This documentation covers the current released version of Ansible (|version|) and also some development version features (|versiondev|).  For recent features, we note in each section the version of Ansible where the feature was added.  
+This documentation covers the current released version of Ansible (|version|) and also some development version features (|versiondev|).  For recent features, we note in each section the version of Ansible where the feature was added.
 
 Ansible, Inc. releases a new major release of Ansible approximately every two months.  The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
 
@@ -40,6 +40,6 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
    faq
    glossary
    YAMLSyntax
-   porting_guide_2.0
+   porting_guides
    python_3_support
    release_and_maintenance
diff --git a/docs/docsite/rst/playbooks_blocks.rst b/docs/docsite/rst/playbooks_blocks.rst
index f7395ff7c9..d659e02ef9 100644
--- a/docs/docsite/rst/playbooks_blocks.rst
+++ b/docs/docsite/rst/playbooks_blocks.rst
@@ -9,20 +9,18 @@ by the tasks enclosed by a block. i.e. a `when` will be applied to the tasks, no
 
 
 .. code-block:: YAML
- :emphasize-lines: 2
+ :emphasize-lines: 3
  :caption: Block example
 
     tasks:
-      - block:
+      - name: Install Apache
+        block:
           - yum: name={{ item }} state=installed
             with_items:
               - httpd
               - memcached
-
           - template: src=templates/src.j2 dest=/etc/foo.conf
-
           - service: name=bar state=started enabled=True
-
         when: ansible_distribution == 'CentOS'
         become: true
         become_user: root
@@ -32,6 +30,9 @@ In the example above, each of the 3 tasks will be executed after appending the `
 and evaluating it in the task's context. Also they inherit the privilege escalation directives enabling "become to root"
 for all the enclosed tasks.
 
+. versionadded:: 2.3
+
+The `name:` keyword for `blocks:` was added in Ansible 2.3.
 
 .. _block_error_handling:
 
@@ -41,20 +42,21 @@ Error Handling
 Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
 
 .. code-block:: YAML
- :emphasize-lines: 2,6,10
+ :emphasize-lines: 3,7,11
  :caption: Block error handling example
 
-  tasks:
-   - 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"
+   tasks:
+    - name: Attempt and gracefull roll back demo
+      block:
+        - debug: msg='I execute normally'
+        - command: /bin/false
+        - debug: msg='I never execute, due to the above task failing'
+      rescue:
+        - debug: msg='I caught an error'
+        - command: /bin/false
+        - debug: msg='I also never execute :-('
+      always:
+        - debug: msg="this always executes"
 
 
 The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
@@ -65,20 +67,21 @@ error did or did not occur in the ``block`` and ``rescue`` sections.
 Another example is how to run handlers after an error occurred :
 
 .. code-block:: YAML
- :emphasize-lines: 4,8
+ :emphasize-lines: 5,9
  :caption: Block run handlers in error handling
 
   tasks:
-   - block:
-       - debug: msg='i execute normally'
-         notify: run me even after an error
-       - command: /bin/false
-     rescue:
-       - name: make sure all handlers run
-         meta: flush_handlers
-  handlers:
-    - name: run me even after an error
-      debug: msg='this handler runs even on error'
+    - name: Attempt and gracefull roll back demo
+      block:
+        - debug: msg='I execute normally'
+          notify: run me even after an error
+        - command: /bin/false
+      rescue:
+        - name: make sure all handlers run
+          meta: flush_handlers
+   handlers:
+     - name: run me even after an error
+       debug: msg='this handler runs even on error'
 
 .. seealso::
 
@@ -93,4 +96,3 @@ Another example is how to run handlers after an error occurred :
 
 
 
-
diff --git a/docs/docsite/rst/porting_guide_2.0.rst b/docs/docsite/rst/porting_guide_2.0.rst
index 8cc468050e..fc38cadb4b 100644
--- a/docs/docsite/rst/porting_guide_2.0.rst
+++ b/docs/docsite/rst/porting_guide_2.0.rst
@@ -1,14 +1,26 @@
-Porting Guide
-=============
+.. _porting_2.0_guide:
 
+*************************
+Ansible 2.0 Porting Guide
+*************************
+
+This section discusses the behavioral changes between Ansible 1.x and Ansible 2.0.
+
+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.
 
-* backslash escapes When specifying parameters in jinja2 expressions in YAML
-  dicts, backslashes sometimes needed to be escaped twice. This has been fixed
-  in 2.0.x so that escaping once works. The following example shows how
-  playbooks must be modified::
+.. code-block:: yaml
 
     # Syntax in 1.9.x
     - debug:
@@ -88,16 +100,16 @@ uses key=value escaping which has not changed.  The other option is to check for
 * 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. Previouslly this was ignored but now might issue an 'Undefined' error.
+  `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.
+* 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.
+* 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
@@ -151,9 +163,9 @@ Should now be::
 
 
 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 previouslly ignored.
+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::
 
@@ -201,32 +213,33 @@ Here are some corner cases encountered when updating, these are mostly caused by
 
     with_items: "{{var1 + var2}}"
 
-  The bare feature itself is deprecated as an undefined variable is indistiguishable from a string which makes it difficult to display a proper error.
+  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
@@ -262,15 +275,15 @@ populates the callback with them.  Here's a short snippet that shows you how:
 
 
 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. It may mean playing tricks on Ansible.
+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.
 
@@ -290,8 +303,9 @@ You may find the following tips useful:
 
 
 Lookup plugins
-~~~~~~~~~~~~~~
-As a simple example we are going to make a hybrid ``fileglob`` lookup plugin.  The ``fileglob`` lookup plugin is pretty simple to understand
+--------------
+
+As a simple example we are going to make a hybrid ``fileglob`` lookup plugin.
 
 .. code-block:: python
 
@@ -357,28 +371,28 @@ As a simple example we are going to make a hybrid ``fileglob`` lookup plugin.  T
 
 
 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`
+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`
 
diff --git a/docs/docsite/rst/porting_guide_2.3.rst b/docs/docsite/rst/porting_guide_2.3.rst
new file mode 100644
index 0000000000..8b096e0ca6
--- /dev/null
+++ b/docs/docsite/rst/porting_guide_2.3.rst
@@ -0,0 +1,246 @@
+.. _porting_2.3_guide:
+
+*************************
+Ansible 2.3 Porting Guide
+*************************
+
+This section discusses the behavioral changes between Ansible 2.2 and Ansible 2.3.
+
+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.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.
+
+.. code-block:: ini
+
+    [nxos]
+    nxos01
+    nxos02
+
+    [nxos:vars]
+    ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
+
+
+With the configuration above, simply build and run the playbook as normal with
+no additional changes necessary.  The network module will now connect to the
+network device by first connecting to the host specified in
+``ansible_ssh_common_args`` which is ``bastion01`` in the above example.
+
+
+.. notes: Using ``ProxyCommand`` with passwords via variables
+
+   It is a feature that SSH doesn't support providing passwords via environment variables.
+   This is done to prevent secrets from leaking out, for example in ``ps`` output.
+
+   We recommend using SSH Keys, and if needed and ssh-agent, rather than passwords, where ever possible.
+
diff --git a/docs/docsite/rst/porting_guides.rst b/docs/docsite/rst/porting_guides.rst
new file mode 100644
index 0000000000..4c1dbec5fd
--- /dev/null
+++ b/docs/docsite/rst/porting_guides.rst
@@ -0,0 +1,12 @@
+.. _porting_guides:
+
+**********************
+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.
+
+
+* :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>`