mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-03-26 21:33:12 +00:00
12af50cfb7
* docs: add Execution Environment guide Closes #2968 Closes #4512 Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> * add to botmeta * fix code block language * Apply suggestions from code review Co-authored-by: Felix Fontein <felix@fontein.de> * Update section title for community.general EE metadata * Apply suggestion from felixfontein Co-authored-by: Felix Fontein <felix@fontein.de> * Remove extraneous paragraph * Apply suggestions from code review Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: Don Naro <dnaro@redhat.com> * remove link to legacy documentation * Update docs/docsite/rst/guide_ee.rst Co-authored-by: Don Naro <dnaro@redhat.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>
115 lines
4.2 KiB
ReStructuredText
115 lines
4.2 KiB
ReStructuredText
..
|
|
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>`_
|