diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index adff246163e..f90369e7375 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -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 `_ page and click :guilabel:`API token`. +* For Galaxy, go to the `Galaxy profile 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 `. + +.. code-block:: bash + + ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --api-key= + + +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 `_ 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: diff --git a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt index 29797b97460..5ec3fdb1551 100644 --- a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt +++ b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt @@ -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,10 +13,11 @@ 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 ` 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: #. Set the ``auth_url`` option for each server name. @@ -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 diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt index 7d8ad2c0cfa..fc38c6253fa 100644 --- a/docs/docsite/rst/shared_snippets/installing_collections.txt +++ b/docs/docsite/rst/shared_snippets/installing_collections.txt @@ -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 ` 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 ` if you are using any other Galaxy server, such as Red Hat Automation Hub. To install a collection hosted in Galaxy: