Added scenarios for version 3 (#538)

* Scenario for copying arbitratory files
* Scenario for ENV
* Scenario for Galaxy client configuration

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

docs/definition.rst

@@ -11,6 +11,8 @@ You define the content of your execution environment in a YAML file. By default,
 .. contents::
    :local:
 
+.. _version_3_format:
+
 Overview
 --------
 The Ansible Builder 3.x execution environment definition file accepts seven top-level sections:

docs/index.rst

@@ -102,3 +102,12 @@ When Ansible Builder installs collections into an execution environment, it also
    usage
    collection_metadata
    glossary
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+   :caption: Common Scenarios
+
+   scenario_guides/scenario_copy
+   scenario_guides/scenario_using_env
+   scenario_guides/scenario_custom

docs/scenario_guides/copy_ee.yml

@@ -0,0 +1,28 @@
+---
+version: 3
+
+images:
+  base_image:
+    name: quay.io/centos/centos:stream9  # vanilla image
+
+dependencies:
+  # Use Python 3.9
+  python_interpreter:
+    package_system: python39
+    python_path: /usr/bin/python3.9
+  # Collections to be installed
+  galaxy:
+    collections:
+      - ansible.utils
+
+additional_build_files:
+  # copy arbitrary files next to this EE def into the build context - we can refer to them later...
+  - src: files/rootCA.crt
+    dest: configs
+
+additional_build_steps:
+  prepend_base:
+    # copy a custom CA cert into the base image and recompute the trust database
+    # because this is in "base", all stages will inherit (including the final EE)
+    - COPY _build/configs/rootCA.crt /usr/share/pki/ca-trust-source/anchors
+    - RUN update-ca-trust

docs/scenario_guides/env_ee.yml

@@ -0,0 +1,20 @@
+---
+version: 3
+
+images:
+  base_image:
+    name: quay.io/centos/centos:stream9
+
+dependencies:
+  python_interpreter:
+    package_system: python39
+    python_path: /usr/bin/python3.9
+  ansible_core:
+    package_pip: ansible-core==2.14.0
+  ansible_runner:
+    package_pip: ansible-runner==2.3.2
+
+additional_build_steps:
+  prepend_base:
+    - ENV FOO=bar
+    - RUN echo $FOO > /tmp/file1.txt

docs/scenario_guides/galaxy_ansible.cfg

@@ -0,0 +1,2 @@
+[galaxy]
+server_list = automation_hub

docs/scenario_guides/galaxy_ee.yml

@@ -0,0 +1,38 @@
+---
+version: 3
+
+images:
+  base_image:
+    # Needs login
+    name: registry.redhat.io/ansible-automation-platform-23/ee-minimal-rhel8:latest
+
+dependencies:
+  # Use Ansible Core 2.14
+  ansible_core:
+    package_pip: ansible-core==2.14.0
+  # Runner
+  ansible_runner:
+    package_pip: ansible-runner==2.3.2
+  # Collections to be installed using Galaxy
+  galaxy:
+    collections:
+      - ansible.utils
+
+additional_build_files:
+  # copy arbitrary files next to this EE def into the build context- we can refer to them later.
+  - src: files
+    dest: configs
+
+additional_build_steps:
+  prepend_galaxy:
+    # Copy ansible.cfg from build directory to EE
+    - COPY _build/configs/ansible.cfg /etc/ansible/ansible.cfg
+    # Environment variables used for Galaxy client configurations
+    - ENV ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_URL=https://console.redhat.com/api/automation-hub/content/xxxxxxx-synclist/
+    - ENV ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_AUTH_URL=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
+    # define a custom build arg env passthru - we still also have to pass
+    # `--build-arg ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN` to get it to pick it up from the env
+    - ARG ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN
+
+options:
+  package_manager_path: /usr/bin/microdnf  # downstream images use non-standard package manager

docs/scenario_guides/scenario_copy.rst

@@ -0,0 +1,26 @@
+.. _copy_usage:
+
+Copying arbitratory files to EE
+===============================
+
+Ansible Builder version 3 schema provides the option to copy files to an EE image.
+See  the :ref:`version 3 schema <version_3_format>` for more details.
+
+In the example below, we will take a look at copying arbitratory files to an execution environment.
+
+
+.. literalinclude:: copy_ee.yml
+   :language: yaml
+
+In this example, the `additional_build_files` section allows you to add `rootCA.crt` to the build context directory.
+Once this file is copied to the build context directory, it can be used in the build process.
+In order to use, the file,  we need to copy it from the build context directory using  the `COPY` directive specified in
+the `prepend_base` step of `additional_build_steps` section.
+
+Finally, you can perform any action based upon the copied file, such as in this example updating
+dynamic configuration of CA certificates by running `RUN update-ca-trust`.
+
+.. seealso::
+
+   :ref:`Execution Environment Definition version 3 <version_3_format>`
+      The detailed documentation about EE definition version 3

docs/scenario_guides/scenario_custom.rst

@@ -0,0 +1,39 @@
+.. _custom_usage:
+
+Building EEs with environment variables  and `ansible.cfg`
+==========================================================
+
+Ansible Builder version 3 schema allows users to perform complex scenarios
+such as specifying custom Galaxy configurations.
+You can use this approach to pass sensitive information, such as authentication tokens,
+into the EE build without leaking them into the final EE image.
+
+In the example below, we will take a look at
+
+* Copying `ansible.cfg` file to an execution environment
+* Using Galaxy Server environment variables
+
+.. literalinclude:: galaxy_ee.yml
+   :language: yaml
+
+
+.. literalinclude:: galaxy_ansible.cfg
+   :language: ini
+
+In this example, the `additional_build_files` section allows you to add `ansible.cfg` to the build context directory.
+Once this file is copied to the build context directory, it can be used in the build process.
+In order to use the file, we need to copy it from the build context directory using the `COPY` directive specified in
+the `prepend_galaxy` step of `additional_build_steps` section.
+
+You can provide environment variables such as `ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_URL` and `ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_AUTH_URL`
+using the `ENV` directive.
+See `configuring Galaxy client <https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#configuring-the-ansible-galaxy-client>`_ for more details.
+
+For security reason, we do not want to store sensitive information in this case `ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN`.
+You can use `ARG` directive in order to receive the sensitive information from the user as an input. `--build-args` can be used
+to provide this information while invoking the `ansible-builder` command.
+
+.. seealso::
+
+   :ref:`Execution Environment Definition version 3 <version_3_format>`
+      The detailed documentation about EE definition version 3

docs/scenario_guides/scenario_using_env.rst

@@ -0,0 +1,24 @@
+.. _env_usage:
+
+Building EEs with environment variables
+=======================================
+
+Ansible Builder version 3 schema provides the option to specify environment variables which can be used in the build process.
+See :ref:`version 3 schema <version_3_format>` for more details.
+
+In the example below, we will take a look at specifying `ENV` variables.
+
+
+.. literalinclude:: env_ee.yml
+   :language: yaml
+
+In this example, we are specifying an environment variable which may be required for the build process.
+In order to achieve this functionality we are using the `ENV` variable
+definition in the ``prepend_base`` step of the `additional_build_steps` section.
+
+We can use the same environment variable in the later stage of the build process.
+
+.. seealso::
+
+   :ref:`Execution Environment Definition version 3 <version_3_format>`.
+       The detailed documentation about EE definition version 3