update configuring ansible-galaxy client (#64796)
* update configuring ansible-galaxy client, deduplicate, clarify tokens, AH procedures, etc.
This commit is contained in:
Sandra McCann
Alicia Cozine
parent
64595a7d6a
commit
a01376a493
|
|
@ -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 <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
|
||||
|
|
@ -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 <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:
|
||||
|
||||
|
|
@ -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 <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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue