diff --git a/docs/definition.rst b/docs/definition.rst index 83510e89..bbb0593e 100644 --- a/docs/definition.rst +++ b/docs/definition.rst @@ -88,6 +88,8 @@ Configuration options You may use the configuration YAML keys listed here in your v3 execution environment definition file. +.. _additional_build_files: + additional_build_files ^^^^^^^^^^^^^^^^^^^^^^ @@ -111,6 +113,8 @@ Each list item must be a dictionary containing the following (non-optional) keys This may not be an absolute path or contain ``..`` within the path. This directory will be created for you if it does not exist. +.. _additional_build_steps: + additional_build_steps ^^^^^^^^^^^^^^^^^^^^^^ @@ -179,6 +183,8 @@ build instruction file, so they will persist if you run your container build man If you specify the same variable in the execution environment definition and at the command line with the CLI :ref:`build-arg` flag, the CLI value will take higher precedence (the CLI value will override the value in the execution environment definition). +.. _dependencies: + dependencies ^^^^^^^^^^^^ @@ -237,7 +243,7 @@ The following keys are valid for this section: The system packages to be installed, in bindep format. This may either be a filename, or a list of requirements (see below for an example). -The following example uses filenames that contain the various dependencies: +The following example uses filenames that contain various dependencies: .. code:: yaml @@ -275,6 +281,7 @@ And this example uses inline values: package_system: "python310" python_path: "/usr/bin/python3.10" +.. _images: images ^^^^^^ @@ -289,6 +296,8 @@ Valid keys for this section are: key if the image is mirrored within your repository, but signed with the original image's signature key. +.. _image_verification: + image verification """""""""""""""""" You can verify signed container images if you are using the ``podman`` container @@ -310,6 +319,8 @@ file for container image signature validation. :ref:`context directory ` that will be used during the build to validate the images. +.. _options: + options ^^^^^^^ @@ -393,6 +404,8 @@ Example ``options`` section: tags: - ee_development:latest +.. _version: + version ^^^^^^^ diff --git a/docs/index.rst b/docs/index.rst index f1624249..f8ea657d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -109,6 +109,7 @@ Collection maintainers can learn to correctly declare dependencies for their col definition usage collection_metadata + porting_guide_v3 glossary .. toctree:: diff --git a/docs/porting_guide_v3.rst b/docs/porting_guide_v3.rst new file mode 100644 index 00000000..4dd1af16 --- /dev/null +++ b/docs/porting_guide_v3.rst @@ -0,0 +1,113 @@ +.. _porting_guide_v3: + +Ansible Builder version 3 Porting Guide +======================================= + +This section discusses the behavioral changes between ``ansible-builder`` version 1.2 and version 3.0. + +We suggest you read this page along with `ansible-builder 3.0 release notes `_ to understand what updates you may need to make. + +.. contents:: Topics + +Overview +-------- +The Ansible Builder 3.x execution environment definition file accepts seven top-level sections: + +* additional_build_files +* additional_build_steps +* build_arg_defaults +* dependencies +* images +* options +* version + +Porting options +--------------- + +You need to change the configuration YAML keys in your older (v1 and v2) execution environment file to the one listed here. + +additional_build_files +^^^^^^^^^^^^^^^^^^^^^^ + +This is a new configuration that can be used to specify files to be added to the build context directory. +These can then be referenced or copied by `additional_build_steps` during any build stage. + +See the :ref:`additional_build_files ` section for more details. + +additional_build_steps +^^^^^^^^^^^^^^^^^^^^^^ + +With Ansible Builder 3, you can specify more fine-grained build steps or custom commands for any build phase. +These commands will be inserted directly into the build instruction file for the +container runtime (For example, `Containerfile` or `Dockerfile`). The commands must conform to any rules required by the containerization tool. + +These are additional build steps - + +* ``prepend_base`` +* ``append_base`` +* ``prepend_galaxy`` +* ``append_galaxy`` +* ``prepend_builder`` +* ``append_builder`` +* ``prepend_final`` +* ``append_final`` + +See the :ref:`additional_build_steps ` section for more details. + +dependencies +^^^^^^^^^^^^ + +Specifies dependencies to install into the final image, including ``ansible-core``, ``ansible-runner``, Python packages, system packages, and Ansible Collections. Ansible Builder automatically installs dependencies for any Ansible Collections you install. + +In general, you can use standard syntax to constrain package versions. Use the same syntax you would pass to ``dnf``, ``pip``, ``ansible-galaxy``, or any other package management utility. You can also define your packages or collections in separate files and reference those files in the ``dependencies`` section of your execution environment definition file. + +The following keys are valid for this section: + +* ``ansible_core`` +* ``ansible_runner`` +* ``galaxy`` +* ``python`` +* ``python_interpreter`` +* ``system`` + +See the :ref:`dependencies ` section for more details. + +images +^^^^^^ + +Specifies the base image to be used. At a minimum you *MUST* specify a source, image, and tag for the base image. The base image provides the operating system and may also provide some packages. We recommend using the standard ``host/namespace/container:tag`` syntax to specify images. + +See the :ref:`images ` section for more details. + +image verification +"""""""""""""""""" +You can verify signed container images if you are using the ``podman`` container +runtime. + +See the :ref:`image verification ` section for more details. + +options +^^^^^^^ + +A dictionary of keywords/options that can affect +builder runtime functionality. Valid keys for this section are: + +* ``container_init`` +* ``cmd`` +* ``entrypoint`` +* ``package_pip`` +* ``package_manager_path`` +* ``skip_ansible_check`` +* ``relax_passwd_permissions`` +* ``workdir`` +* ``user`` +* ``tags`` + +See the :ref:`options ` section for more details. + +version +^^^^^^^ + +Must be ``3`` if you are using Ansible Builder 3.x. + +See the :ref:`version ` section for more details. \ No newline at end of file