From 1606573f9ae257962798812784d5e40c89e18341 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Fri, 9 Jun 2023 11:53:39 -0700 Subject: [PATCH] Added scenarios for version 3 * 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 | 26 ++++++++++++++++ docs/scenario_guides/env_ee.yml | 20 ++++++++++++ docs/scenario_guides/galaxy_ansible.cfg | 2 ++ docs/scenario_guides/galaxy_ee.yml | 33 ++++++++++++++++++++ docs/scenario_guides/scenario_copy.rst | 26 ++++++++++++++++ docs/scenario_guides/scenario_custom.rst | 34 +++++++++++++++++++++ docs/scenario_guides/scenario_using_env.rst | 24 +++++++++++++++ 9 files changed, 176 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..f304b2f6 --- /dev/null +++ b/docs/scenario_guides/copy_ee.yml @@ -0,0 +1,26 @@ +--- +version: 3 + +images: + base_image: + name: quay.io/centos/centos:stream9 + +dependencies: + python_interpreter: + package_system: python39 + python_path: /usr/bin/python3.9 + 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..6647dd6f --- /dev/null +++ b/docs/scenario_guides/galaxy_ee.yml @@ -0,0 +1,33 @@ +--- +version: 3 + +images: + base_image: + name: registry.redhat.io/ansible-automation-platform-23/ee-minimal-rhel8:latest + +dependencies: + ansible_core: + package_pip: ansible-core==2.14.0 + ansible_runner: + package_pip: ansible-runner==2.3.2 + 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 _build/configs/ansible.cfg /etc/ansible/ansible.cfg + - 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 + # NB: this is still a lot harder than it should be... + - ARG ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN + +options: + package_manager_path: /usr/bin/microdnf 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..400a4c85 --- /dev/null +++ b/docs/scenario_guides/scenario_custom.rst @@ -0,0 +1,34 @@ +.. _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. + +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. + + +.. 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