From 8e9f86c7ca5036b59def4b0ff1a605f470432a34 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Mon, 12 Jun 2023 15:17:51 -0700 Subject: [PATCH] Added scenarios for version 3 (#538) * Scenario for copying arbitratory files * Scenario for ENV * Scenario for Galaxy client configuration Signed-off-by: Abhijeet Kasurde --- docs/definition.rst | 2 ++ docs/index.rst | 9 +++++ docs/scenario_guides/copy_ee.yml | 28 +++++++++++++++ docs/scenario_guides/env_ee.yml | 20 +++++++++++ docs/scenario_guides/galaxy_ansible.cfg | 2 ++ docs/scenario_guides/galaxy_ee.yml | 38 ++++++++++++++++++++ docs/scenario_guides/scenario_copy.rst | 26 ++++++++++++++ docs/scenario_guides/scenario_custom.rst | 39 +++++++++++++++++++++ docs/scenario_guides/scenario_using_env.rst | 24 +++++++++++++ 9 files changed, 188 insertions(+) create mode 100644 docs/scenario_guides/copy_ee.yml create mode 100644 docs/scenario_guides/env_ee.yml create mode 100644 docs/scenario_guides/galaxy_ansible.cfg create mode 100644 docs/scenario_guides/galaxy_ee.yml create mode 100644 docs/scenario_guides/scenario_copy.rst create mode 100644 docs/scenario_guides/scenario_custom.rst create mode 100644 docs/scenario_guides/scenario_using_env.rst diff --git a/docs/definition.rst b/docs/definition.rst index 46c64621..7d75f6a5 100644 --- a/docs/definition.rst +++ b/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: diff --git a/docs/index.rst b/docs/index.rst index 36695e87..d6af520d 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/scenario_guides/copy_ee.yml b/docs/scenario_guides/copy_ee.yml new file mode 100644 index 00000000..5deaddb0 --- /dev/null +++ b/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 diff --git a/docs/scenario_guides/env_ee.yml b/docs/scenario_guides/env_ee.yml new file mode 100644 index 00000000..6513a7d0 --- /dev/null +++ b/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 diff --git a/docs/scenario_guides/galaxy_ansible.cfg b/docs/scenario_guides/galaxy_ansible.cfg new file mode 100644 index 00000000..e3e65619 --- /dev/null +++ b/docs/scenario_guides/galaxy_ansible.cfg @@ -0,0 +1,2 @@ +[galaxy] +server_list = automation_hub diff --git a/docs/scenario_guides/galaxy_ee.yml b/docs/scenario_guides/galaxy_ee.yml new file mode 100644 index 00000000..0d70f600 --- /dev/null +++ b/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 diff --git a/docs/scenario_guides/scenario_copy.rst b/docs/scenario_guides/scenario_copy.rst new file mode 100644 index 00000000..cb28616e --- /dev/null +++ b/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 ` 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 ` + The detailed documentation about EE definition version 3 diff --git a/docs/scenario_guides/scenario_custom.rst b/docs/scenario_guides/scenario_custom.rst new file mode 100644 index 00000000..252612bf --- /dev/null +++ b/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 `_ 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 ` + The detailed documentation about EE definition version 3 diff --git a/docs/scenario_guides/scenario_using_env.rst b/docs/scenario_guides/scenario_using_env.rst new file mode 100644 index 00000000..93467bd1 --- /dev/null +++ b/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 ` 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 `. + The detailed documentation about EE definition version 3