diff options
Diffstat (limited to '')
-rw-r--r-- | docs/docsite/rst/shared_snippets/installing_collections.txt | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt new file mode 100644 index 0000000..23f5c3e --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_collections.txt @@ -0,0 +1,72 @@ + + +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: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection + +To upgrade a collection to the latest available version from the Galaxy server you can use the ``--upgrade`` option: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection --upgrade + +You can also directly use the tarball from your build: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections + +You can build and install a collection from a local source directory. The ``ansible-galaxy`` utility builds the collection using the ``MANIFEST.json`` or ``galaxy.yml`` +metadata in the directory. + +.. code-block:: bash + + ansible-galaxy collection install /path/to/collection -p ./collections + +You can also install multiple collections in a namespace directory. + +.. code-block:: text + + ns/ + ├── collection1/ + │ ├── MANIFEST.json + │ └── plugins/ + └── collection2/ + ├── galaxy.yml + └── plugins/ + +.. code-block:: bash + + ansible-galaxy collection install /path/to/ns -p ./collections + +.. note:: + The install command automatically appends the path ``ansible_collections`` to the one specified with the ``-p`` option unless the + parent directory is already in a folder called ``ansible_collections``. + + +When using the ``-p`` option to specify the install path, use one of the values configured in :ref:`COLLECTIONS_PATHS`, as this is +where Ansible itself will expect to find collections. If you don't specify a path, ``ansible-galaxy collection install`` installs +the collection to the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections`` + +You can also keep a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure. + +.. code-block:: text + + ./ + ├── play.yml + ├── collections/ + │ └── ansible_collections/ + │ └── my_namespace/ + │ └── my_collection/<collection structure lives here> + + +See :ref:`collection_structure` for details on the collection directory structure. + |