execution environments: add EE overview page

execution_environments/building_and_testing_ee_tutorial.rst

@@ -0,0 +1,202 @@
+.. _build_and_test_ee:
+
+*******************************************
+Building and testing execution environments
+*******************************************
+
+This tutorial shows you how to build and test a simple execution environment.
+
+For general information about execution environments, see the :ref:`Ansible execution environments overview<ee_overview>` document.
+
+.. _setting_up_environment:
+
+Setting up your environment
+===========================
+
+Ensure the following packages are installed on your system:
+
+* podman or docker
+* python3
+
+If you use the DNF as a package manager, you can install them as follows:
+
+.. code-block:: bash
+
+  sudo dnf install -y podman python3
+
+Complete the following steps to set up a local environment for your first execution environment:
+
+1. Upgrade the `pip` package manager and install `ansible-navigator`.
+
+.. code-block:: bash
+
+  python3 -m pip install --upgrade pip ansible-navigator
+
+Installing `ansible-navigator` lets you run EEs.
+It includes the `ansible-builder` package to build EEs.
+
+You can verify your environment with the following commands:
+
+.. code-block:: bash
+
+  ansible-navigator --version
+  ansible-builder --version
+
+.. _build_first_ee:
+
+Building your first EE
+======================
+
+We are going to build an EE containing, in addition to standard packages like ansible-core and Python,
+an Ansible collection (``community.postgresql``) and its dependency (the ``psycopg2-binary`` Python connector).
+
+The resulting image represents an :ref:`Ansible control node<terminology>` that contains:
+
+* Python
+* ansible-core
+* ansible-runner
+* the community.postgresql collection
+* the psycopg2-binary Python package
+
+To build your first ee, do the following:
+
+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.
+
+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.
+
+1. Run ``ansible-navigator``.
+2. Type ``:images`` in the TUI and then choose ``postgresql_ee``.
+
+Proceed to :ref:`Running your EE in command line<run_first_ee>` and test the EE you have just created.
+
+.. _run_first_ee:
+
+Running your EE in command line
+===============================
+
+Here, we will test the EE you created in the :ref:`Building your first EE<build_first_ee>` section against the localhost and a remote target.
+
+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 hostname for a remote target.
+* Valid credentials for the remote host.
+* Root or superuser 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.0.2.0  # Replace with the IP of a 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/>`_.

execution_environments/execution_environments_overview.rst

@@ -0,0 +1,108 @@
+.. _ee_overview:
+
+***************************************
+Ansible execution environments overview
+***************************************
+
+.. contents::
+   :local:
+
+.. _terminology:
+
+Terminology
+===========
+
+Notions used in this document:
+
+* **ansible-core**: you install it using ``pip install ansible-core``; includes command-line tools such as ``ansible-playbook`` and ``ansible-galaxy``, the Ansible language and a set of `builtin modules and plugins <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html>`_.
+* **Ansible collections**: a format in which Ansible content is distributed that can contain playbooks, roles, modules and plugins.
+* **Ansible package**: you install it using ``pip install ansible`` or an OS distribution package manager; it provides ansible-core and a big set of Ansible collections in the *batteries included* manner.
+* **Ansible**: in the context of this document, is the Ansible package or ``ansible-core`` plus a set of collections installed on the Ansible control node.
+* **Ansible control node**: the machine from which you run Ansible.
+* **Container Runtime**: it is what you typically use ``podman`` or ``docker`` for running containers.
+* **Execution environment**: is a container image providing a runtime environment for Ansible control node.
+
+What is an execution environment?
+=================================
+
+Ansible, as a software application, can run in a container, thus, it can benefit from containerization the same as most other applications.
+
+The Ansible automation execution environment (hereinafter, execution environment or EE) is a container image serving as Ansible control node.
+
+The EE image contains:
+
+* ansible-core
+* ansible-runner
+* none or more Ansible collections
+* Python
+* Python and system dependencies
+* custom user needs
+
+Tools you can use EEs with
+-------------------------
+
+You can use EEs with:
+
+* `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
+
+.. _ee_rationale:
+
+Why execution environments were introduced
+==========================================
+
+The Ansible execution environments were introduced to resolve the following issues
+and provide all benefits you can get from using containerization.
+
+Dependencies
+------------
+
+Software applications typically have dependencies.
+It can be software libraries, configuration files or other services, to name a few, and Ansible,
+being an exceptional automation tool, is not an exception in terms of the mentioned.
+
+Traditionally, application dependencies are installed by administrators on top of
+an operating system using packaging management tools like RPM or Python-pip.
+
+The major drawback of such approach is that an application might require versions
+of dependencies different from those provided by default.
+
+In case of Ansible, a typical installation consists of ansible-core and a set of Ansible collections.
+
+At present, there are more than a hundred collections included in the Ansible package and
+hundreds more are available on Ansible Galaxy and Automation Hub for manual installation.
+Many of them have dependencies for their 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 **partly** resolve dependency issue is
+to use Python virtual environments on Ansible control node.
+However, applied to Ansible, it has drawbacks and natural limitations.
+
+Portability
+-----------
+
+An Ansible user writes content for Ansible locally and wants to leverage the container technology
+to make your 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 like Ansible AWX/Controller used by several users, they might want their content be separated to avoid configuration and dependency conflicts.
+
+What to read next
+=================
+
+* :ref:`How to build and test EE guide<build_and_test_ee>`