From a01376a493a755923895893e21ac3ce7e4b12ed2 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 15 Nov 2019 10:49:51 -0500 Subject: [PATCH] update configuring ansible-galaxy client (#64796) * update configuring ansible-galaxy client, deduplicate, clarify tokens, AH procedures, etc. --- .../rst/dev_guide/developing_collections.rst | 27 +++++++++--- docs/docsite/rst/galaxy/user_guide.rst | 44 ++++++++++++++++--- .../shared_snippets/galaxy_server_list.txt | 39 ++++++++++------ .../installing_collections.txt | 3 ++ .../rst/user_guide/collections_using.rst | 9 ++-- 5 files changed, 94 insertions(+), 28 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index 1875cdf377a..adff246163e 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/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 -a tarball of the built collection in the current directory which can be uploaded to Galaxy.:: +This creates a tarball of the built collection in the current directory which can be uploaded to Galaxy.:: my_collection/ ├── galaxy.yml @@ -280,8 +279,8 @@ can set the following in your ``galaxy.yml`` file: .. _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: @@ -306,11 +305,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 `_ 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 `. + To upload the collection artifact with the ``ansible-galaxy`` command: .. code-block:: bash @@ -322,8 +336,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 `_ page. -The API key is a secret token used by Ansible Galaxy to protect your content. You can find your API key at your -`Galaxy profile preferences `_ page. +The API key is a secret token used by the Galaxy server to protect your content. See :ref:`galaxy_get_token` for details. .. _upload_collection_galaxy: @@ -351,7 +364,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 `_ for version numbers. Please read the official documentation for details and examples. In summary: +Collection versions use `Semantic Versioning `_ 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. diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst index a80141e07fc..17da45c6f58 100644 --- a/docs/docsite/rst/galaxy/user_guide.rst +++ b/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 `_ + An introduction to Automation Hub Installing an older version of a collection ------------------------------------------- @@ -44,11 +78,11 @@ Install multiple collections with a requirements file .. include:: ../shared_snippets/installing_multiple_collections.txt -Galaxy server configuration list --------------------------------- -.. include:: ../shared_snippets/galaxy_server_list.txt +Configuring the ``ansible-galaxy`` client +------------------------------------------ +.. include:: ../shared_snippets/galaxy_server_list.txt .. _finding_galaxy_roles: diff --git a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt index 5e9f94f0c45..0e3d6d5c73d 100644 --- a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt +++ b/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 -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 -using the :ref:`galaxy_server_list` configuration option. To define multiple Galaxy servers you have to create the -following entries like so: +You can configure this to use other servers (such as Red Hat Automation Hub or a custom Galaxy server) as follows: + +* Set the server list in the :ref:`galaxy_server_list` configuration option in :ref:`ansible_configuration_settings_locations`. +* Use the ``--server`` command line argument to limit to an individual server. + +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/ - auth_url=https://sso.qa.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token - token=my_token + 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 [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 - 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 + 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 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: diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt index f721feda1ac..7d8ad2c0cfa 100644 --- a/docs/docsite/rst/shared_snippets/installing_collections.txt +++ b/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 ` if you are using any other Galaxy server, such as Red Hat Automation Hub). + To install a collection hosted in Galaxy: .. code-block:: bash diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index aea06332b0f..b95100f321f 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -17,6 +17,10 @@ You can install and use collections through `Ansible Galaxy