From 3fb76e5410f3c1799d7b0ee8b9444c65fca01c34 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 16 Oct 2023 12:51:23 +0100 Subject: [PATCH] ee getting started points to ecosystem --- .../build_execution_environment.rst | 74 +------------ docs/docsite/rst/getting_started_ee/index.rst | 38 +++---- .../rst/getting_started_ee/introduction.rst | 6 +- .../run_community_ee_image.rst | 50 +-------- .../run_execution_environment.rst | 102 +----------------- .../getting_started_ee/setup_environment.rst | 43 +------- 6 files changed, 36 insertions(+), 277 deletions(-) diff --git a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst index 0200fbf13c9..73c849d20ee 100644 --- a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst +++ b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst @@ -1,76 +1,8 @@ +:orphan: .. _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<`_ 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` and test the EE you just built. - -.. seealso:: - - `Running a local container registry for EE `_ - Learn how to set up a simple local registry to host your Execution Environment images +Visit the Ansible ecosystem documentation for detailed instructions on using execution environments. +Return to :ref:`Getting started with Execution Environments` for more information. diff --git a/docs/docsite/rst/getting_started_ee/index.rst b/docs/docsite/rst/getting_started_ee/index.rst index 69a6858d97a..540591c5681 100644 --- a/docs/docsite/rst/getting_started_ee/index.rst +++ b/docs/docsite/rst/getting_started_ee/index.rst @@ -6,29 +6,29 @@ 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. +Execution Environments (EEs) are Ansible control nodes packaged as container images. +EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward. -An Execution Environment image contains the following packages as standard: +EEs provide you with: -* ``ansible-core`` -* ``ansible-runner`` -* Python -* Ansible content dependencies +* Software dependency isolation +* Portability across teams and environments +* Separation from other automation content and tooling -In addition to the standard packages, an EE can also contain: +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. -* one or more Ansible collections and their dependencies -* other custom components +Visit the `Ansible ecosystem documentation `_ and get started with EEs. -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. +Ansible ecosystem +----------------- -.. toctree:: - :maxdepth: 1 +Using EEs with projects in the Ansible ecosystem lets you expand automation to lots of use cases: - introduction - setup_environment - build_execution_environment - run_execution_environment - run_community_ee_image +* `Ansible Builder `_ +* `Ansible Navigator `_ +* `Ansible AWX `_ +* `Ansible Runner `_ +* VS Code `Ansible `_ and `Dev Containers `_ extensions + +Visit the `Ansible ecosystem documentation `_ to find How Tos and tutorials for using EEs with Ansible projects. diff --git a/docs/docsite/rst/getting_started_ee/introduction.rst b/docs/docsite/rst/getting_started_ee/introduction.rst index 6eb86042f94..d00536ec070 100644 --- a/docs/docsite/rst/getting_started_ee/introduction.rst +++ b/docs/docsite/rst/getting_started_ee/introduction.rst @@ -1,9 +1,13 @@ +:orphan: .. _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. +Visit the Ansible ecosystem documentation for detailed instructions on using execution environments. +Return to :ref:`Getting started with Execution Environments` for more information. + +Ansible Execution Environments remove complexity from automation projects and provide all the benefits you can get from containerization. Reducing complexity ------------------- diff --git a/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst b/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst index d4686d32610..6a83e4bc57c 100644 --- a/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst +++ b/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst @@ -1,52 +1,8 @@ +:orphan: .. _run_community_ee_image: 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: - -.. code-block:: yaml - - cat > test_localhost.yml<` for an example of how to run your playbook against a remote target. - -Ready to learn how to build an Execution Environment in a few easy steps? -Proceed to the :ref:`Building your first EE`. - -.. seealso:: - - `Ansible Navigator documentation `_ - Learn more about the ansible-navigator utility. - :ref:`The list of tools for EE` - See the list of tools you can use Execution Environments with. +Visit the Ansible ecosystem documentation for detailed instructions on using execution environments. +Return to :ref:`Getting started with Execution Environments` for more information. diff --git a/docs/docsite/rst/getting_started_ee/run_execution_environment.rst b/docs/docsite/rst/getting_started_ee/run_execution_environment.rst index 60f53474833..062bb9e5db6 100644 --- a/docs/docsite/rst/getting_started_ee/run_execution_environment.rst +++ b/docs/docsite/rst/getting_started_ee/run_execution_environment.rst @@ -1,104 +1,8 @@ +:orphan: .. _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< inventory/hosts.yml< test_remote.yml<`_ - More about Execution Environment definition file and available options. - `Ansible Builder CLI usage `_ - Find out more about Ansible Builder's command-line arguments. - `Ansible Navigator documentation `_ - Learn more about the ansible-navigator utility. - :ref:`The list of tools for EE` - See the list of tools you can use Execution Environments with. - :ref:`Running community EE guide` - Learn more about running the community-provided Execution Environment. - `Running a local container registry for EE `_ - Learn how to quickly set up a local container registry for your Execution Environments. +Visit the Ansible ecosystem documentation for detailed instructions on using execution environments. +Return to :ref:`Getting started with Execution Environments` for more information. diff --git a/docs/docsite/rst/getting_started_ee/setup_environment.rst b/docs/docsite/rst/getting_started_ee/setup_environment.rst index 0720be10a7e..b61bcc25153 100644 --- a/docs/docsite/rst/getting_started_ee/setup_environment.rst +++ b/docs/docsite/rst/getting_started_ee/setup_environment.rst @@ -1,45 +1,8 @@ +:orphan: .. _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 an EE in a few easy steps? -Proceed to the :ref:`Building your first EE`. - -Want to try an EE without having to build one? -Proceed to the :ref:`Running the community EE`. +Visit the Ansible ecosystem documentation for detailed instructions on using execution environments. +Return to :ref:`Getting started with Execution Environments` for more information.