@@ -37,6 +37,8 @@ docs/docsite/rst/cli/ansible.rst

 docs/docsite/rst/dev_guide/collections_galaxy_meta.rst

 docs/docsite/rst/dev_guide/testing/sanity/index.rst.new

 docs/docsite/rst/modules/*.rst

+docs/docsite/rst/collections/*.rst

+docs/docsite/rst/collections/*/*.rst

 docs/docsite/rst/playbooks_directives.rst

 docs/docsite/rst/plugins_by_category.rst

 docs/docsite/rst/plugins/*/*.rst

@@ -275,7 +275,7 @@ linkcheckdocs:

 .PHONY: generate_rst

 generate_rst: lib/ansible/cli/*.py

 	mkdir -p ./docs/man/man1/ ; \

-	PYTHONPATH=./lib $(GENERATE_CLI) --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py

+	$(GENERATE_CLI) --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py

 docs: generate_rst

@@ -1,6 +1,6 @@

 OS := $(shell uname -s)

 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"):

-PLUGIN_FORMATTER=../../hacking/build-ansible.py document-plugins

+PLUGIN_FORMATTER=../../hacking/build-ansible.py docs-build

 TESTING_FORMATTER=../bin/testing_formatter.sh

 KEYWORD_DUMPER=../../hacking/build-ansible.py document-keywords

 CONFIG_DUMPER=../../hacking/build-ansible.py document-config

@@ -12,23 +12,35 @@ else

 CPUS ?= $(shell nproc)

 endif

-# Sets the build output directory if it's not already specified

+# Sets the build output directory for the main docsite if it's not already specified

 ifndef BUILDDIR

 	BUILDDIR = _build

 endif

-MODULE_ARGS=

+# Backwards compat for separate VARS

+PLUGIN_ARGS=

 ifdef MODULES

-	MODULE_ARGS = -l $(MODULES)

+ifndef PLUGINS

+	PLUGIN_ARGS = -l $(MODULES)

+else

+	PLUGIN_ARGS = -l $(MODULES),$(PLUGINS)

 endif

-

-PLUGIN_ARGS=

+else

 ifdef PLUGINS

 	PLUGIN_ARGS = -l $(PLUGINS)

 endif

+endif

+

 DOC_PLUGINS ?= become cache callback cliconf connection httpapi inventory lookup netconf shell strategy vars

+PYTHON=python

+# fetch version from project release.py as single source-of-truth

+VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --raw || echo error)

+ifeq ($(findstring error,$(VERSION)), error)

+$(error "version_helper failed")

+endif

+

 assertrst:

 ifndef rst

 	$(error specify document or pattern with rst=somefile.rst)

@@ -38,7 +50,8 @@ all: docs

 docs: htmldocs

-generate_rst: collections_meta config cli keywords modules plugins testing

+generate_rst: collections_meta config cli keywords plugins testing

+base_generate_rst: collections_meta config cli keywords base_plugins testing

 htmldocs: generate_rst

 	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html

@@ -46,9 +59,12 @@ htmldocs: generate_rst

 singlehtmldocs: generate_rst

 	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml

+base_singlehtmldocs: base_generate_rst

+	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml

+

 linkcheckdocs: generate_rst

 		CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck

-		

+

 webdocs: docs

 #TODO: leaving htmlout removal for those having older versions, should eventually be removed also

@@ -58,7 +74,7 @@ clean:

 	-rm -rf $(BUILDDIR)/html

 	-rm -rf htmlout

 	-rm -rf module_docs

-	-rm -rf _build

+	-rm -rf $(BUILDDIR)

 	-rm -f .buildinfo

 	-rm -f objects.inv

 	-rm -rf *.doctrees

@@ -70,43 +86,44 @@ clean:

 	find . -type f \( -name "*~" -or -name "#*" \) -delete

 	find . -type f \( -name "*.swp" \) -delete

 	@echo "Cleaning up generated rst"

-	rm -f rst/modules/*_by_category.rst

-	rm -f rst/modules/list_of_*.rst

-	rm -f rst/modules/*_maintained.rst

-	rm -f rst/modules/*_module.rst

-	rm -f rst/modules/*_plugin.rst

 	rm -f rst/playbooks_directives.rst

-	rm -f rst/plugins/*/*.rst

 	rm -f rst/reference_appendices/config.rst

 	rm -f rst/reference_appendices/playbooks_keywords.rst

 	rm -f rst/dev_guide/collections_galaxy_meta.rst

 	rm -f rst/cli/*.rst

+	rm -rf rst/collections/*

+	@echo "Cleaning up legacy generated rst locations"

+	rm -rf rst/modules

+	rm -f rst/plugins/*/*.rst

 .PHONY: docs clean

 collections_meta: ../templates/collections_galaxy_meta.rst.j2

-	PYTHONPATH=../../lib $(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml

+	$(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml

 # TODO: make generate_man output dir cli option

 cli:

 	mkdir -p rst/cli

-	PYTHONPATH=../../lib $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py

+	$(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py

 keywords: ../templates/playbooks_keywords.rst.j2

-	PYTHONPATH=../../lib $(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ./keyword_desc.yml

+	$(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ./keyword_desc.yml

 config: ../templates/config.rst.j2

-	PYTHONPATH=../../lib $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml

-

-modules: ../templates/plugin.rst.j2

-	PYTHONPATH=../../lib $(PLUGIN_FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/modules/ $(MODULE_ARGS)

-

-plugins: ../templates/plugin.rst.j2

-	@echo "looping over doc plugins"

-	for plugin in $(DOC_PLUGINS); \

-	do \

-		PYTHONPATH=../../lib $(PLUGIN_FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst $(PLUGIN_ARGS); \

-	done

+	$(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml

+

+# For now, if we're building on devel, just build base docs.  In the future we'll want to build docs that

+# are the latest versions on galaxy (using a different antsibull-docs subcommand)

+plugins:

+	if expr match "$(VERSION)" '.*[.]dev[0-9]\+$$' &> /dev/null; then \

+		$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\

+	else \

+		$(PLUGIN_FORMATTER) full -o rst $(PLUGIN_ARGS);\

+	fi

+

+# This only builds the plugin docs included with ansible-base

+base_plugins:

+	$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\

 testing:

 	$(TESTING_FORMATTER)

@@ -10,26 +10,27 @@

       element.appendChild(para);

       document.write('</div>');

     }

-

-    // Create a banner if we're not the latest version

-    current_url = window.location.href;

-    if ((current_url.search("latest") > -1) || (current_url.search("/{{ latest_version }}/") > -1)) {

-     // no banner for latest release

-    } else if (current_url.search("devel") > -1) {

-      document.write('<div id="banner_id" class="admonition caution">');

-      para = document.createElement('p');

-      banner_text=document.createTextNode("You are reading the *devel* version of the Ansible documentation - most module documentation is currently missing as the modules have moved to collections. Until docs catches up to this change, use the version selection to the left if you want module documentation or the latest stable release version. The *devel* version is not guaranteed stable.");

-      para.appendChild(banner_text);

-      element = document.getElementById('banner_id');

-      element.appendChild(para);

-      document.write('</div>');

-    } else {

-      document.write('<div id="banner_id" class="admonition caution">');

-      para = document.createElement('p');

-      banner_text=document.createTextNode("You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.");

-      para.appendChild(banner_text);

-      element = document.getElementById('banner_id');

-      element.appendChild(para);

-      document.write('</div>');

-    }

+    {% if (not READTHEDOCS) and (available_versions is defined) %}

+      // Create a banner if we're not the latest version

+      current_url = window.location.href;

+      if ((current_url.search("latest") > -1) || (current_url.search("/{{ latest_version }}/") > -1)) {

+       // no banner for latest release

+      } else if (current_url.search("devel") > -1) {

+        document.write('<div id="banner_id" class="admonition caution">');

+        para = document.createElement('p');

+        banner_text=document.createTextNode("You are reading the *devel* version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest stable released version.");

+        para.appendChild(banner_text);

+        element = document.getElementById('banner_id');

+        element.appendChild(para);

+        document.write('</div>');

+      } else {

+        document.write('<div id="banner_id" class="admonition caution">');

+        para = document.createElement('p');

+        banner_text=document.createTextNode("You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.");

+        para.appendChild(banner_text);

+        element = document.getElementById('banner_id');

+        element.appendChild(para);

+        document.write('</div>');

+      }

+    {% endif %}

   </script>

@@ -1,7 +1,7 @@

 <!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->

 {# Creates dropdown version selection in the top-left navigation. #}

 <div class="version">

-  {% if not READTHEDOCS %}

+  {% if (not READTHEDOCS) and (available_versions is defined) %}

     <div class="version-dropdown">

       <select class="version-list" id="version-list" onchange="javascript:location.href = this.value;">

         <script> x = document.getElementById("version-list"); </script>

new file mode 100644

@@ -0,0 +1,17 @@

+# We also need an example of modules hosted in Automation Hub

+# We'll likely move to data hosted in botmeta instead of a standalone file but

+# we'll need all of these same details.

+module:

+    purefa_user:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

+    purefa_vg:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

+    gcp_compute_firewall_info:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'google.cloud'

+module_utils:

+    purefa:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

@@ -6,3 +6,4 @@ sphinx==2.1.2

 sphinx-notfound-page

 Pygments >= 2.4.0

 straight.plugin # Needed for hacking/build-ansible.py which is the backend build script

+antsibull >= 0.15.0

@@ -277,6 +277,10 @@ autoclass_content = 'both'

 intersphinx_mapping = {'python': ('https://docs.python.org/2/', (None, '../python2.inv')),

                        'python3': ('https://docs.python.org/3/', (None, '../python3.inv')),

                        'jinja2': ('http://jinja.palletsprojects.com/', (None, '../jinja2.inv')),

+                       'collections': ('https://docs.ansible.com/collections/',

+                                       (None, '../collections.inv',

+                                        'http://docs.testing.ansible.com/collections/objects.inv',

+                                        '../_collections_build/html/objects.inv')),

                        'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, '../ansible_2_9.inv')),

                        'ansible_2_8': ('https://docs.ansible.com/ansible/2.8/', (None, '../ansible_2_8.inv')),

                        'ansible_2_7': ('https://docs.ansible.com/ansible/2.7/', (None, '../ansible_2_7.inv')),

@@ -74,7 +74,7 @@ Ansible releases a new major release of Ansible approximately three to four time

    :maxdepth: 1

    :caption: Reference & Appendices

-   ../modules/modules_by_category

+   collections/index

    reference_appendices/playbooks_keywords

    reference_appendices/common_return_values

    reference_appendices/config

@@ -10,7 +10,7 @@ Ansible Network modules extend the benefits of simple, powerful, agentless autom

 If you're new to Ansible, or new to using Ansible for network management, start with :ref:`network_getting_started`. If you are already familiar with network automation with Ansible, see :ref:`network_advanced`.

-For documentation on using a particular network module, consult the :ref:`list of all network modules<network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :ref:`network modules maintained by the Ansible Network Team<network_supported>`.

+For documentation on using a particular network module, consult the :ref:`list of all network modules<network_modules>`. Network modules for various hardware are supported by different teams including the hardware vendors themselves, volunteers from the Ansible community, and the Ansible Network Team.

 .. toctree::

    :maxdepth: 3

@@ -483,4 +483,4 @@ If you receive an connection error please double check the inventory and playboo

   * :ref:`network_guide`

   * :ref:`intro_inventory`

-  * :ref:`Vault best practices <best_practices_for_variables_and_vaults>`

+  * :ref:`Keeping vaulted variables visible <tip_for_variables_and_vaults>`

@@ -47,11 +47,6 @@ Plugin List

 You can use ``ansible-doc -t become -l`` to see the list of available plugins.

 Use ``ansible-doc -t become <plugin name>`` to see specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    become/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -118,11 +118,6 @@ Plugin List

 You can use ``ansible-doc -t cache -l`` to see the list of available plugins.

 Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    cache/*

-

 .. seealso::

    :ref:`action_plugins`

@@ -79,12 +79,6 @@ Plugin list

 You can use ``ansible-doc -t callback -l`` to see the list of available plugins.

 Use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    callback/*

-

-

 .. seealso::

    :ref:`action_plugins`

@@ -58,12 +58,6 @@ You can use ``ansible-doc -t connection -l`` to see the list of available plugin

 Use ``ansible-doc -t connection <plugin name>`` to see detailed documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    connection/*

-

-

 .. seealso::

    :ref:`Working with Playbooks<working_with_playbooks>`

@@ -162,11 +162,6 @@ Plugin List

 You can use ``ansible-doc -t inventory -l`` to see the list of available plugins.

 Use ``ansible-doc -t inventory <plugin name>`` to see plugin-specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    inventory/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -138,11 +138,6 @@ Plugin list

 You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup <plugin name>`` to see specific documents and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    lookup/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -33,11 +33,6 @@ In this case, you will also want to update the :ref:`ansible_shell_executable <a

 You can further control the settings for each plugin via other configuration options

 detailed in the plugin themselves (linked below).

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    shell/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -59,11 +59,6 @@ You can use ``ansible-doc -t strategy -l`` to see the list of available plugins.

 Use ``ansible-doc -t strategy <plugin name>`` to see plugin-specific specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    strategy/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -57,11 +57,6 @@ You can use ``ansible-doc -t vars -l`` to see the list of available plugins.

 Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    vars/*

-

 .. seealso::

    :ref:`action_plugins`

@@ -698,7 +698,7 @@ Please see the section below for a link to IRC and the Google Group, where you c

    :ref:`working_with_playbooks`

        An introduction to playbooks

    :ref:`playbooks_best_practices`

-       Best practices advice

+       Tips and tricks for playbooks

    `User Mailing List <https://groups.google.com/group/ansible-project>`_

        Have a question?  Stop by the google group!

    `irc.freenode.net <http://irc.freenode.net>`_

@@ -494,7 +494,7 @@ when a term comes up on the mailing list.

    :ref:`working_with_playbooks`

        An introduction to playbooks

    :ref:`playbooks_best_practices`

-       Best practices advice

+       Tips and tricks for playbooks

    `User Mailing List <https://groups.google.com/group/ansible-devel>`_

        Have a question?  Stop by the google group!

    `irc.freenode.net <http://irc.freenode.net>`_

@@ -234,7 +234,7 @@ For more information, see `this systemd issue

 Become and network automation

 =============================

-As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all :ref:`Ansible-maintained platforms<network_supported>` that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary.

+As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all Ansible-maintained network platforms that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary.

 You must set the connection type to either ``connection: network_cli`` or ``connection: httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details.

@@ -5,7 +5,8 @@

 Using collections

 *****************

-Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins.

+Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. As modules move from the core Ansible repository into collections, the module documentation will move to the `collections documentation page <https://docs.ansible.com/collections/>`_

+

 You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.

 * For details on how to *develop* collections see :ref:`developing_collections`.

@@ -543,7 +543,7 @@ ansible_port

 ansible_user

     The user name to use when connecting to the host

 ansible_password

-    The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)

+    The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)

 Specific to the SSH connection:

@@ -575,7 +575,7 @@ ansible_become_method

 ansible_become_user

     Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation

 ansible_become_password

-    Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)

+    Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)

 ansible_become_exe

     Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected

 ansible_become_flags

@@ -7,9 +7,8 @@ Working With Modules

    :maxdepth: 1

    modules_intro

-   ../reference_appendices/common_return_values

    modules_support

-   ../modules/modules_by_category

+   ../reference_appendices/common_return_values

 Ansible ships with a number of modules (called the 'module library')

@@ -4,68 +4,66 @@

 Module Maintenance & Support

 ****************************

+If you are using a module and you discover a bug, you may want to know where to report that bug, who is responsible for fixing it, and how you can track changes to the module. If you are a Red Hat subscriber, you may want to know whether you can get support for the issue you are facing.

+

+Starting in Ansible 2.10, most modules live in collections. The distribution method for each collection reflects the maintenance and support for the modules in that collection.

+

 .. contents::

-  :depth: 2

   :local:

 Maintenance

 ===========

-To clarify who maintains each included module, adding features and fixing bugs, each included module now has associated metadata that provides information about maintenance.

-

-Core

-

-:ref:`Core Maintained<core_supported>` modules are maintained by the Ansible Engineering Team.

-These modules are integral to the basic foundations of the Ansible distribution.

+.. table::

+   :class: documentation-table

-Network

+   ============================= ========================================== ==========================

+   Collection                    Code location                              Maintained by

+   ============================= ========================================== ==========================

+   ansible.builtin               `ansible/ansible repo`_ on GitHub          core team

-:ref:`Network Maintained<network_supported>` modules are are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.

+   distributed on Galaxy         various; follow ``repo`` link              community or partners

+   distributed on Automation Hub various; follow ``repo`` link              content team or partners

+   ============================= ========================================== ==========================

-Certified

+.. _ansible/ansible repo: https://github.com/ansible/ansible/tree/devel/lib/ansible/modules

-`Certified <https://access.redhat.com/articles/3642632>`_ modules are maintained by Ansible Partners.

+Issue Reporting

+===============

-Community

+If you find a bug that affects a plugin in the main Ansible repo:

-:ref:`Community Maintained<community_supported>` modules are submitted and maintained by the Ansible community.  These modules are not maintained by Ansible, and are included as a convenience.

+  #. Confirm that you are running the latest stable version of Ansible or the devel branch.

+  #. Look at the `issue tracker in the Ansible repo <https://github.com/ansible/ansible/issues>`_ to see if an issue has already been filed.

+  #. Create an issue if one does not already exist. Include as much detail as you can about the behavior you discovered.

-Issue Reporting

-===============

+If you find a bug that affects a plugin in a Galaxy collection:

-If you believe you have found a bug in a module and are already running the latest stable or development version of Ansible, first look at the `issue tracker in the Ansible repo <https://github.com/ansible/ansible/issues>`_ to see if an issue has already been filed. If not, please file one.

+  #. Find the collection on Galaxy.

+  #. Find the issue tracker for the collection.

+  #. Look there to see if an issue has already been filed.

+  #. Create an issue if one does not already exist. Include as much detail as you can about the behavior you discovered.

-Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.

+Some partner collections may be hosted in private repositories.

-For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible's #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read the :ref:`Community Guide <ansible_community_guide>`, :ref:`Testing Ansible <developing_testing>`, and the :ref:`Developer Guide <developer_guide>`.

+If you are not sure whether the behavior you see is a bug, if you have questions, if you want to discuss development-oriented topics, or if you just want to get in touch, use one of our Google groups or IRC channels to  :ref:`communicate with Ansiblers <communication>`.

-The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.

+If you find a bug that affects a module in an Automation Hub collection:

-NOTE: If you have a Red Hat Ansible Automation product subscription, please follow the standard issue reporting process via the `Red Hat Customer Portal <https://access.redhat.com/>`_.

+  #. If the collection offers an Issue Tracker link on Automation Hub, click there and open an issue on the collection repository. If it does not, follow the standard process for reporting issues on the `Red Hat Customer Portal <https://access.redhat.com/>`_. You must have a subscription to the Red Hat Ansible Automation Platform to create an issue on the portal.

 Support

 =======

-For more information on how included Ansible modules are supported by Red Hat,

-please refer to the following `knowledge base article <https://access.redhat.com/articles/3166901>`_ as well as other resources on the `Red Hat Customer Portal. <https://access.redhat.com/>`_

+All plugins that remain in ansible-base and all collections hosted in Automation Hub are supported by Red Hat. No other plugins or collections are supported by Red Hat. If you have a subscription to the Red Hat Ansible Automation Platform, you can find more information and resources on the `Red Hat Customer Portal. <https://access.redhat.com/>`_

 .. seealso::

-   :ref:`Module index<modules_by_category>`

-       A complete list of all available modules.

    :ref:`intro_adhoc`

        Examples of using modules in /usr/bin/ansible

    :ref:`working_with_playbooks`

        Examples of using modules with /usr/bin/ansible-playbook

-   :ref:`developing_modules`

-       How to write your own modules

-   `List of Ansible Certified Modules <https://access.redhat.com/articles/3642632>`_

-       High level list of Ansible certified modules from Partners

    `Mailing List <https://groups.google.com/group/ansible-project>`_

        Questions? Help? Ideas?  Stop by the list on Google Groups

    `irc.freenode.net <http://irc.freenode.net>`_

@@ -4,20 +4,21 @@

 Search paths in Ansible

 ***********************

-Absolute paths are not an issue as they always have a known start, but relative paths ... well, they are relative.

+You can control the paths Ansible searches to find resources on your control node (including configuration, modules, roles, ssh keys, and more) as well as resources on the remote nodes you are managing. Use absolute paths to tell Ansible where to find resources whenever you can. However, absolute paths are not always practical. This page covers how Ansible interprets relative search paths, along with ways to troubleshoot when Ansible cannot find the resource you need.

+

+.. contents::

+   :local:

 Config paths

 ============

-By default these should be relative to the config file, some are specifically relative to the 'cwd' or the playbook and should have this noted in their description. Things like ssh keys are left to use 'cwd' because it mirrors how the underlying tools would use it.

+By default these should be relative to the config file, some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like ssh keys are left to use the current working directory because it mirrors how the underlying tools would use it.

 Task paths

 ==========

-Here things start getting complicated, there are 2 different scopes to consider, task evaluation (paths are all local, like in lookups) and task execution, which is normally on the remote, unless an action plugin is involved.

-

-Some tasks that require 'local' resources use action plugins (template and copy are examples of these), in which case the path is also local.

+Task paths include two different scopes: task evaluation and task execution. For task evaluation, all paths are local, like in lookups. For task execution, which usually happens on the remote nodes, local paths do not usually apply. However, if a task uses an action plugin, it uses a local path. The template and copy modules are examples of modules that use action plugins, and therefore use local paths.

 The magic of 'local' paths

 --------------------------

@@ -32,12 +33,10 @@ i.e ::

     play search path is playdir/{files|vars|templates}/, playdir/.

-The current working directory (cwd) is not searched. If you see it, it just happens to coincide with one of the paths above.

-If you `include` a task file from a role, it  will NOT trigger role behavior, this only happens when running as a role, `include_role` will work.

-A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.

+By default, Ansible does not search the current working directory unless it happens to coincide with one of the paths above. If you `include` a task file from a role, it  will NOT trigger role behavior, this only happens when running as a role, `include_role` will work. A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.

 As for includes, they try the path of the included file first and fall back to the play/role that includes them.

-.. note:  The 'cwd' might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory.

+.. note:  The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory.

@@ -70,7 +70,7 @@ Separate production and staging inventory

 You can keep your production environment separate from development, test, and staging environments by using separate inventory files or directories for each environment. This way you pick with -i what you are targeting. Keeping all your environments in one file can lead to surprises!

-.. _best_practices_for_variables_and_vaults:

+.. _tip_for_variables_and_vaults:

 Keep vaulted variables safely visible

 -------------------------------------

@@ -464,7 +464,7 @@ Possible values (sample, not complete list)::

    :ref:`playbooks_reuse_roles`

        Playbook organization by roles

    :ref:`playbooks_best_practices`

-       Best practices in playbooks

+       Tips and tricks for playbooks

    :ref:`playbooks_variables`

        All about variables

    `User Mailing List <https://groups.google.com/group/ansible-devel>`_

@@ -1,9 +1,9 @@

 .. _playbooks_delegation:

-Delegation and local actions

-============================

+Controlling where tasks run: delegation and local actions

+=========================================================

-By default Ansible executes all tasks on the machines that match the ``hosts`` line of your playbook. If you want to run some tasks on a different machine, you can use delegation. For example, when updating webservers, you might want to retrieve information from your database servers. In this scenario, your play would target the webservers group and you would delegate the database tasks to your dbservers group. With delegation, you can perform a task on one host on behalf of another, or execute tasks locally on behalf of remote hosts.

+By default Ansible gathers facts and executes all tasks on the machines that match the ``hosts`` line of your playbook. This page shows you how to delegate tasks to a different machine or group, delegate facts to specific machines or groups, or run an entire playbook locally. Using these approaches, you can manage inter-related environments precisely and efficiently. For example, when updating your webservers, you might need to remove them from a load-balanced pool temporarily. You cannot perform this task on the webservers themselves. By delegating the task to localhost, you keep all the tasks within the same play.

 .. contents::

    :local:

@@ -99,52 +99,10 @@ Delegating Ansible tasks is like delegating tasks in the real world - your groce

 This task gathers facts for the machines in the dbservers group and assigns the facts to those machines, even though the play targets the app_servers group. This way you can lookup `hostvars['dbhost1']['ansible_default_ipv4']['address']` even though dbservers were not part of the play, or left out by using `--limit`.

-.. _run_once:

-

-Run once

-

-If you want a task to run only on the first host in your batch of hosts, set ``run_once`` to true on that task::

-

-    ---

-    # ...

-

-      tasks:

-

-        # ...

-

-        - command: /opt/application/upgrade_db.py

-          run_once: true

-

-        # ...

-

-Ansible executes this task on the first host in the current batch and applies all results and facts to all the hosts in the same batch. This approach is similar to applying a conditional to a task such as::

-

-        - command: /opt/application/upgrade_db.py

-          when: inventory_hostname == webservers[0]

-

-However, with ``run_once``, the results are applied to all the hosts. To specify an individual host to execute on, delegate the task::

-

-        - command: /opt/application/upgrade_db.py

-          run_once: true

-          delegate_to: web01.example.org

-

-As always with delegation, the action will be executed on the delegated host, but the information is still that of the original host in the task.

-

-.. note::

-     When used together with "serial", tasks marked as "run_once" will be run on one host in *each* serial batch. If the task must run only once regardless of "serial" mode, use

-     :code:`when: inventory_hostname == ansible_play_hosts_all[0]` construct.

-

-.. note::

-    Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.

-

-.. note::

-    If you want to avoid the default behavior of setting the fact for all hosts, set `delegate_facts: True` for the specific task or block.

-

 .. _local_playbooks:

 Local playbooks

-```````````````

+---------------

 It may be useful to use a playbook locally on a remote host, rather than by connecting over SSH.  This can be useful for assuring the configuration of a system by putting a playbook in a crontab.  This may also be used

 to run a playbook inside an OS installer, such as an Anaconda kickstart.

@@ -165,11 +123,12 @@ use the default remote connection type::

     under {{ ansible_playbook_python }}. Be sure to set ansible_python_interpreter: "{{ ansible_playbook_python }}" in

     host_vars/localhost.yml, for example. You can avoid this issue by using ``local_action`` or ``delegate_to: localhost`` instead.

-

 .. seealso::

    :ref:`playbooks_intro`

        An introduction to playbooks

+   :ref:`playbooks_strategies`

+       More ways to control how and where Ansible executes

    `Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_

        Many examples of full-stack deployments

    `User Mailing List <https://groups.google.com/group/ansible-devel>`_

@@ -231,7 +231,7 @@ You can also use blocks to define responses to task errors. This approach is sim

    :ref:`playbooks_intro`

        An introduction to playbooks

    :ref:`playbooks_best_practices`

-       Best practices in playbooks

+       Tips and tricks for playbooks

    :ref:`playbooks_conditionals`

        Conditional statements in playbooks

    :ref:`playbooks_variables`

@@ -1644,7 +1644,7 @@ This can then be used to reference hashes in Pod specifications::

    :ref:`playbooks_reuse_roles`

        Playbook organization by roles

    :ref:`playbooks_best_practices`

-       Best practices in playbooks

+       Tips and tricks for playbooks

    `User Mailing List <https://groups.google.com/group/ansible-devel>`_

        Have a question?  Stop by the google group!

    `irc.freenode.net <http://irc.freenode.net>`_

@@ -737,7 +737,7 @@ the filter ``slaac()`` generates an IPv6 address for a given network and a MAC A

    :ref:`playbooks_reuse_roles`

        Playbook organization by roles

    :ref:`playbooks_best_practices`

-       Best practices in playbooks

+    	 Tips and tricks for playbooks

    `User Mailing List <https://groups.google.com/group/ansible-devel>`_

        Have a question?  Stop by the google group!

    `irc.freenode.net <http://irc.freenode.net>`_

@@ -430,7 +430,7 @@ Migrating from with_X to loop

    :ref:`playbooks_reuse_roles`

        Playbook organization by roles

    :ref:`playbooks_best_practices`

-       Best practices in playbooks

+       Tips and tricks for playbooks

    :ref:`playbooks_conditionals`

        Conditional statements in playbooks

    :ref:`playbooks_variables`

@@ -188,7 +188,7 @@ Imports are processed before the play begins, so the name of the import no longe

    :ref:`playbooks_loops`

        Loops in playbooks

    :ref:`playbooks_best_practices`

-       Various tips about managing playbooks in the real world

+       Tips and tricks for playbooks

    :ref:`ansible_galaxy`

        How to share roles on galaxy, role management

    `GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_

@@ -15,7 +15,7 @@ The content on this page has been moved to :ref:`playbooks_reuse`.

    :ref:`working_with_playbooks`

        Review the basic Playbook language features

    :ref:`playbooks_best_practices`

-       Various tips about managing playbooks in the real world

+       Tips and tricks for playbooks

    :ref:`playbooks_variables`

        All about variables in playbooks

    :ref:`playbooks_conditionals`

@@ -441,7 +441,7 @@ Read the `Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_ page

    :ref:`working_with_playbooks`

        Review the basic Playbook language features

    :ref:`playbooks_best_practices`

-       Tips for managing playbooks in the real world

+       Tips and tricks for playbooks

    :ref:`playbooks_variables`

        Variables in playbooks

    :ref:`playbooks_conditionals`

@@ -19,7 +19,7 @@ As you write more playbooks and roles, you might have some special use cases. Fo

    ../plugins/plugins

    playbooks_prompts

    playbooks_tags

-   playbooks_vault

+   vault

    playbooks_startnstep

    ../reference_appendices/playbooks_keywords

    playbooks_lookups

@@ -36,7 +36,7 @@ or pass it on the command line: `ansible-playbook -f 30 my_playbook.yml`.

 Using keywords to control execution

 -----------------------------------

-In addition to strategies, several :ref:`keywords<playbook_keywords>` also affect play execution. You can set a number, a percentage, or a list of numbers of hosts you want to manage at a time with ``serial``. Ansible completes the play on the specified number or percentage of hosts before starting the next batch of hosts. You can restrict the number of workers allotted to a block or task with ``throttle``. You can control how Ansible selects the next host in a group to execute against with ``order``. These keywords are not strategies. They are directives or options applied to a play, block, or task.

+In addition to strategies, several :ref:`keywords<playbook_keywords>` also affect play execution. You can set a number, a percentage, or a list of numbers of hosts you want to manage at a time with ``serial``. Ansible completes the play on the specified number or percentage of hosts before starting the next batch of hosts. You can restrict the number of workers allotted to a block or task with ``throttle``. You can control how Ansible selects the next host in a group to execute against with ``order``. You can run a task on a single host with ``run_once``. These keywords are not strategies. They are directives or options applied to a play, block, or task.

 .. _rolling_update_batch_size:

@@ -160,10 +160,54 @@ shuffle:

 Other keywords that affect play execution include ``ignore_errors``, ``ignore_unreachable``, and ``any_errors_fatal``. These options are documented in :ref:`playbooks_error_handling`.

+.. _run_once:

+

+Running on a single machine with ``run_once``

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+

+If you want a task to run only on the first host in your batch of hosts, set ``run_once`` to true on that task::

+

+    ---

+    # ...

+

+      tasks:

+

+        # ...

+

+        - command: /opt/application/upgrade_db.py

+          run_once: true

+

+        # ...

+

+Ansible executes this task on the first host in the current batch and applies all results and facts to all the hosts in the same batch. This approach is similar to applying a conditional to a task such as::

+

+        - command: /opt/application/upgrade_db.py

+          when: inventory_hostname == webservers[0]

+

+However, with ``run_once``, the results are applied to all the hosts. To run the task on a specific host, instead of the first host in the batch, delegate the task::

+

+        - command: /opt/application/upgrade_db.py

+          run_once: true

+          delegate_to: web01.example.org