update configuring ansible-galaxy client (#64796) (#64904)

* update configuring ansible-galaxy client, deduplicate, clarify tokens, AH procedures, etc.

(cherry picked from commit a01376a493)

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -223,8 +223,7 @@ To build a collection, run ``ansible-galaxy collection build`` from inside the r
 
     collection_dir#> ansible-galaxy collection build
 
-This creates
+This creates a tarball of the built collection in the current directory which can be uploaded to Galaxy.::
-a tarball of the built collection in the current directory which can be uploaded to Galaxy.::
 
     my_collection/
     ├── galaxy.yml
@@ -245,8 +244,8 @@ as a distribution method, but you can use it directly to install the collection
 
 .. _trying_collection_locally:
 
-Trying collection locally
+Trying collections locally
--------------------------
+--------------------------
 
 You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to
 access the collection:
@@ -271,11 +270,26 @@ You can publish collections to Galaxy using the ``ansible-galaxy collection publ
 
 .. note:: Once you upload a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before you upload it.
 
+.. _galaxy_get_token:
+
+Getting your token or API key
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To upload your collection to Galaxy, you must first obtain an API token (``--api-key`` in the ``ansible-galaxy`` CLI command). The API token is a secret token used to protect your content.
+
+To get your API token:
+
+* For galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API token`.
+* For Automation Hub, go to https://cloud.redhat.com/ansible/automation-hub/token/ and click :guilabel:`Get API token` from the version dropdown.
+
 .. _upload_collection_ansible_galaxy:
 
 Upload using ansible-galaxy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. note::
+  By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
+
 To upload the collection artifact with the ``ansible-galaxy`` command:
 
 .. code-block:: bash
@@ -287,8 +301,7 @@ The command waits until the import process completes before reporting the status
 without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your
 `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
 
-The API key is a secret token used by Ansible Galaxy to protect your content. You can find your API key at your
+The API key is a secret token used by the Galaxy server to protect your content. See :ref:`galaxy_get_token` for details.
-`Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page.
 
 .. _upload_collection_galaxy:
 
@@ -316,7 +329,7 @@ Once you upload a version of a collection, you cannot delete or modify that vers
 uploading. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number)
 will be the version displayed everywhere in Galaxy; however, users will still be able to download older versions.
 
-Collection versions use `Sematic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
+Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
 
 * Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
 * Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner.

docs/docsite/rst/galaxy/user_guide.rst

@@ -28,11 +28,45 @@ Galaxy presents a list of collections that match your search criteria.
 
 .. _installing_galaxy_collections:
 
-Installing collections from Galaxy
+
-==================================
+Installing collections
+======================
+
+
+Installing a collection from Galaxy
+-----------------------------------
 
 .. include:: ../shared_snippets/installing_collections.txt
 
+.. _installing_ah_collection:
+
+Downloading a collection from Automation Hub
+----------------------------------------------------
+
+To download a collection from Automation Hub with the ``ansible-galaxy`` command:
+
+1. Get your Automation Hub API token. Go to https://cloud.redhat.com/ansible/automation-hub/token/ and click :guilabel:`Get API token` from the version dropdown to copy your API token.
+2. Configure Red Hat Automation Hub server in the ``server_list``  option under the ``[galaxy]`` section in your :file:`ansible.cfg` file.
+
+  .. code-block:: ini
+
+      [galaxy]
+      server_list = automation_hub
+
+      [galaxy_server.automation_hub]
+      url=https://cloud.redhat.com/api/automation-hub/
+      auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
+      token=my_ah_token
+
+3. Download the collection hosted in Automation Hub.
+
+  .. code-block:: bash
+
+     ansible-galaxy collection install my_namespace.my_collection
+
+.. seealso::
+  `Getting started with Automation Hub <https://www.ansible.com/blog/getting-started-with-ansible-hub>`_
+    An introduction to Automation Hub
 
 Installing an older version of a collection
 -------------------------------------------
@@ -44,12 +78,12 @@ Install multiple collections with a requirements file
 
 .. include:: ../shared_snippets/installing_multiple_collections.txt
 
-Galaxy server configuration list
+
---------------------------------
+Configuring the ``ansible-galaxy`` client
+------------------------------------------
 
 .. include:: ../shared_snippets/galaxy_server_list.txt
 
-
 .. _finding_galaxy_roles:
 
 Finding roles on Galaxy

docs/docsite/rst/shared_snippets/galaxy_server_list.txt

@@ -1,11 +1,24 @@
 
 
+By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`).
 
-By default running ``ansible-galaxy`` will use the :ref:`galaxy_server` config value or the ``--server`` command line
+You can configure this to use other servers (such as Red Hat Automation Hub or a custom Galaxy server) as follows:
-argument when it performs an action against a Galaxy server. The ``ansible-galaxy collection install`` supports
+
-installing collections from multiple servers as defined in the :ref:`ansible_configuration_settings_locations` file
+* Set the server list in the :ref:`galaxy_server_list` configuration option in :ref:`ansible_configuration_settings_locations`.
-using the :ref:`galaxy_server_list` configuration option. To define multiple Galaxy servers you have to create the
+* Use the ``--server`` command line argument to limit to an individual server.
-following entries like so:
+
+To configure a Galaxy server list in ``ansible.cfg``:
+
+#. Add the ``server_list``  option under the ``[galaxy]`` section to one or more server names.
+#. Create a new section for each server name.
+#. Set the ``url`` option for each server name.
+
+For Automation Hub, you additionally need to:
+
+#. Set the ``auth_url`` option for each server name.
+#. Set the API token for each server name. Go to https://cloud.redhat.com/ansible/automation-hub/token/ and click ::guilabel:`Get API token` from the version dropdown to copy your API token.
+
+The following example shows how to configure multiple servers:
 
 .. code-block:: ini
 
@@ -13,9 +26,10 @@ following entries like so:
     server_list = automation_hub, my_org_hub, release_galaxy, test_galaxy
 
     [galaxy_server.automation_hub]
-    url=https://ci.cloud.redhat.com/api/automation-hub/
+    url=https://cloud.redhat.com/api/automation-hub/
-    auth_url=https://sso.qa.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
+    auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
-    token=my_token
+
+    token=my_ah_token
 
     [galaxy_server.my_org_hub]
     url=https://automation.my_org/
@@ -28,18 +42,17 @@ following entries like so:
 
     [galaxy_server.test_galaxy]
     url=https://galaxy-dev.ansible.com/
-    token=my_token
+    token=my_test_token
 
 .. note::
     You can use the ``--server`` command line argument to select an explicit Galaxy server in the ``server_list`` and
-    the value of this arg should match the name of the server. If the value of ``--server`` is not a pre-defined server
+    the value of this argument should match the name of the server. To use a server not in the server list, set the value to the URL to access that server (all servers in the server list will be ignored). Also the ``--api-key`` argument is not applied to any of the predefined servers. It is only applied
-    in ``ansible.cfg`` then the value specified will be the URL used to access that server and all pre-defined servers
-    are ignored. Also the ``--api-key`` argument is not applied to any of the pre-defined servers, it is only applied
     if no server list is defined or a URL was specified by ``--server``.
 
+**Galaxy server list configuration options**
 
 The :ref:`galaxy_server_list` option is a list of server identifiers in a prioritized order. When searching for a
-collection, the install process will search in that order, e.g. ``my_org_hub`` first, then ``release_galaxy``, and
+collection, the install process will search in that order, e.g. ``automation_hub`` first, then ``my_org_hub``, ``release_galaxy``, and
 finally ``test_galaxy`` until the collection is found. The actual Galaxy instance is then defined under the section
 ``[galaxy_server.{{ id }}]`` where ``{{ id }}`` is the server identifier defined in the list. This section can then
 define the following keys:

docs/docsite/rst/shared_snippets/installing_collections.txt

@@ -1,6 +1,9 @@
 
 You can use the ``ansible-galaxy collection install`` command to install a collection on your system.
 
+.. note::
+  By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). You do not need any further configuration. See :ref:`Configuring the ansible-galaxy client <galaxy_server_config>` if you are using any other Galaxy server, such as Red Hat Automation Hub).
+
 To install a collection hosted in Galaxy:
 
 .. code-block:: bash

docs/docsite/rst/user_guide/collections_using.rst

@@ -17,6 +17,10 @@ You can install and use collections through `Ansible Galaxy <https://galaxy.ansi
 Installing collections
 ======================
 
+
+Installing collections with ``ansible-galaxy``
+----------------------------------------------
+
 .. include:: ../shared_snippets/installing_collections.txt
 
 .. _collections_older_version:
@@ -33,11 +37,10 @@ Install multiple collections with a requirements file
 
 .. include:: ../shared_snippets/installing_multiple_collections.txt
 
-
 .. _galaxy_server_config:
 
-Galaxy server configuration list
+Configuring the ``ansible-galaxy`` client
---------------------------------
+------------------------------------------
 
 .. include:: ../shared_snippets/galaxy_server_list.txt