From 730ce7646370b30f181d552f778d3f42579e93af Mon Sep 17 00:00:00 2001 From: Devids10 <129358723+Devids10@users.noreply.github.com> Date: Tue, 30 Apr 2024 23:19:00 +0200 Subject: [PATCH] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 (#1315) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: remove the reused snippet * feat: add new shared_snippet and add description of local installation next to playbooks * feat: add new section for installing collections locally * fix: fix nox check error * fix: remove shared txt files, add them to their included space, add an anchor to the new section * fix: comments from the pull request --------- Co-authored-by: Dávid Németh (cherry picked from commit ba04139aaa7a178eed1ccda037f962bea1dd5594) --- .../collections_installing.rst | 84 ++++++++++++++++++- .../installing_collections.txt | 72 ---------------- 2 files changed, 83 insertions(+), 73 deletions(-) delete mode 100644 docs/docsite/rst/shared_snippets/installing_collections.txt diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 50366b41928..313f754e5aa 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -16,7 +16,62 @@ See `Getting started with Execution Environments ` 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`` .. _installing_signed_collections: @@ -114,6 +169,33 @@ Downloading a collection for offline use .. include:: ../shared_snippets/download_tarball_collections.txt +.. _collection_local_install: + +Installing collections adjacent to playbooks +-------------------------------------------- + +You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on AWX. + +Using locally installed collections adjacent to playbooks has some benefits, such as: +* Ensuring that all users of the project use the same collection version. +* Using self-contained projects makes it easy to move across different environments. Increased portability also reduces overhead when setting up new environments. This is a benefit when deploying Ansible playbooks in cloud environments. +* Managing collections locally lets you version them along with your playbooks. +* Installing collections locally isolates them from global installations in environments that have multiple projects. + +Here is an example of keeping 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/ + + +See :ref:`collection_structure` for details on the collection directory structure. + Installing a collection from source files ----------------------------------------- diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt deleted file mode 100644 index e408ccf113b..00000000000 --- a/docs/docsite/rst/shared_snippets/installing_collections.txt +++ /dev/null @@ -1,72 +0,0 @@ - - -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. -By default, Ansible installs the collection in ``~/.ansible/collections`` under the ``ansible_collections`` directory. - -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: - -.. 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/ - - -See :ref:`collection_structure` for details on the collection directory structure. -