[PR #11673/12af50cf backport][stable-12] docs: add Execution Environment guide (#11693)

docs: add Execution Environment guide (#11673)

* docs: add Execution Environment guide

Closes #2968
Closes #4512



* add to botmeta

* fix code block language

* Apply suggestions from code review



* Update section title for community.general EE metadata

* Apply suggestion from felixfontein



* Remove extraneous paragraph

* Apply suggestions from code review




* remove link to legacy documentation

* Update docs/docsite/rst/guide_ee.rst



---------




(cherry picked from commit 12af50cfb7)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Don Naro <dnaro@redhat.com>

.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:

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

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 <https://docs.ansible.com/projects/ansible/latest/getting_started_ee/index.html>`_
+(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 <https://docs.ansible.com/projects/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 <https://docs.ansible.com/ansible/latest/collections/community/general/>`_.
+
+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 <https://docs.ansible.com/projects/builder/en/latest/>`_ 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 <https://docs.ansible.com/projects/builder/en/latest/>`_
+    - `Building EEs with ansible-builder <https://ansible-builder.readthedocs.io/en/latest/definition/>`_
+    - `Issue #2968 — original request for EE requirements support <https://github.com/ansible-collections/community.general/issues/2968>`_
+    - `Issue #4512 — design discussion for EE support in community.general <https://github.com/ansible-collections/community.general/issues/4512>`_