Clarify how to use the Galaxy token (#65961)
* DOCS: clarify how to use the Galaxy token, with info for installs and api-key
This commit is contained in:
Sandra McCann
Alicia Cozine
parent
e19b94f43b
commit
0ca79a4234
3 changed files with 63 additions and 23 deletions
|
|
@ -310,13 +310,48 @@ You can publish collections to Galaxy using the ``ansible-galaxy collection publ
|
|||
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 upload your collection to Galaxy, you must first obtain an API token (``--api-key`` in the ``ansible-galaxy`` CLI command or ``token`` in the :file:`ansible.cfg` file under the ``galaxy_server`` section). 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 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.
|
||||
|
||||
Storing or using your API token
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once you have retrieved your API token, you can store or use the token for collections in two ways:
|
||||
|
||||
* Pass the token to the ``ansible-galaxy`` command using the ``--api-key``.
|
||||
* Specify the token within a Galaxy server list in your :file:`ansible.cfg` file.
|
||||
|
||||
Using the ``api-key``
|
||||
.....................
|
||||
|
||||
You can use the ``--api-key`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --api-key=<key goes here>
|
||||
|
||||
|
||||
Specify the token within a Galaxy server list
|
||||
.............................................
|
||||
|
||||
With this option, you configure one or more servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
|
||||
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[galaxy]
|
||||
server_list = release_galaxy
|
||||
|
||||
[galaxy_server.release_galaxy]
|
||||
url=https://galaxy.ansible.com/
|
||||
token=my_token
|
||||
|
||||
See :ref:`galaxy_server_config` for complete details.
|
||||
|
||||
.. _upload_collection_ansible_galaxy:
|
||||
|
||||
Upload using ansible-galaxy
|
||||
|
|
@ -329,14 +364,17 @@ To upload the collection artifact with the ``ansible-galaxy`` command:
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --api-key=SECRET
|
||||
ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz
|
||||
|
||||
The above command triggers an import process, just as if you uploaded the collection through the Galaxy website.
|
||||
.. note::
|
||||
|
||||
The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
|
||||
|
||||
The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website.
|
||||
The command waits until the import process completes before reporting the status back. If you wish to continue
|
||||
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 the Galaxy server to protect your content. See :ref:`galaxy_get_token` for details.
|
||||
|
||||
.. _upload_collection_galaxy:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
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 can configure this to use other servers (such as Red Hat Automation Hub or a custom Galaxy server) as follows:
|
||||
You can use either option below to configure ``ansible-galaxy collection`` to use other servers (such as Red Hat Automation Hub or a custom Galaxy server):
|
||||
|
||||
* 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.
|
||||
|
|
@ -13,9 +13,10 @@ 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.
|
||||
#. Optionally, set the API token for each server name. See :ref:`API token <collections_installing>` for details.
|
||||
|
||||
.. note::
|
||||
The ``url`` option for each server name must end with a forward slash ``/``.
|
||||
The ``url`` option for each server name must end with a forward slash ``/``. If you do not set the API token in your Galaxy server list, use the ``--api-key`` argument to pass in the token to the ``ansible-galaxy collection publish`` command.
|
||||
|
||||
For Automation Hub, you additionally need to:
|
||||
|
||||
|
|
@ -32,7 +33,6 @@ The following example shows how to configure multiple servers:
|
|||
[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
|
||||
|
||||
[galaxy_server.my_org_hub]
|
||||
|
|
@ -50,30 +50,30 @@ The following example shows how to configure multiple servers:
|
|||
|
||||
.. note::
|
||||
You can use the ``--server`` command line argument to select an explicit Galaxy server in the ``server_list`` and
|
||||
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``.
|
||||
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 you cannot use the ``--api-key`` argument for any of the predefined servers. You can only use the ``api_key`` argument if you did not define a server list or if you specify a URL in the
|
||||
``--server`` argument.
|
||||
|
||||
**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. ``automation_hub`` first, then ``my_org_hub``, ``release_galaxy``, and
|
||||
collection, the install process will search in that order, for example, ``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:
|
||||
|
||||
* ``url``: The URL of the galaxy instance to connect to, this is required.
|
||||
* ``token``: A token key to use for authentication against the Galaxy instance, this is mutually exclusive with ``username``
|
||||
* ``username``: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive with ``token``
|
||||
* ``password``: The password to use for basic authentication
|
||||
* ``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO auth (Automation Hub for ex). This is mutually exclusive with ``username``. ``auth_url`` requires ``token``.
|
||||
* ``url``: The URL of the Galaxy instance to connect to. Required.
|
||||
* ``token``: An API token key to use for authentication against the Galaxy instance. Mutually exclusive with ``username``.
|
||||
* ``username``: The username to use for basic authentication against the Galaxy instance. Mutually exclusive with ``token``.
|
||||
* ``password``: The password to use, in conjuction with ``username``, for basic authentication.
|
||||
* ``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO authentication (for example, Automation Hub). Mutually exclusive with ``username``. Requires ``token``.
|
||||
|
||||
As well as being defined in the ``ansible.cfg`` file, these server options can be defined as an environment variable.
|
||||
As well as defining these server options in the ``ansible.cfg`` file, you can also define them as environment variables.
|
||||
The environment variable is in the form ``ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}`` where ``{{ id }}`` is the upper
|
||||
case form of the server identifier and ``{{ key }}`` is the key to define. For example I can define ``token`` for
|
||||
``release_galaxy`` by setting ``ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token``.
|
||||
|
||||
For operations where only one Galaxy server is used, i.e. ``publish``, ``info``, ``login`` then the first entry in the
|
||||
``server_list`` is used unless an explicit server was passed in as a command line argument.
|
||||
For operations that use only one Galaxy server (for example, the ``publish``, ``info``, or ``install`` commands). the ``ansible-galaxy collection`` command uses the first entry in the
|
||||
``server_list``, unless you pass in an explicit server with the ``--server`` argument.
|
||||
|
||||
.. note::
|
||||
Once a collection is found, any of its requirements are only searched within the same Galaxy instance as the parent
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
|
||||
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).
|
||||
By default, ``ansible-galaxy collection install`` 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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue