Restore community ee content (#1852) (#1859)

* restore community ee content

This PR restores the docs about community execution environments from
the ecosystem docsite. Please see the forum post for more info about
this change: https://forum.ansible.com/t/moving-the-community-ee-content-to-package-docs/8239

* Update docs/docsite/rst/getting_started_ee/introduction.rst

Co-authored-by: Andrew Klychkov <[email protected]>

* Update docs/docsite/rst/getting_started_ee/introduction.rst

Co-authored-by: Andrew Klychkov <[email protected]>

* Update docs/docsite/rst/getting_started_ee/run_community_ee_image.rst

Co-authored-by: Andrew Klychkov <[email protected]>

* formatting nits

---------

Co-authored-by: Andrew Klychkov <[email protected]>
(cherry picked from commit 2043e2e)

Co-authored-by: Don Naro <[email protected]>

Author: patchback[bot]

docs/docsite/rst/getting_started_ee/build_execution_environment.rst

@@ -0,0 +1,57 @@
+.. _building_execution_environment:
+
+*****************************************
+Building your first Execution Environment
+*****************************************
+
+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:
+
+#. Create a project folder on your filesystem.
+
+   .. code-block:: bash
+
+      mkdir my_first_ee && cd my_first_ee
+
+#. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image.
+
+   .. literalinclude:: yaml/execution-environment.yml
+      :language: yaml
+
+    > 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.
+
+#. 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
+
+#. 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_custom_execution_environment` and test the EE you just built.
+
+.. seealso::
+
+   `Running a local container registry for Execution Environments <https://forum.ansible.com/t/running-a-local-container-registry-for-execution-environments/206>`_
+      This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images.

docs/docsite/rst/getting_started_ee/index.rst

@@ -4,29 +4,34 @@
 Getting started with Execution Environments
 *******************************************
 
-Execution Environments (EEs) are Ansible control nodes packaged as container images.
+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.
 EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward.
 
-EEs provide you with:
+An Execution Environment image contains the following packages as standard:
 
-* Software dependency isolation
-* Portability across teams and environments
-* Separation from other automation content and tooling
+* ``ansible-core``
+* ``ansible-runner``
+* Python
+* Ansible content dependencies
 
-You can use Ansible community EEs to get up and running.
-Or you can easily build and deploy custom EEs with whatever packages and Ansible community collections you need for your project.
+In addition to the standard packages, an EE can also contain:
 
-Visit `Getting started with Execution Environments <https://ansible.readthedocs.io/en/latest/getting_started_ee/index.html>`_ in the Ansible ecosystem documentation.
+* one or more Ansible collections and their dependencies
+* other custom components
 
-Ansible ecosystem
------------------
+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:
 
-Using EEs with projects in the Ansible ecosystem lets you expand automation to lots of use cases:
+* standard EE packages
+* ``community.postgresql`` collection
+* ``psycopg2-binary`` Python package
 
-* `Ansible Builder <https://ansible.readthedocs.io/projects/builder/en/latest/>`_
-* `Ansible Navigator <https://ansible.readthedocs.io/projects/navigator/>`_
-* `Ansible AWX <https://ansible.readthedocs.io/projects/awx/en/latest/userguide/execution_environments.html#use-an-execution-environment-in-jobs>`_
-* `Ansible Runner <https://ansible.readthedocs.io/projects/runner/en/stable/>`_
-* VS Code `Ansible <https://marketplace.visualstudio.com/items?itemName=redhat.ansible>`_ and `Dev Containers <https://code.visualstudio.com/docs/devcontainers/containers>`_ extensions
+.. toctree::
+   :maxdepth: 1
 
-Visit the `Ansible ecosystem documentation <https://ansible.readthedocs.io/en/latest/index.html>`_ to find How Tos and tutorials for using EEs with Ansible projects.
+   introduction
+   setup_environment
+   build_execution_environment
+   run_execution_environment
+   run_community_ee_image

docs/docsite/rst/getting_started_ee/introduction.rst

@@ -0,0 +1,65 @@
+.. _introduction_execution_environment:
+
+**************************************
+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
+* 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 the 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 EEs
+=======================
+
+Projects in the Ansible ecosystem also provide several tools 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://ansible.readthedocs.io/projects/awx/en/latest/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>`_
+* `Dev Containers extensions <https://code.visualstudio.com/docs/devcontainers/containers>`_
+
+Ready to get started with EEs? Proceed to :ref:`setting_up_ee_environment`.

docs/docsite/rst/getting_started_ee/run_community_ee_image.rst

@@ -0,0 +1,35 @@
+.. _running_community_execution_environment:
+
+*******************************************
+Running Ansible with the community EE image
+*******************************************
+
+You can run ansible without the need to build a custom EE using community images.
+
+Use the ``community-ee-minimal`` image that includes only ``ansible-core`` or the ``community-ee-base`` image that also includes several base collections.
+Run the following command to see the collections included in the ``community-ee-base`` image:
+
+.. code-block:: bash
+
+   ansible-navigator collections --execution-environment-image ghcr.io/ansible-community/community-ee-base:latest
+
+Run the following Ansible ad-hoc command against localhost inside the ``community-ee-minimal`` container:
+
+.. code-block:: bash
+
+   ansible-navigator exec "ansible localhost -m setup" --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout
+
+Now, create a simple test playbook and run it against ``localhost`` inside the container:
+
+.. literalinclude:: yaml/test_localhost.yml
+   :language: yaml
+
+.. code-block:: bash
+
+   ansible-navigator run test_localhost.yml --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout
+
+.. seealso::
+
+   * :ref:`building_execution_environment`
+   * :ref:`running_custom_execution_environment`
+   * `Ansible Navigator documentation <https://ansible-navigator.readthedocs.io/>`_

docs/docsite/rst/getting_started_ee/run_execution_environment.rst

@@ -0,0 +1,73 @@
+.. _running_custom_execution_environment:
+
+***************
+Running your EE
+***************
+
+You can run your EE on the command line against ``localhost`` or a remote target using ``ansible-navigator``.
+
+> There are other tools besides ``ansible-navigator`` you can run EEs with.
+
+Run against localhost
+=====================
+
+#. Create a ``test_localhost.yml`` playbook.
+
+   .. literalinclude:: yaml/test_localhost.yml
+      :language: yaml
+
+#. 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 --container-options='--user=0'
+
+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
+===========================
+
+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.
+
+Execute a playbook inside the ``postgresql_ee`` EE against a remote host machine as in the following example:
+
+#. Create a directory for inventory files.
+
+   .. code-block:: bash
+
+      mkdir inventory
+
+#. Create the ``hosts.yml`` inventory file in the ``inventory`` directory.
+
+   .. literalinclude:: yaml/hosts.yml
+      :language: yaml
+
+#. Create a ``test_remote.yml`` playbook.
+
+   .. literalinclude:: yaml/test_remote.yml
+      :language: yaml
+
+#. Run the playbook inside the ``postgresql_ee`` EE.
+
+   Replace ``student`` with the appropriate username.
+   Some arguments in the command can be optional depending on your target host authentication method.
+
+   .. 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
+
+.. seealso::
+
+   `Execution Environment Definition <https://ansible-builder.readthedocs.io/en/stable/definition/>`_
+      Provides information about the about Execution Environment definition file and available options.
+   `Ansible Builder CLI usage <https://ansible-builder.readthedocs.io/en/stable/usage/>`_
+      Provides details about using Ansible Builder.
+   `Ansible Navigator documentation <https://ansible-navigator.readthedocs.io/>`_
+      Provides details about using Ansible Navigator.
+   `Running a local container registry for EEs <https://forum.ansible.com/t/running-local-container-registry-for-execution-environments/206>`_
+      This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images.

docs/docsite/rst/getting_started_ee/setup_environment.rst

@@ -0,0 +1,44 @@
+.. _setting_up_ee_environment:
+
+***************************
+Setting up your environment
+***************************
+
+Complete the following steps to set up a local environment for your first Execution Environment:
+
+#. 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
+
+#. 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
+
+#. Verify your environment with the following commands:
+
+    .. code-block:: bash
+
+       ansible-navigator --version
+       ansible-builder --version
+
+Ready to build an EE in a few easy steps? Proceed to :ref:`building_execution_environment`.
+
+Want to try an EE without having to build one? Proceed to :ref:`running_community_execution_environment`.

docs/docsite/rst/getting_started_ee/yaml/execution-environment.yml

@@ -0,0 +1,17 @@
+version: 3
+
+images:
+  base_image:
+    name: quay.io/fedora/fedora:latest
+
+dependencies:
+  ansible_core:
+    package_pip: ansible-core
+  ansible_runner:
+    package_pip: ansible-runner
+  system:
+  - openssh-clients
+  - sshpass
+  galaxy:
+    collections:
+    - name: community.postgresql

docs/docsite/rst/getting_started_ee/yaml/hosts.yml

@@ -0,0 +1,3 @@
+all:
+  hosts:
+    192.168.0.2  # Replace with the IP of your target host

docs/docsite/rst/getting_started_ee/yaml/test_localhost.yml

@@ -0,0 +1,9 @@
+- name: Gather and print local facts
+  hosts: localhost
+  become: true
+  gather_facts: true
+  tasks:
+
+   - name: Print facts
+     ansible.builtin.debug:
+      var: ansible_facts

docs/docsite/rst/getting_started_ee/yaml/test_remote.yml

@@ -0,0 +1,9 @@
+- name: Gather and print facts
+  hosts: all
+  become: true
+  gather_facts: true
+  tasks:
+
+   - name: Print facts
+     ansible.builtin.debug:
+      var: ansible_facts