wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

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

(cherry picked from commit a01376a493)
This commit is contained in:
Alicia Cozine 2019-11-15 11:52:24 -06:00 committed by GitHub
parent d4f1552a19
commit 23de3c1614
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 94 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

27
docs/docsite/rst/dev_guide/developing_collections.rst
View file

@ -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
@ -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
`Galaxy profile preferences <https://galaxy.ansible.com/me/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:
@ -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.

44
docs/docsite/rst/galaxy/user_guide.rst
View file

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

39
docs/docsite/rst/shared_snippets/galaxy_server_list.txt
View file

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

3
docs/docsite/rst/shared_snippets/installing_collections.txt
View file

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

9
docs/docsite/rst/user_guide/collections_using.rst
View file

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