Backportapalooza 08 16 (#78584)

* Supply some descriptions for settings used in ansible.cfg (#78536)

(cherry picked from commit 4604ea38ddf8e90b0f0e37c07c3a9da5efef18bc)

* Targeting a small typo correction (#78531)

(cherry picked from commit b6f42547f415f162e180ff94be94ea82a30b35a2)

* clarify collection signature not available from Community Galaxy (#78386)

(cherry picked from commit 7ae1eabaa41080fc97e0155919471f57dba23825)

* update FAQ with not about libyaml (#78483)

(cherry picked from commit 33ee5d4c1b8ea5357e29749a71f55d8f03642b9e)

* add note to use package_facts module (#78484)

(cherry picked from commit 8dc097989b88f4f4bf40434016faabbeb5e25d5f)

* Fix ansible-docs: shipping ansible in wheel format  #78485 (#78524)

(cherry picked from commit 7f69629fa787fb5242534111cec2fb4772e3f1b9)

* update link for RH customers in docs banner (#78563)

(cherry picked from commit 2fdaee143a88e1c63c7dc56f06a114bf31380683)

Co-authored-by: Andrew Latham <lathama@users.noreply.github.com>
Co-authored-by: Ian Wienand <iwienand@redhat.com>
Co-authored-by: Arnold Kamanzi <kamstan6@gmail.com>

6 files changed, 126 insertions, 73 deletions

diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html
index 3288eb8e8a..57c104d9da 100644
--- a/docs/docsite/.templates/banner.html
+++ b/docs/docsite/.templates/banner.html
@@ -46,7 +46,7 @@
         /* temp extra banner to advertise AnsibeFest2021 */
         banner += extra_banner;
 
-        msg += 'You are reading the <b>latest</b> (stable) community version of the Ansible documentation. Red Hat subscribers, select <b>2.9</b> in the version selection to the left for the most recent Red Hat release.';
+        msg += 'You are reading the <b>latest</b> (stable) community version of the Ansible documentation. If you are a Red Hat customer, refer to the <a href="https://access.redhat.com/support/policy/updates/ansible-automation-platform">Ansible Automation Platform Life Cycle</a> page for subscription details.';
       } else if (startsWith(current_url_path, "/ansible/2.9/")) {
         msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select <b>latest</b> from the version selector to the left for the most recent community version.';
       } else if (startsWith(current_url_path, "/ansible/devel/")) {
diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
index d040668055..a13226ea70 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
@@ -6,15 +6,16 @@ Distributing collections
 
 A collection is a distribution format for Ansible content. A typical collection contains modules and other plugins that address a set of related use cases. For example, a collection might automate administering a particular database. A collection can also contain roles and playbooks.
 
-To distribute your collection and allow others to use it, you can publish your collection on one or more distribution servers. Distribution servers include:
+To distribute your collection and allow others to use it, you can publish your collection on one or more :term:`distribution server`. Distribution servers include:
 
-================================= ========================================================
+================================= ===================================================================
 Distribution server               Collections accepted
-================================= ========================================================
+================================= ===================================================================
 Ansible Galaxy                    All collections
-Red Hat Automation Hub            Only collections certified by Red Hat
+:term:`Pulp 3 Galaxy`             All collections, supports signed collections
+Red Hat Automation Hub            Only collections certified by Red Hat, supports signed collections
 Privately hosted Automation Hub   Collections authorized by the owners
-================================= ========================================================
+================================= ===================================================================
 
 Distributing collections involves four major steps:
 
@@ -179,6 +180,22 @@ For more information on the :file:`galaxy.yml` file, see :ref:`collections_galax
 .. note::
      The ``build_ignore`` feature is only supported with ``ansible-galaxy collection build`` in Ansible 2.10 or newer.
 
+
+.. _signing_collections:
+
+Signing a collection
+--------------------------
+
+You can include a GnuPG signature with your collection on a :term:`Pulp 3 Galaxy` server. See `Enabling collection signing <https://galaxyng.netlify.app/config/collection_signing/>`_ for details.
+
+You can manually generate detached signatures for a collection using the ``gpg`` CLI using the following step. This step assume you have generated a GPG private key, but do not cover this process.
+
+.. code-block:: bash
+
+   ansible-galaxy collection build
+   tar -Oxzf namespace-name-1.0.0.tar.gz MANIFEST.json | gpg --output namespace-name-1.0.0.asc --detach-sign --armor --local-user email@example.com -
+
+
 .. _trying_collection_locally:
 
 Preparing to publish your collection
diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst
index a969fd4d0c..486fb5f09a 100644
--- a/docs/docsite/rst/reference_appendices/faq.rst
+++ b/docs/docsite/rst/reference_appendices/faq.rst
@@ -23,6 +23,15 @@ Where did this specific module go?
 
 IF you are searching for a specific module, you can check the `runtime.yml <https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml>`_ file, which lists the first destination for each module that we extracted from the main ansible/ansible repository. Some modules have moved again since then. You can also search on `Ansible Galaxy <https://galaxy.ansible.com/>`_ or ask on one of our :ref:`chat channels <communication_irc>`.
 
+.. _slow_install:
+
+How can I speed up Ansible on systems with slow disks?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Ansible may feel sluggish on systems with slow disks, such as Raspberry PI. See `Ansible might be running slow if libyaml is not available <https://www.jeffgeerling.com/blog/2021/ansible-might-be-running-slow-if-libyaml-not-available>`_ for hints on how to improve this.
+
+
+
 .. _set_environment:
 
 How can I set the PATH or any other environment variable for a task or entire play?
@@ -709,15 +718,6 @@ To determine if a keyword requires ``{{ }}`` or even supports templating, use ``
 this will return documentation on the keyword including a ``template`` field with the values ``explicit`` (requires ``{{ }}``),
 ``implicit`` (assumes ``{{ }}``, so no needed) or ``static`` (no templating supported, all characters will be interpreted literally)
 
-.. _why_no_wheel:
-
-Why don't you ship ansible in wheel format (or other packaging format) ?
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-In most cases it has to do with maintainability. There are many ways to ship software and we do not have
-the resources to release Ansible on every platform.
-In some cases there are technical issues. For example, our dependencies are not present on Python Wheels.
-
 .. _ansible_host_delegated:
 
 How do I get the original ansible_host when I delegate a task?
diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst
index 10fdd2dd4a..f30a933c18 100644
--- a/docs/docsite/rst/reference_appendices/glossary.rst
+++ b/docs/docsite/rst/reference_appendices/glossary.rst
@@ -33,7 +33,7 @@ when a term comes up on the mailing list.
         Name used starting with 2.11. The installable package (RPM/Python/Deb package) generated from the `ansible/ansible repository <https://github.com/ansible/ansible>`_. Contains the command-line tools and the code for basic features and functions, such as copying module code to managed nodes. The ``ansible-core`` package includes a few modules and plugins and allows you to add others by installing collections.
 
     Ansible Galaxy
-        An `online resource <galaxy.ansible.com>`_ for finding and sharing Ansible community content. Also, the command-line utility that lets users install individual Ansible Collections, for example`` ansible-galaxy install community.crypto``.
+        An `online distribution server <galaxy.ansible.com>`_ for finding and sharing Ansible community content, sometimes referred to as community Galaxy. Also, the command-line utility that lets users install individual Ansible Collections, for example ``ansible-galaxy collection install community.crypto``.
 
     Async
         Refers to a task that is configured to run in the background rather
@@ -108,6 +108,9 @@ when a term comes up on the mailing list.
         modules that support it. You can combine it with ``--check`` to get a
         good 'dry run'.  File diffs are normally in unified diff format.
 
+    Distribution server
+        A server, such as Ansible Galaxy or Red Hat Automation Hub where you can distribute your collections and allow others to access these collections. See :ref:`distributing_collections` for a list of distribution server types. Some Ansible features are only available on certain distribution servers.
+
     Executor
         A core software component of Ansible that is the power behind
         :command:`/usr/bin/ansible` directly -- and corresponds to the
@@ -386,6 +389,10 @@ when a term comes up on the mailing list.
         git on a crontab and then managing the machine locally, using the
         :term:`local connection` plugin.
 
+    Pulp 3 Galaxy
+        A self-hosted distribution server based on the `GalaxyNG codebase <https://galaxyng.netlify.app/>`_, based on Pulp version 3. Use it to find and share your own curated set of content. You can access your content with the ``ansible-galaxy collection`` command.
+
+
     Push Mode
         Push mode is the default mode of Ansible. In fact, it's not really
         a mode at all -- it's just how Ansible works when you aren't thinking
diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt
index ba241088f9..23f5c3e78c 100644
--- a/docs/docsite/rst/shared_snippets/installing_collections.txt
+++ b/docs/docsite/rst/shared_snippets/installing_collections.txt
@@ -70,34 +70,3 @@ You can also keep a collection adjacent to the current playbook, under a ``colle
 
 See :ref:`collection_structure` for details on the collection directory structure.
 
-Collections signed by a Galaxy server can be verified during installation with GnuPG. To opt into signature verification, configure a keyring for ``ansible-galaxy`` with native GnuPG tooling and provide the file path with the ``--keyring`` CLI option or ref:`GALAXY_GPG_KEYRING`. Signatures provided by the Galaxy server will be used to verify the collection's ``MANIFEST.json``.
-
-Use the ``--signature`` option to verify the collection's ``MANIFEST.json`` with additional signatures to those provided by the Galaxy server. Supplemental signatures should be provided as URIs.
-
-.. code-block:: bash
-
-   ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx
-
-GnuPG verification only occurs for collections installed from a Galaxy server. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files.
-
-By default, verification is considered successful if a minimum of 1 signature successfully verifies the collection. The number of required signatures can be configured with ``--required-valid-signature-count`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. All signatures can be required by setting the option to ``all``. To fail signature verification if no valid signatures are found, prepend the value with ``+``, such as ``+all`` or ``+1``.
-
-.. code-block:: bash
-
-   export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
-   export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=2
-   ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc
-
-Certain GnuPG errors can be ignored with ``--ignore-signature-status-code`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT` should be a list, and ``--ignore-signature-status-code`` can be provided multiple times to ignore multiple additional error status codes.
-
-This example requires any signatures provided by the Galaxy server to verify the collection except if they fail due to NO_PUBKEY:
-
-.. code-block:: bash
-
-   export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
-   export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=all
-   ansible-galaxy collection install my_namespace.my_collection --ignore-signature-status-code NO_PUBKEY
-
-If verification fails for the example above, only errors other than NO_PUBKEY will be displayed.
-
-If verification is unsuccessful, the collection will not be installed. GnuPG signature verification can be disabled with ``--disable-gpg-verify`` or by configuring :ref:`GALAXY_DISABLE_GPG_VERIFY`.
diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst
index 1bebb1dec6..f259ffcba6 100644
--- a/docs/docsite/rst/user_guide/collections_using.rst
+++ b/docs/docsite/rst/user_guide/collections_using.rst
@@ -7,7 +7,7 @@ Using collections
 
 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 :ref:`collections pages <list_of_collections>`.
 
-You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
+You can install and use collections through a distribution server, such as `Ansible Galaxy <https://galaxy.ansible.com>`_ or a `Pulp 3 Galaxy server <https://galaxyng.netlify.app/>`_.
 
 * For details on how to *develop* collections see :ref:`developing_collections`.
 * For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/main/README.rst>`_.
@@ -30,6 +30,81 @@ Installing collections with ``ansible-galaxy``
 
 .. include:: ../shared_snippets/installing_collections.txt
 
+.. _installing_signed_collections:
+
+Installing collections with signature verification
+---------------------------------------------------
+
+If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the ``MANIFEST.json`` before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing which servers support collection signing.
+
+To use signature verification for signed collections:
+
+1. :ref:`Configured a GnuPG keyring <galaxy_gpg_keyring>` for ``ansible-galaxy``, or provide the path to the keyring with the ``--keyring`` option when you install the signed collection.
+   
+
+2. Import the public key from the distribution server into that keyring.
+   
+   .. code-block:: bash
+
+     gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
+
+
+3. Verify the signature when you install the collection.
+   
+   .. code-block:: bash
+
+     ansible-galaxy collection install my_namespace.my_collection --keyring ~/.ansible/pubring.kbx
+
+   The ``--keyring`` option is not necessary if you have :ref:`configured a GnuPG keyring <galaxy_gpg_keyring>`. 
+
+4. Optionally, verify the signature at any point after installation to prove the collection has not been tampered with. See :ref:`verify_signed_collections` for details.
+
+
+You can also include signatures in addition to those provided by the distribution server. Use the ``--signature`` option to verify the collection's ``MANIFEST.json`` with these additional signatures. Supplemental signatures should be provided as URIs.
+
+.. code-block:: bash
+
+   ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx
+
+GnuPG verification only occurs for collections installed from a distribution server. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files.
+
+You can also include additional signatures in the collection ``requirements.yml`` file under the ``signatures`` key.
+
+.. code-block:: yaml
+
+   # requirements.yml
+   collections:
+     - name: ns.coll
+       version: 1.0.0
+       signatures:
+         - https://examplehost.com/detached_signature.asc
+         - file:///path/to/local/detached_signature.asc
+
+See :ref:`collection requirements file <collection_requirements_file>` for details on how to install collections with this file.
+
+By default, verification is considered successful if a minimum of 1 signature successfully verifies the collection. The number of required signatures can be configured with ``--required-valid-signature-count`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. All signatures can be required by setting the option to ``all``. To fail signature verification if no valid signatures are found, prepend the value with ``+``, such as ``+all`` or ``+1``.
+
+.. code-block:: bash
+
+   export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
+   export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=2
+   ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc
+
+Certain GnuPG errors can be ignored with ``--ignore-signature-status-code`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT` should be a list, and ``--ignore-signature-status-code`` can be provided multiple times to ignore multiple additional error status codes.
+
+This example requires any signatures provided by the distribution server to verify the collection except if they fail due to NO_PUBKEY:
+
+.. code-block:: bash
+
+   export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
+   export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=all
+   ansible-galaxy collection install my_namespace.my_collection --ignore-signature-status-code NO_PUBKEY
+
+If verification fails for the example above, only errors other than NO_PUBKEY will be displayed.
+
+If verification is unsuccessful, the collection will not be installed. GnuPG signature verification can be disabled with ``--disable-gpg-verify`` or by configuring :ref:`GALAXY_DISABLE_GPG_VERIFY`.
+
+
 .. _collections_older_version:
 
 Installing an older version of a collection
@@ -270,25 +345,19 @@ In addition to the ``namespace.collection_name:version`` format, you can provide
 
 Verifying against ``tar.gz`` files is not supported. If your ``requirements.yml`` contains paths to tar files or URLs for installation, you can use the ``--ignore-errors`` flag to ensure that all collections using the ``namespace.name`` format in the file are processed.
 
-Signature verification
-----------------------
-
-If a collection has been signed by the Galaxy server, the server will provide ASCII armored, detached signatures to verify the authenticity of the MANIFEST.json before using it to verify the collection's contents. You must opt into signature verification by :ref:`configuring a keyring <galaxy_gpg_keyring>` for ``ansible-galaxy``, or by providing the path with the ``--keyring`` option.
+.. _verify_signed_collections:
 
-To import a public key into a keyring for use with ``ansible-galaxy`` use the following step.
+Verifying signed collections
+-----------------------------
 
-.. code-block:: bash
+If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the MANIFEST.json before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing which servers support collection signing. See :ref:`installing_signed_collections` for how to verify a signed collection when you install it.
 
-   gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
-
-In addition to any signatures provided by the Galaxy server, signature sources can also be provided in the requirements file and on the command line. Signature sources should be URIs.
-
-You can manually generate detached signatures for a collection using the ``gpg`` CLI using the following step. This step assume you have generated a GPG private key, but do not cover this process.
+To verify a signed installed collection:
 
 .. code-block:: bash
 
-   ansible-galaxy collection build
-   tar -Oxzf namespace-name-1.0.0.tar.gz MANIFEST.json | gpg --output namespace-name-1.0.0.asc --detach-sign --armor --local-user email@example.com -
+   ansible-galaxy collection verify my_namespace.my_collection  --keyring ~/.ansible/pubring.kbx
+
 
 Use the ``--signature`` option to verify collection name(s) provided on the CLI with an additional signature. This option can be used multiple times to provide multiple signatures.
 
@@ -296,28 +365,19 @@ Use the ``--signature`` option to verify collection name(s) provided on the CLI
 
    ansible-galaxy collection verify my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc --keyring ~/.ansible/pubring.kbx
 
-Collections in a requirements file should list any additional signature sources following the collection's "signatures" key.
-
-.. code-block:: yaml
-
-   # requirements.yml
-   collections:
-     - name: ns.coll
-       version: 1.0.0
-       signatures:
-         - https://examplehost.com/detached_signature.asc
-         - file:///path/to/local/detached_signature.asc
+Optionally, you can verify a collection signature with a ``requirements.yml`` file.
 
 .. code-block:: bash
 
    ansible-galaxy collection verify -r requirements.yml --keyring ~/.ansible/pubring.kbx
 
-When a collection is installed from a Galaxy server, the signatures provided by the server to verify the collection's authenticity are saved alongside the installed collections. This data is used to verify the internal consistency of the collection without querying the Galaxy server again when the ``--offline`` option is provided.
+When a collection is installed from a distribution server, the signatures provided by the server to verify the collection's authenticity are saved alongside the installed collections. This data is used to verify the internal consistency of the collection without querying the distribution server again when the ``--offline`` option is provided.
 
 .. code-block:: bash
 
    ansible-galaxy collection verify my_namespace.my_collection --offline --keyring ~/.ansible/pubring.kbx
 
+
 .. _collections_using_playbook:
 
 Using collections in a Playbook