Skip to content

Commit

Permalink
ee getting started points to ecosystem
Browse files Browse the repository at this point in the history
  • Loading branch information
@oraNod
oraNod committed Oct 17, 2023
1 parent 96d5929 commit 3fb76e5
Show file tree
Hide file tree
Showing 6 changed files with 36 additions and 277 deletions.
74 changes: 3 additions & 71 deletions docs/docsite/rst/getting_started_ee/build_execution_environment.rst
View file
Original file line number Diff line number Diff line change
@@ -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<<EOF
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
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.

.. seealso::

`Running a local container registry for EE <https://forum.ansible.com/t/running-a-local-container-registry-for-execution-environments/206>`_
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<getting_started_ee_index>` for more information.
38 changes: 19 additions & 19 deletions docs/docsite/rst/getting_started_ee/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://ansible.readthedocs.io/en/latest/>`_ 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 <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

Visit the `Ansible ecosystem documentation <https://ansible.readthedocs.io/en/latest/>`_ to find How Tos and tutorials for using EEs with Ansible projects.
6 changes: 5 additions & 1 deletion docs/docsite/rst/getting_started_ee/introduction.rst
View file
Original file line number Diff line number Diff line change
@@ -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<getting_started_ee_index>` for more information.

Ansible Execution Environments remove complexity from automation projects and provide all the benefits you can get from containerization.

Reducing complexity
-------------------
Expand Down
50 changes: 3 additions & 47 deletions docs/docsite/rst/getting_started_ee/run_community_ee_image.rst
View file
Original file line number Diff line number Diff line change
@@ -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<<EOF
- name: Gather and print local facts
hosts: localhost
become: yes
gather_facts: yes
tasks:
- name: Print facts
ansible.builtin.debug:
var: ansible_facts
EOF
.. code-block:: bash
ansible-navigator run test_localhost.yml --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout
See the :ref:`Running your EE guide<running_execution_environments_remote_target>` 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<building_execution_environments>`.

.. seealso::

`Ansible Navigator documentation <https://ansible-navigator.readthedocs.io/>`_
Learn more about the ansible-navigator utility.
:ref:`The list of tools for EE<ansible_tooling_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<getting_started_ee_index>` for more information.
102 changes: 3 additions & 99 deletions docs/docsite/rst/getting_started_ee/run_execution_environment.rst
View file
Original file line number Diff line number Diff line change
@@ -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<<EOF
- name: Gather and print local facts
hosts: localhost
become: yes
gather_facts: yes
tasks:
- name: Print facts
ansible.builtin.debug:
var: 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 --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.

.. _running_execution_environments_remote_target:

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
- name: Gather and print facts
hosts: all
become: yes
gather_facts: yes
tasks:
- name: Print facts
ansible.builtin.debug:
var: ansible_facts
EOF
4. 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/>`_
More about Execution Environment definition file and available options.
`Ansible Builder CLI usage <https://ansible-builder.readthedocs.io/en/stable/usage/>`_
Find out more about Ansible Builder's command-line arguments.
`Ansible Navigator documentation <https://ansible-navigator.readthedocs.io/>`_
Learn more about the ansible-navigator utility.
:ref:`The list of tools for EE<ansible_tooling_for_ee>`
See the list of tools you can use Execution Environments with.
:ref:`Running community EE guide<run_community_ee_image>`
Learn more about running the community-provided Execution Environment.
`Running a local container registry for EE <https://forum.ansible.com/t/running-local-container-registry-for-execution-environments/206>`_
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<getting_started_ee_index>` for more information.
43 changes: 3 additions & 40 deletions docs/docsite/rst/getting_started_ee/setup_environment.rst
View file
Original file line number Diff line number Diff line change
@@ -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<building_execution_environments>`.

Want to try an EE without having to build one?
Proceed to the :ref:`Running the community EE<run_community_ee_image>`.
Visit the Ansible ecosystem documentation for detailed instructions on using execution environments.
Return to :ref:`Getting started with Execution Environments<getting_started_ee_index>` for more information.

0 comments on commit 3fb76e5

Please sign in to comment.