diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 89507c2d45..cf33d051e9 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1570,6 +1570,8 @@ files: maintainers: russoz docs/docsite/rst/guide_deps.rst: maintainers: russoz + docs/docsite/rst/guide_ee.rst: + maintainers: russoz docs/docsite/rst/guide_iocage.rst: maintainers: russoz felixfontein docs/docsite/rst/guide_iocage_inventory.rst: diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml index 4594ab4c2d..b195542227 100644 --- a/docs/docsite/extra-docs.yml +++ b/docs/docsite/extra-docs.yml @@ -8,6 +8,9 @@ sections: toctree: - filter_guide - test_guide + - title: Deployment Guides + toctree: + - guide_ee - title: Technology Guides toctree: - guide_alicloud diff --git a/docs/docsite/rst/guide_ee.rst b/docs/docsite/rst/guide_ee.rst new file mode 100644 index 0000000000..02b417fb31 --- /dev/null +++ b/docs/docsite/rst/guide_ee.rst @@ -0,0 +1,114 @@ +.. + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later + +.. _ansible_collections.community.general.docsite.guide_ee: + +Execution Environment Guide +=========================== + +`Ansible Execution Environments `_ +(EEs) are container images that bundle ansible-core, collections, and their Python and system dependencies. +They are the standard runtime for Red Hat Ansible Automation Platform and AWX, replacing the older virtualenv model. +They can also be used outside of RHAAP and AWX by using `ansible-navigator `__, or by using ansible-runner directly. + +What runs in the EE +^^^^^^^^^^^^^^^^^^^ + +Only **controller-side plugins** run inside the EE. Their Python and system dependencies must be installed there. +This includes: lookup plugins, inventory plugins, callback plugins, connection plugins, become plugins, and filter plugins. + +Modules run on the managed nodes and are transferred there at runtime — their dependencies must be present on the +target, not in the EE. + +.. note:: + + Modules delegated to ``localhost`` (for example, those that interact with a remote API) are an exception: + they run on the controller and their dependencies must therefore be available in the EE. + +Why community.general does not provide EE metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``community.general`` ships dozens of controller-side plugins covering a very broad range of technologies. +Bundling the dependencies for all of them into a single EE image would almost certainly create irreconcilable +conflicts — both within the collection and with other collections or tools (such as ``ansible-lint``) that +share the same image. + +For that reason, ``community.general`` does **not** provide Python or system package dependency metadata. +Users are expected to build purpose-built, minimal EEs containing only the dependencies +required by the specific plugins they actually use. + +Finding the dependencies you need +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every plugin that has external dependencies documents them in its ``requirements`` field. +You can inspect those with ``ansible-doc``: + +.. code-block:: shell + + $ ansible-doc -t lookup community.general.some_lookup | grep -A 10 "REQUIREMENTS" + +Or browse the plugin's documentation page on `docs.ansible.com `_. + +For example, a lookup plugin that wraps an external service might list: + +.. code-block:: yaml + + requirements: + - some-python-library >= 1.2 + +An inventory plugin backed by a REST API might list: + +.. code-block:: yaml + + requirements: + - requests + - some-sdk + +These are the packages you need to add to your EE. + +Building a minimal EE with ansible-builder +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`ansible-builder `_ is the standard tool for creating EEs. + +Install it with: + +.. code-block:: shell + + $ pip install ansible-builder + +Create an ``execution-environment.yml`` **in your own project** — not inside ``community.general`` — +that includes only the dependencies needed for the plugins you use: + +.. code-block:: yaml + + version: 3 + + dependencies: + galaxy: + collections: + - name: community.general + python: + - some-python-library>=1.2 + - requests + system: + - libxml2-devel [platform:rpm] + + images: + base_image: + name: ghcr.io/ansible/community-ee-base:latest + +Then build the image: + +.. code-block:: shell + + $ ansible-builder build -t my-custom-ee:latest + +.. seealso:: + + - `ansible-builder documentation `_ + - `Building EEs with ansible-builder `_ + - `Issue #2968 — original request for EE requirements support `_ + - `Issue #4512 — design discussion for EE support in community.general `_