@ -223,8 +223,7 @@ To build a collection, run ``ansible-galaxy collection build`` from inside the r
collection_dir#> ansible-galaxy collection build
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/
my_collection/
├── galaxy.yml
├── galaxy.yml
@ -280,8 +279,8 @@ can set the following in your ``galaxy.yml`` file:
.._trying_collection_locally:
.._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
You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to
access the collection:
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.
..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_collection_ansible_galaxy:
Upload using 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:
To upload the collection artifact with the ``ansible-galaxy`` command:
..code-block:: bash
..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
without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your
@ -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)
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.
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 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.
* 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
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:
You can use the ``--server`` command line argument to select an explicit Galaxy server in the ``server_list`` and
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``.
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
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
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
``[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.
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