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

CHANGELOG.md

@@ -282,9 +282,12 @@ Ansible Changes By Release
   * win_security_policy
   * win_wakeonlan
 
+<a id="2.3"></a>
 
 ## 2.3 "Ramble On" - 2017-04-12
 
+Moving to Ansible 2.3 guide http://docs.ansible.com/ansible/porting_guide_2.3.html
+
 ### Major Changes
 * Documented and renamed the previously released 'single var vaulting' feature, allowing user to use vault encryption for single variables in a normal YAML vars file.
 * Allow module_utils for custom modules to be placed in site-specific directories and shipped in roles
@@ -598,6 +601,7 @@ Ansible Changes By Release
   * zfs_facts
   * zpool_facts
 
+<a id="2.2.1"></a>
 
 ## 2.2.1 "The Battle of Evermore" - 2017-01-16
 
@@ -624,10 +628,11 @@ Ansible Changes By Release
 * Improvements and fixes to OpenBSD fact gathering.
 * Updated `make deb` to use pbuilder. Use `make local_deb` for the previous non-pbuilder build.
 * Fixed Windows async to avoid blocking due to handle inheritance.
-* Fixed bugs in the mount module on older Linux kernels and *BSDs
+* Fixed bugs in the mount module on older Linux kernels and BSDs
 * Various minor fixes for Python 3
 * Inserted some checks for jinja2-2.9, which can cause some issues with Ansible currently.
 
+<a id="2.2"></a>
 
 ## 2.2 "The Battle of Evermore" - 2016-11-01
 
@@ -942,12 +947,16 @@ Notice given that the following will be removed in Ansible 2.4:
   * nxos_template
   * ops_template
 
+<a id="2.1.4"></a>
+
 ## 2.1.4 "The Song Remains the Same" - 2017-01-16
 
 * Security fix for CVE-2016-9587 - An attacker with control over a client system being managed by Ansible and the ability to send facts back to the Ansible server could use this flaw to execute arbitrary code on the Ansible server as the user and group Ansible is running as.
 * Fixed a bug with conditionals in loops, where undefined variables and other errors will defer raising the error until the conditional has been evaluated.
 * Added a version check for jinja2-2.9, which does not fully work with Ansible currently.
 
+<a id="2.1.3"></a>
+
 ## 2.1.3 "The Song Remains the Same" - 2016-11-04
 
 * Security fix for CVE-2016-8628 - Command injection by compromised server via fact variables. In some situations, facts returned by modules could overwrite connection-based facts or some other special variables, leading to injected commands running on the Ansible controller as the user running Ansible (or via escalated permissions).
@@ -960,11 +969,13 @@ Notice given that the following will be removed in Ansible 2.4:
   login_password as no_log so the password is obscured when logging.
 * Fixed several bugs related to locating files relative to role/playbook directories.
 * Fixed a bug in the way hosts were tested for failed states, resulting in incorrectly skipped block sessions.
-* Fixed a bug in the way our custom JSON encoder is used for the to_json* filters.
+* Fixed a bug in the way our custom JSON encoder is used for the `to_json*` filters.
 * Fixed some bugs related to the use of non-ascii characters in become passwords.
 * Fixed a bug with Azure modules which may be using the latest rc6 library.
 * Backported some docker_common fixes.
 
+<a id="2.1.2"></a>
+
 ## 2.1.2 "The Song Remains the Same" - 2016-09-29
 
 ### Minor Changes
@@ -1027,6 +1038,8 @@ Module fixes:
   Use `_fixup_perms2` if support for previous releases is not required.
   Otherwise use `_fixup_perms` with `recursive=False`.
 
+<a id="2.1"></a>
+
 ## 2.1 "The Song Remains the Same"
 
 ### Major Changes:
@@ -1214,6 +1227,8 @@ Module fixes:
   completely in 2.3, after which time it will be an error.
 * play_hosts magic variable, use ansible_play_batch or ansible_play_hosts instead.
 
+<a id="2.0.2"></a>
+
 ## 2.0.2 "Over the Hills and Far Away"
 
 * Backport of the 2.1 feature to ensure per-item callbacks are sent as they occur,
@@ -1255,10 +1270,12 @@ Module fixes:
   permissions on the temporary file too leniently on a temporary file that was
   executed as a script.  Addresses CVE-2016-3096
 * Fix a bug in the uri module where setting headers via module params that
-  start with HEADER_ were causing a traceback.
+  start with `HEADER_` were causing a traceback.
 * Fix bug in the free strategy that was causing it to synchronize its workers
   after every task (making it a lot more like linear than it should have been).
 
+<a id="2.0.1"></a>
+
 ## 2.0.1 "Over the Hills and Far Away"
 
 * Fixes a major compatibility break in the synchronize module shipped with
@@ -1266,7 +1283,7 @@ Module fixes:
   running rsync.  In 1.9.x and previous, sudo was run on the host that rsync
   connected to.  2.0.1 restores the 1.9.x behaviour.
 * Additionally, several other problems with where synchronize chose to run when
-  combined with delegate_to were fixed.  In particular, if a playbook targeted
+  combined with delegate_to were fixed.  In particular, if a playbook targetted
   localhost and then delegated_to a remote host the prior behavior (in 1.9.x
   and 2.0.0.x) was to copy files between the src and destination directories on
   the delegated host.  This has now been fixed to copy between localhost and
@@ -1300,6 +1317,8 @@ Module fixes:
   this might cause an error if settings environment on play depending on 'ansible_env'
   which was previouslly ignored
 
+<a id="2.0"></a>
+
 ## 2.0 "Over the Hills and Far Away" - Jan 12, 2016
 
 ### Major Changes:

docs/docsite/rst/index.rst

@@ -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

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,14 +42,15 @@ 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:
+    - name: Attempt and gracefull roll back demo
-       - debug: msg='i execute normally'
+      block:
+        - debug: msg='I execute normally'
         - command: /bin/false
-       - debug: msg='i never execute, cause ERROR!'
+        - debug: msg='I never execute, due to the above task failing'
       rescue:
         - debug: msg='I caught an error'
         - command: /bin/false
@@ -65,12 +67,13 @@ 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:
+    - name: Attempt and gracefull roll back demo
-       - debug: msg='i execute normally'
+      block:
+        - debug: msg='I execute normally'
           notify: run me even after an error
         - command: /bin/false
       rescue:
@@ -93,4 +96,3 @@ Another example is how to run handlers after an error occurred :
 
 
 
-

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
---------
+========
 
-* backslash escapes When specifying parameters in jinja2 expressions in YAML
+This section discusses any changes you may need to make to your playbooks.
-  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
+.. code-block:: yaml
-  playbooks must be modified::
 
     # 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::
 
@@ -199,32 +211,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
@@ -260,15 +273,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.
 
@@ -288,8 +301,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
 
@@ -355,28 +369,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`
 

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.
+

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>`