diff options
Diffstat (limited to 'docs/docsite/rst/shared_snippets/installing_multiple_collections.txt')
-rw-r--r-- | docs/docsite/rst/shared_snippets/installing_multiple_collections.txt | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt new file mode 100644 index 0000000..a1b18b5 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt @@ -0,0 +1,77 @@ + +You can set up a ``requirements.yml`` file to install multiple collections in one command. This file is a YAML file in the format: + +.. code-block:: yaml+jinja + + --- + collections: + # With just the collection name + - my_namespace.my_collection + + # With the collection name, version, and source options + - name: my_namespace.my_other_collection + version: ">=1.2.0" # Version range identifiers (default: ``*``) + source: ... # The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline) + +You can specify the following keys for each collection entry: + + * ``name`` + * ``version`` + * ``signatures`` + * ``source`` + * ``type`` + +The ``version`` key uses the same range identifier format documented in :ref:`collections_older_version`. + +The ``signatures`` key accepts a list of signature sources that are used to supplement those found on the Galaxy server during collection installation and ``ansible-galaxy collection verify``. Signature sources should be URIs that contain the detached signature. The ``--keyring`` CLI option must be provided if signatures are specified. + +Signatures are only used to verify collections on Galaxy servers. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files. + +.. code-block:: yaml + + collections: + - name: namespace.name + version: 1.0.0 + type: galaxy + signatures: + - https://examplehost.com/detached_signature.asc + - file:///path/to/local/detached_signature.asc + +The ``type`` key can be set to ``file``, ``galaxy``, ``git``, ``url``, ``dir``, or ``subdirs``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection. + +When you install a collection with ``type: git``, the ``version`` key can refer to a branch or to a `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ object (commit or tag). For example: + +.. code-block:: yaml + + collections: + - name: https://github.com/organization/repo_name.git + type: git + version: devel + +You can also add roles to a ``requirements.yml`` file, under the ``roles`` key. The values follow the same format as a requirements file used in older Ansible releases. + +.. code-block:: yaml + + --- + roles: + # Install a role from Ansible Galaxy. + - name: geerlingguy.java + version: "1.9.6" # note that ranges are not supported for roles + + + collections: + # Install a collection from Ansible Galaxy. + - name: geerlingguy.php_roles + version: ">=0.9.3" + source: https://galaxy.ansible.com + +To install both roles and collections at the same time with one command, run the following: + +.. code-block:: bash + + $ ansible-galaxy install -r requirements.yml + +Running ``ansible-galaxy collection install -r`` or ``ansible-galaxy role install -r`` will only install collections, or roles respectively. + +.. note:: + Installing both roles and collections from the same requirements file will not work when specifying a custom collection or role install path. In this scenario the collections will be skipped and the command will process each like ``ansible-galaxy role install`` would. |