Add EE docs

docs/docsite/rst/ansible_index.rst

@@ -29,6 +29,7 @@ Ansible releases a new major release approximately twice a year. The core applic
    :caption: Ansible getting started
 
    getting_started/index
+   getting_started_ee/index
 
 .. toctree::
    :maxdepth: 2

docs/docsite/rst/getting_started_ee/build_execution_environment.rst

@@ -0,0 +1,61 @@
+.. _building_execution_environments:
+
+Building your first EE
+======================
+
+We are going to build an EE that represents an Ansible control node containing standard packages such as ``ansible-core`` and Python in addition to
+an Ansible collection (``community.postgresql``) and its dependency (the ``psycopg2-binary`` Python connector).
+
+To build your first EE:
+
+1. Create a project folder on your filesystem.
+
+.. code-block:: bash
+
+  mkdir my_first_ee && cd my_first_ee
+
+2. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image.
+
+.. code-block:: yaml
+
+  cat > execution-environment.yml<<EOF
+  ---
+  version: 3
+
+  dependencies:
+    galaxy:
+      collections:
+      - name: community.postgresql
+  EOF
+
+.. note::
+
+  The ``psycopg2-binary`` Python package is included in the ``requirements.txt`` file for the collection.
+  For collections that do not include ``requirements.txt`` files, you need to specify Python dependencies explicitly.
+  See the `Ansible Builder documentation <https://ansible-builder.readthedocs.io/en/stable/definition/>`_ for details.
+
+3. Build a EE container image called ``postgresql_ee``. If you use docker, add the ``--container-runtime docker`` argument.
+
+.. code-block:: bash
+
+  ansible-builder build --tag postgresql_ee
+
+4. List container images to verify that you built it successfully.
+
+.. code-block:: bash
+
+  podman image list
+
+  localhost/postgresql_ee          latest      2e866777269b  6 minutes ago  1.11 GB
+
+You can verify the image you created by inspecting the ``Containerfile`` or ``Dockerfile`` in the ``context`` directory to view its configuration.
+
+.. code-block:: bash
+
+  less context/Containerfile
+
+You can also use Ansible Navigator to view detailed information about the image.
+
+Run the ``ansible-navigator`` command, type ``:images`` in the TUI, and then choose ``postgresql_ee``.
+
+Proceed to :ref:`Running your EE<running_execution_environments>` and test the EE you just built.

docs/docsite/rst/getting_started_ee/index.rst

@@ -0,0 +1,33 @@
+:orphan:
+
+.. _getting_started_ee_index:
+
+*******************************************
+Getting started with Execution Environments
+*******************************************
+
+You can run Ansible automation in containers, like any other modern software application.
+Ansible uses container images known as execution environments (EE) that act as control nodes.
+
+An execution environment image contains the following packages as standard:
+
+* ``ansible-core``
+* ``ansible-runner``
+* Python
+* Ansible content dependencies
+
+In addition to the standard packages, an EE can also contain:
+
+* one or more Ansible collections and their dependencies
+* other custom components
+
+This getting started guide shows you how to build and test a simple execution environment.
+The resulting container image represents an Ansible control node that contains the standard EE packages plus the ``community.postgresql`` collection and the ``psycopg2-binary`` Python package.
+
+.. toctree::
+   :maxdepth: 1
+
+   introduction
+   setup_environment
+   build_execution_environment
+   run_execution_environment

docs/docsite/rst/getting_started_ee/introduction.rst

@@ -0,0 +1,64 @@
+.. _introduction_execution_environments:
+
+Introduction to execution environments
+======================================
+
+Ansible execution environments aim to resolve complexity issues and provide all the benefits you can get from containerization.
+
+Reducing complexity
+-------------------
+
+There are three main areas where EEs can reduce complexity: software dependencies, portability, and content separation.
+
+Dependencies
+^^^^^^^^^^^^
+
+Software applications typically have dependencies, and Ansible is no exception. 
+These dependencies can include software libraries, configuration files or other services, to name a few.
+
+Traditionally, administrators install application dependencies on top of an operating system using packaging management tools such as RPM or Python-pip.
+
+The major drawback of such an approach is that an application might require versions of dependencies different from those provided by default.
+
+For Ansible, a typical installation consists of ``ansible-core`` and a set of Ansible collections.
+Many of them have dependencies for the plugins, modules, roles and playbooks they provide.
+
+The Ansible collections can depend on the following pieces of software and their versions:
+
+* ``ansible-core``
+* Python
+* Python packages
+* System packages
+* Other Ansible collections
+
+The dependencies have to be installed and sometimes can conflict with each other.
+
+One way to **partially** resolve dependency issue is to use Python virtual environments on  Ansible control nodes.
+However, applied to Ansible, virtual environments have drawbacks and natural limitations.
+
+Portability
+^^^^^^^^^^^
+
+An Ansible user writes content for Ansible locally and wants to leverage the container technology to make their automation runtimes portable, shareable and easily deployable to testing and production environments.
+
+Content separation
+^^^^^^^^^^^^^^^^^^
+
+In situations when there is an Ansible control node or a tool such as Ansible AWX/Controller used by several users, they might want separate their content to avoid configuration and dependency conflicts.
+
+.. _ansible_tooling_for_ee:
+
+Ansible tooling for EEs
+-----------------------
+
+Projects in the Ansible ecosystem also provide lots of tooling that you can use with EEs, such as:
+
+* `Ansible Builder <https://ansible-builder.readthedocs.io/en/stable/>`_
+* `Ansible Navigator <https://ansible-navigator.readthedocs.io/>`_
+* `Ansible AWX <https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html#use-an-execution-environment-in-jobs>`_
+* `Automation controller <https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html#use-an-execution-environment-in-jobs>`_
+* `Ansible Runner <https://ansible-runner.readthedocs.io/en/stable/>`_
+* VS Code `Ansible <https://marketplace.visualstudio.com/items?itemName=redhat.ansible>`_ and `Dev Containers <https://code.visualstudio.com/docs/devcontainers/containers>`_ extensions
+
+Ready to get started with EEs?
+Proceed to :ref:`Setting up your environment<setting_up_environment>`.

docs/docsite/rst/getting_started_ee/run_execution_environment.rst

@@ -0,0 +1,94 @@
+.. _running_execution_environments:
+
+Running your EE
+===============
+
+You can run your EE on the command line against ``localhost`` or a remote target
+using ``ansible-navigator``.
+
+.. note::
+
+  There are other tools besides ``ansible-navigator`` you can run EEs with.
+
+Run against localhost
+---------------------
+
+1. Create a ``test_localhost.yml`` playbook.
+
+.. code-block:: yaml
+
+  cat > test_localhost.yml<<EOF
+  ---
+  - hosts: localhost
+    become: yes
+    gather_facts: yes
+    tasks:
+    - name: Print facts
+      ansible.builtin.debug:
+        msg: '{{ ansible_facts }}'
+  EOF
+
+2. Run the playbook inside the ``postgresql_ee`` EE.
+
+.. code-block:: bash
+
+  ansible-navigator run test_localhost.yml --execution-environment-image postgresql_ee --mode stdout --pull-policy missing
+
+You may notice the facts being gathered are about the container and not the developer machine.
+This is because the ansible playbook was run inside the container.
+
+Run against a remote target
+---------------------------
+
+In this example, you execute a playbook inside the ``postgresql_ee`` EE against a remote host machine.
+Before you start, ensure you have the following:
+
+* At least one IP address or resolvable hostname for a remote target.
+* Valid credentials for the remote host.
+* A user with ``sudo`` permissions on the remote host.
+
+1. Create a directory for inventory files.
+
+.. code-block:: yaml
+
+  mkdir inventory
+
+2. Create the ``hosts.yml`` inventory file in the ``inventory`` directory.
+
+.. code-block:: yaml
+
+  cat > inventory/hosts.yml<<EOF
+  ---
+  all:
+    hosts:
+      192.168.0.2  # Replace with the IP of your target host
+  EOF
+
+3. Create a ``test_remote.yml`` playbook.
+
+.. code-block:: yaml
+
+  cat > test_remote.yml<<EOF
+  ---
+  - hosts: all
+    become: yes
+    gather_facts: yes
+    tasks:
+    - name: Print facts
+      ansible.builtin.debug:
+        msg: '{{ ansible_facts }}'
+  EOF
+
+4. Run the playbook inside the ``postgresql_ee`` EE. Replace ``student`` with the appropriate user name.
+
+.. code-block:: bash
+
+  ansible-navigator run test_remote.yml -i inventory --execution-environment-image postgresql_ee:latest --mode stdout --pull-policy missing --enable-prompts -u student -k -K
+
+What to read next
+-----------------
+
+* More about the `EE definition file <https://ansible-builder.readthedocs.io/en/stable/definition/>`_ and available options.
+* `Ansible Builder CLI usage <https://ansible-builder.readthedocs.io/en/stable/usage/>`_.
+* `Ansible Navigator official documentation <https://ansible-navigator.readthedocs.io/>`_.
+* :ref:`The list of tools for EE<ansible_tooling_for_ee>`

docs/docsite/rst/getting_started_ee/setup_environment.rst

@@ -0,0 +1,42 @@
+.. _setting_up_environment:
+
+Setting up your environment
+===========================
+
+Complete the following steps to set up a local environment for your first execution environment:
+
+1. Ensure the following packages are installed on your system:
+
+* ``podman`` or ``docker``
+* ``python3``
+
+If you use the DNF package manager, install these prerequisites as follows:
+
+.. code-block:: bash
+
+  sudo dnf install -y podman python3
+
+2. Install ``ansible-navigator``:
+
+.. code-block:: bash
+
+  pip3 install ansible-navigator
+
+Installing ``ansible-navigator`` lets you run EEs on the command line.
+It includes the ``ansible-builder`` package to build EEs.
+
+If you want to build EEs without testing, install only ``ansible-builder``:
+
+.. code-block:: bash
+
+  pip3 install ansible-builder
+
+3. Verify your environment with the following commands:
+
+.. code-block:: bash
+
+  ansible-navigator --version
+  ansible-builder --version
+
+Ready to build your first EE?
+Proceed to :ref:`Building your first EE<building_execution_environments>`

docs/docsite/sphinx_conf/core_conf.py

@@ -128,6 +128,11 @@
     'dev_guide/platforms/ovirt_dev_guide.rst',
     'dev_guide/platforms/vmware_guidelines.rst',
     'dev_guide/platforms/vmware_rest_guidelines.rst',
+    'getting_started_ee/build_execution_environment.rst',
+    'getting_started_ee/index.rst',
+    'getting_started_ee/introduction.rst',
+    'getting_started_ee/run_execution_environment.rst',
+    'getting_started_ee/setup_environment.rst',
     'porting_guides/porting_guides.rst',
     'porting_guides/porting_guide_[1-9]*',
     'roadmap/index.rst',

docs/docsite/sphinx_conf/core_lang_conf.py

@@ -128,6 +128,11 @@
     'dev_guide/platforms/ovirt_dev_guide.rst',
     'dev_guide/platforms/vmware_guidelines.rst',
     'dev_guide/platforms/vmware_rest_guidelines.rst',
+    'getting_started_ee/build_execution_environment.rst',
+    'getting_started_ee/index.rst',
+    'getting_started_ee/introduction.rst',
+    'getting_started_ee/run_execution_environment.rst',
+    'getting_started_ee/setup_environment.rst',
     'porting_guides/porting_guides.rst',
     'porting_guides/porting_guide_[1-9]*',
     'roadmap/index.rst',