@ -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
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.
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.
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:
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
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).
Sandra McCann
5 years ago
committed by