From 8a754e0858d922e955e71b253c139e071ecec432 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 18:04:21 +0200 Subject: Adding upstream version 2.14.3. Signed-off-by: Daniel Baumann --- .../collections_guide/collections_installing.rst | 126 +++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/docsite/rst/collections_guide/collections_installing.rst (limited to 'docs/docsite/rst/collections_guide/collections_installing.rst') diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst new file mode 100644 index 0000000..6ee446a --- /dev/null +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -0,0 +1,126 @@ +.. _collections_installing: + +Installing collections +====================== + +.. note:: + + If you install a collection manually as described in this paragraph, the collection will not be upgraded automatically when you upgrade the ``ansible`` package or ``ansible-core``. + +Installing collections with ``ansible-galaxy`` +---------------------------------------------- + +.. include:: ../shared_snippets/installing_collections.txt + +.. _installing_signed_collections: + +Installing collections with signature verification +--------------------------------------------------- + +If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the ``MANIFEST.json`` before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing which servers support collection signing. + +To use signature verification for signed collections: + +1. :ref:`Configured a GnuPG keyring ` for ``ansible-galaxy``, or provide the path to the keyring with the ``--keyring`` option when you install the signed collection. + + +2. Import the public key from the distribution server into that keyring. + + .. code-block:: bash + + gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc + + +3. Verify the signature when you install the collection. + + .. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection --keyring ~/.ansible/pubring.kbx + + The ``--keyring`` option is not necessary if you have :ref:`configured a GnuPG keyring `. + +4. Optionally, verify the signature at any point after installation to prove the collection has not been tampered with. See :ref:`verify_signed_collections` for details. + + +You can also include signatures in addition to those provided by the distribution server. Use the ``--signature`` option to verify the collection's ``MANIFEST.json`` with these additional signatures. Supplemental signatures should be provided as URIs. + +.. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx + +GnuPG verification only occurs for collections installed from a distribution server. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files. + +You can also include additional signatures in the collection ``requirements.yml`` file under the ``signatures`` key. + +.. code-block:: yaml + + # requirements.yml + collections: + - name: ns.coll + version: 1.0.0 + signatures: + - https://examplehost.com/detached_signature.asc + - file:///path/to/local/detached_signature.asc + +See :ref:`collection requirements file ` for details on how to install collections with this file. + +By default, verification is considered successful if a minimum of 1 signature successfully verifies the collection. The number of required signatures can be configured with ``--required-valid-signature-count`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. All signatures can be required by setting the option to ``all``. To fail signature verification if no valid signatures are found, prepend the value with ``+``, such as ``+all`` or ``+1``. + +.. code-block:: bash + + export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx + export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=2 + ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc + +Certain GnuPG errors can be ignored with ``--ignore-signature-status-code`` or :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`. :ref:`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT` should be a list, and ``--ignore-signature-status-code`` can be provided multiple times to ignore multiple additional error status codes. + +This example requires any signatures provided by the distribution server to verify the collection except if they fail due to NO_PUBKEY: + +.. code-block:: bash + + export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx + export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=all + ansible-galaxy collection install my_namespace.my_collection --ignore-signature-status-code NO_PUBKEY + +If verification fails for the example above, only errors other than NO_PUBKEY will be displayed. + +If verification is unsuccessful, the collection will not be installed. GnuPG signature verification can be disabled with ``--disable-gpg-verify`` or by configuring :ref:`GALAXY_DISABLE_GPG_VERIFY`. + + +.. _collections_older_version: + +Installing an older version of a collection +------------------------------------------- + +.. include:: ../shared_snippets/installing_older_collection.txt + +.. _collection_requirements_file: + +Install multiple collections with a requirements file +----------------------------------------------------- + +.. include:: ../shared_snippets/installing_multiple_collections.txt + +.. _collection_offline_download: + +Downloading a collection for offline use +----------------------------------------- + +.. include:: ../shared_snippets/download_tarball_collections.txt + +Installing a collection from source files +----------------------------------------- + +.. include:: ../shared_snippets/installing_collections_file.rst + +Installing a collection from a git repository +--------------------------------------------- + +.. include:: ../shared_snippets/installing_collections_git_repo.txt + +.. _galaxy_server_config: + +Configuring the ``ansible-galaxy`` client +------------------------------------------ + +.. include:: ../shared_snippets/galaxy_server_list.txt \ No newline at end of file -- cgit v1.2.3