diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
commit | 8a754e0858d922e955e71b253c139e071ecec432 (patch) | |
tree | 527d16e74bfd1840c85efd675fdecad056c54107 /docs/docsite/rst/shared_snippets/galaxy_server_list.txt | |
parent | Initial commit. (diff) | |
download | ansible-core-upstream.tar.xz ansible-core-upstream.zip |
Adding upstream version 2.14.3.upstream/2.14.3upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/docsite/rst/shared_snippets/galaxy_server_list.txt')
-rw-r--r-- | docs/docsite/rst/shared_snippets/galaxy_server_list.txt | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt new file mode 100644 index 0000000..9991d85 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt @@ -0,0 +1,78 @@ + + +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 use either option below to configure ``ansible-galaxy collection`` to use other servers (such as 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. + +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. Go to https://galaxy.ansible.com/me/preferences and click :guilabel:`Show API key`. + +.. note:: + 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. + + +The following example shows how to configure multiple servers: + +.. code-block:: ini + + [galaxy] + server_list = my_org_hub, release_galaxy, test_galaxy, my_galaxy_ng + + [galaxy_server.my_org_hub] + url=https://automation.my_org/ + username=my_user + password=my_pass + + [galaxy_server.release_galaxy] + url=https://galaxy.ansible.com/ + token=my_token + + [galaxy_server.test_galaxy] + url=https://galaxy-dev.ansible.com/ + token=my_test_token + + [galaxy_server.my_galaxy_ng] + url=http://my_galaxy_ng:8000/api/automation-hub/ + auth_url=http://my_keycloak:8080/auth/realms/myco/protocol/openid-connect/token + client_id=galaxy-ng + token=my_keycloak_access_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 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, 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. 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 conjunction with ``username``, for basic authentication. +* ``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO authentication (for example, galaxyNG). Mutually exclusive with ``username``. Requires ``token``. +* ``validate_certs``: Whether or not to verify TLS certificates for the Galaxy server. This defaults to True unless the ``--ignore-certs`` option is provided or ``GALAXY_IGNORE_CERTS`` is configured to True. +* ``client_id``: The Keycloak token's client_id to use for authentication. Requires ``auth_url`` and ``token``. The default ``client_id`` is cloud-services to work with Red Hat SSO. + +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 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:: + ``ansible-galaxy`` can seek out dependencies on other configured Galaxy instances to support the use case where a collection can depend on a collection from another Galaxy instance. |