diff --git a/downstream/assemblies/builder/assembly-definition-file-breakdown.adoc b/downstream/assemblies/builder/assembly-definition-file-breakdown.adoc index d7f64972a..113ccb512 100644 --- a/downstream/assemblies/builder/assembly-definition-file-breakdown.adoc +++ b/downstream/assemblies/builder/assembly-definition-file-breakdown.adoc @@ -4,7 +4,7 @@ A definition file is required for building {ExecEnvName} with {Builder}, because it specifies the content that is included in the {ExecEnvNameSing} container image. -The following sections breaks down the different parts of a definition file. +The following sections break down the different parts of a definition file. include::builder/ref-build-args-base-image.adoc[leveloffset=+1] //include::builder/con-ansible-config-file-path.adoc[leveloffset=+1] @@ -13,6 +13,7 @@ include::builder/con-galaxy-dependencies.adoc[leveloffset=+2] include::builder/con-python-dependencies.adoc[leveloffset=+2] include::builder/con-system-dependencies.adoc[leveloffset=+2] include::builder/ref-definition-file-images.adoc[leveloffset=+1] +include::builder/ref-example-file-to-build-image.adoc[leveloffset=+2] include::builder/con-additional-build-files.adoc[leveloffset=+1] include::builder/con-additional-custom-build-steps.adoc[leveloffset=+1] diff --git a/downstream/assemblies/builder/assembly-using-builder.adoc b/downstream/assemblies/builder/assembly-using-builder.adoc index 9a713d8e8..3e96290f8 100644 --- a/downstream/assemblies/builder/assembly-using-builder.adoc +++ b/downstream/assemblies/builder/assembly-using-builder.adoc @@ -6,6 +6,7 @@ include::builder/con-why-builder.adoc[leveloffset=+1] include::builder/proc-installing-builder.adoc[leveloffset=+1] +include::builder/ref-content-needed-for-builder.adoc[leveloffset=+1] include::platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc[leveloffset=+1] include::builder/con-building-definition-file.adoc[leveloffset=+1] diff --git a/downstream/modules/builder/con-about-ee.adoc b/downstream/modules/builder/con-about-ee.adoc index 71d00bcac..b2bcfbc1b 100644 --- a/downstream/modules/builder/con-about-ee.adoc +++ b/downstream/modules/builder/con-about-ee.adoc @@ -4,9 +4,11 @@ [role="_abstract"] -All automation in {PlatformName} runs on container images called {ExecEnvName}. +All automation in {PlatformName} runs on Podman container images called {ExecEnvName}. {ExecEnvNameStart} create a common language for communicating automation dependencies, and offer a standard way to build and distribute the automation environment. +Red Hat provides supported {ExecEnvShort}s link:https://catalog.redhat.com/search?gs&q=execution%20environments&searchType=containers[here]. + An {ExecEnvNameSing} should contain the following: * Ansible Core 2.15 or later @@ -14,3 +16,5 @@ An {ExecEnvNameSing} should contain the following: * {Runner} * Ansible content collections and their dependencies * System dependencies + + diff --git a/downstream/modules/builder/con-additional-build-files.adoc b/downstream/modules/builder/con-additional-build-files.adoc index 12c57fa0e..9dcb85daf 100644 --- a/downstream/modules/builder/con-additional-build-files.adoc +++ b/downstream/modules/builder/con-additional-build-files.adoc @@ -7,10 +7,11 @@ You can add any external file to the build context directory by referring or cop Each list item must be a dictionary containing the following required keys: `src`:: Specifies the source files to copy into the build context directory. This can be an absolute path (for example, `/home/user/.ansible.cfg`), or a path that is relative to the {ExecEnvShort} file. Relative paths can be glob expressions matching one or more files (for example, `files/*.cfg`). - ++ [NOTE] ==== -Absolute paths can not include a regular expression. If `src` is a directory, the entire contents of that directory are copied to `dest`. +Absolute paths can not include a regular expression. +If `src` is a directory, the entire contents of that directory are copied to `dest`. ==== `dest`:: Specifies a subdirectory path underneath the `_build` subdirectory of the build context directory that contains the source files (for example, `files/configs`). This can not be an absolute path or contain `..` within the path. {Builder} creates this directory for you if it does not already exist. diff --git a/downstream/modules/builder/con-additional-custom-build-steps.adoc b/downstream/modules/builder/con-additional-custom-build-steps.adoc index 336e76909..86cfb6fbc 100644 --- a/downstream/modules/builder/con-additional-custom-build-steps.adoc +++ b/downstream/modules/builder/con-additional-custom-build-steps.adoc @@ -2,39 +2,41 @@ = Additional custom build steps -You can specify custom build commands for any build phase in the `additional_build_steps` section of the definition file. This allows fine-grained control over the build phases. +You can specify custom build commands for any build phase in the `additional_build_steps` section of the definition file. +This enables fine-grained control over the build phases. -Use the `prepend_` and `append_` commands to add directives to the `Containerfile` that run either before or after the main build steps are executed. The commands must conform to any rules required for the runtime system. +Use the `prepend_` and `append_` commands to add directives to the `Containerfile` that run either before or after the main build steps are executed. +The commands must conform to any rules required for the runtime system. -See the following table for a list of values that can be used in `additional_build_steps`: +The following table shows a list of values that can be used in `additional_build_steps`: [cols="a,a"] |=== | Value | Description | `prepend_base` -| Allows you to insert commands before building the base image. +| Enables you to insert commands before building the base image. | `append_base` -| Allows you to insert commands after building the base image. +| Enables you to insert commands after building the base image. | `prepend_galaxy` -| Allows you to insert before building the galaxy image. +| Enables you to insert before building the galaxy image. | `append_galaxy` -| Allows you to insert after building the galaxy image. +| Enables you to insert after building the galaxy image. | `prepend_builder` -| Allows you to insert commands before building the Python builder image. +| Enables you to insert commands before building the Python builder image. | `append_builder` -| Allows you to insert commands after building the Python builder image. +| Enables you to insert commands after building the Python builder image. | `prepend_final` -| Allows you to insert before building the final image. +| Enables you to insert before building the final image. | `append_final` -| Allows you to insert after building the final image. +| Enables you to insert after building the final image. |=== diff --git a/downstream/modules/builder/con-building-definition-file.adoc b/downstream/modules/builder/con-building-definition-file.adoc index 3bf85b2d8..e2beb7d26 100644 --- a/downstream/modules/builder/con-building-definition-file.adoc +++ b/downstream/modules/builder/con-building-definition-file.adoc @@ -2,7 +2,9 @@ = Building a definition file -After you install {Builder}, you can create a definition file that {Builder} uses to create your {ExecEnvNameSing} image. {Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} image. The definition file that you create must be in `yaml` format and contain different sections. The default definition filename, if not provided, is `execution-environment.yml`. For more information on the parts of a definition file, see xref:assembly-definition-file-breakdown[Breakdown of definition file content]. +After you install {Builder}, you can create a definition file that defines what {Builder} uses to create your {ExecEnvNameSing} image. +{Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} container image. +The definition file that you create must be in `yaml` format and contain different sections. The default definition filename, if not provided, is `execution-environment.yml`. For more information on the parts of a definition file, see xref:assembly-definition-file-breakdown[Breakdown of definition file content]. The following is an example of a version 3 definition file. Each definition file must specify the major version number of the {Builder} feature set it uses. If not specified, {Builder} defaults to version 1, making most new features and definition keywords unavailable. diff --git a/downstream/modules/builder/con-container_file.adoc b/downstream/modules/builder/con-container_file.adoc index 4521842fa..a72618a05 100644 --- a/downstream/modules/builder/con-container_file.adoc +++ b/downstream/modules/builder/con-container_file.adoc @@ -2,10 +2,16 @@ = Containerfile -After your definition file is created, {Builder} reads and validates it, creates a `Containerfile` and container build context, and optionally passes these to Podman to build your {ExecEnvNameSing} image. The container build occurs in several distinct stages: `base` , `galaxy`, `builder`, and `final`. The image build steps (along with any corresponding custom `prepend_` and `append_` steps defined in `additional_build_steps`) are: +After your definition file is created, {Builder} reads and validates it, creates a `Containerfile` and container build context, and optionally passes these to Podman to build your {ExecEnvNameSing} image. +The container build occurs in several distinct stages: `base` , `galaxy`, `builder`, and `final`. +The image build steps (along with any corresponding custom `prepend_` and `append_` steps defined in `additional_build_steps`) are: -. During the `base` build stage, the specified base image is (optionally) customized with components required by other build stages, including Python, `pip`, `ansible-core`, and `ansible-runner`. The resulting image is then validated to ensure that the required components are available (as they may have already been present in the base image). Ephemeral copies of the resulting customized `base` image are used as the base for all other build stages. -. During the `galaxy` build stage, collections specified by the definition file are downloaded and stored for later installation during the `final` build stage. Python and system dependencies declared by the collections, if any, are also collected for later analysis. -. During the `builder` build stage, Python dependencies declared by collections are merged with those listed in the definition file. This final set of Python dependencies is downloaded and built as Python wheels and stored for later installation during the `final` build stage. +. During the `base` build stage, the specified base image is (optionally) customized with components required by other build stages, including Python, `pip`, `ansible-core`, and `ansible-runner`. +The resulting image is then validated to ensure that the required components are available (as they may have already been present in the base image). +Ephemeral copies of the resulting customized `base` image are used as the base for all other build stages. +. During the `galaxy` build stage, collections specified by the definition file are downloaded and stored for later installation during the `final` build stage. +Python and system dependencies declared by the collections, if any, are also collected for later analysis. +. During the `builder` build stage, Python dependencies declared by collections are merged with those listed in the definition file. +This final set of Python dependencies is downloaded and built as Python wheels and stored for later installation during the `final` build stage. . During the `final` build stage, the previously-downloaded collections are installed, along with system packages and any previously-built Python packages that were declared as dependencies by the collections or listed in the definition file. //Note if a diagram with the Main step actions gets created, it should be included here. Check with @nitzmahone diff --git a/downstream/modules/builder/con-galaxy-dependencies.adoc b/downstream/modules/builder/con-galaxy-dependencies.adoc index 264371316..b52c84af9 100644 --- a/downstream/modules/builder/con-galaxy-dependencies.adoc +++ b/downstream/modules/builder/con-galaxy-dependencies.adoc @@ -1,13 +1,13 @@ [id="con-galaxy-dependencies"] -= Galaxy += {Galaxy} dependencies The `galaxy` entry points to a valid requirements file or includes inline content for the `ansible-galaxy collection install -r ...` command. The entry `requirements.yml` can be a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path. The content might look like the following: -.Galaxy entry +.{Galaxy} entry [example] ==== ---- diff --git a/downstream/modules/builder/con-optional-build-command-arguments.adoc b/downstream/modules/builder/con-optional-build-command-arguments.adoc index 1952a053a..c651e8840 100644 --- a/downstream/modules/builder/con-optional-build-command-arguments.adoc +++ b/downstream/modules/builder/con-optional-build-command-arguments.adoc @@ -2,7 +2,7 @@ = Optional build command arguments -The `-t` flag will tag your {ExecEnvNameSing} image with a specific name. For example, the following command will build an image named `my_first_ee_image`: +The `-t` flag tags your {ExecEnvNameSing} image with a specific name. For example, the following command builds an image named `my_first_ee_image`: ==== ---- diff --git a/downstream/modules/builder/con-python-dependencies.adoc b/downstream/modules/builder/con-python-dependencies.adoc index 54c589b11..95cb5241e 100644 --- a/downstream/modules/builder/con-python-dependencies.adoc +++ b/downstream/modules/builder/con-python-dependencies.adoc @@ -1,10 +1,12 @@ [id="con-python-dependencies"] -= Python += Python dependencies The `python` entry in the definition file points to a valid requirements file or to an inline list of Python requirements in PEP508 format for the `pip install -r ...` command. -The entry `requirements.txt` is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. It may be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path. The contents of a `requirements.txt` file should be formatted like the following example, similar to the standard output from a `pip freeze` command: +The entry `requirements.txt` is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. +It might be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path. +The contents of a `requirements.txt` file should be formatted like the following example, similar to the standard output from a `pip freeze` command: .Python entry [example] diff --git a/downstream/modules/builder/con-system-dependencies.adoc b/downstream/modules/builder/con-system-dependencies.adoc index 4ffd3a5c8..4a6b628f4 100644 --- a/downstream/modules/builder/con-system-dependencies.adoc +++ b/downstream/modules/builder/con-system-dependencies.adoc @@ -1,8 +1,10 @@ [id="con-system-dependencies"] -= System += System dependencies -The `system` entry in the definition points to a link:https://docs.opendev.org/opendev/bindep/latest/readme.html[bindep] requirements file or to an inline list of bindep entries, which install system-level dependencies that are outside of what the collections already include as their dependencies. It can be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or as an absolute path. At a minimum, the the collection(s) must specify necessary requirements for `[platform:rpm]`. +The `system` entry in the definition points to a link:https://docs.opendev.org/opendev/bindep/latest/readme.html[bindep] requirements file or to an inline list of bindep entries, which install system-level dependencies that are outside of what the collections already include as their dependencies. +It can be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or as an absolute path. +At a minimum, the collection(s) must specify necessary requirements for `[platform:rpm]`. To demonstrate this, the following is an example `bindep.txt` file that adds the `libxml2` and `subversion` packages to a container: @@ -15,4 +17,4 @@ subversion [platform:rpm] ---- ==== -Entries from multiple collections are combined into a single file. This is processed by `bindep` and then passed to `dnf`. Only requirements with no profiles or no runtime requirements will be installed to the image. +Entries from multiple collections are combined into a single file. This is processed by `bindep` and then passed to `dnf`. Only requirements with no profiles or no runtime requirements are installed to the image. diff --git a/downstream/modules/builder/con-why-builder.adoc b/downstream/modules/builder/con-why-builder.adoc index 6bf24afe7..7cc5d6891 100644 --- a/downstream/modules/builder/con-why-builder.adoc +++ b/downstream/modules/builder/con-why-builder.adoc @@ -4,4 +4,4 @@ Before {Builder} was developed, {PlatformName} users could run into dependency issues and errors when creating custom virtual environments or containers that included all of the required dependencies installed. -Now, with {Builder}, you can easily create a customizable {ExecEnvName} definition file that specifies the content you want included in your {ExecEnvName} such as Ansible Core, Python, Collections, third-party Python requirements, and system level packages. This allows you to fulfill all of the necessary requirements and dependencies to get jobs running. +Now, with {Builder}, you can easily create a customizable {ExecEnvName} definition file that specifies the content you want included in your {ExecEnvName} such as Ansible Core, Python, Collections, third-party Python requirements, and system level packages. This enables you to fulfill all of the necessary requirements and dependencies to get jobs running. diff --git a/downstream/modules/builder/con-why-ee.adoc b/downstream/modules/builder/con-why-ee.adoc index a5731138c..adc5fcba8 100644 --- a/downstream/modules/builder/con-why-ee.adoc +++ b/downstream/modules/builder/con-why-ee.adoc @@ -1,6 +1,6 @@ [id="con-why-ee"] -= Why use {ExecEnvName}? += Why {ExecEnvName}? With {ExecEnvName}, {PlatformName} has transitioned to a distributed architecture by separating the control plane from the execution plane. Keeping automation execution independent of the control plane results in faster development cycles and improves scalability, reliability, and portability across environments. @@ -10,7 +10,7 @@ In addition to speed, portability, and flexibility, {ExecEnvName} provide the fo * They ensure that automation runs consistently across multiple platforms and make it possible to incorporate system-level dependencies and collection-based content. * They give {PlatformName} administrators the ability to provide and manage automation environments to meet the needs of different teams. -* They allow automation to be easily scaled and shared between teams by providing a standard way of building and distributing the automation environment. -* They enable automation teams to define, build, and update their automation environments themselves. +* They enable automation to be easily scaled and shared between teams by providing a standard way of building and distributing the automation environment. +* {ExecEnvNameStart}s enable automation teams to define, build, and update their automation environments themselves. * {ExecEnvNameStart} provide a common language to communicate automation dependencies. diff --git a/downstream/modules/builder/proc-customize-ee-image.adoc b/downstream/modules/builder/proc-customize-ee-image.adoc index aa879999d..1d0567a93 100644 --- a/downstream/modules/builder/proc-customize-ee-image.adoc +++ b/downstream/modules/builder/proc-customize-ee-image.adoc @@ -2,15 +2,16 @@ = Customizing an existing {ExecEnvName} image -Ansible Controller includes the following default execution environments: +{ControllerNameStart} includes the following default execution environments: -* `Minimal` - Includes the latest Ansible-core 2.15 release along with {Runner}, but does not include collections or other content +* `Minimal` - Includes the latest Ansible-core {CoreInstVersion} release along with {Runner}, but does not include collections or other content * `EE Supported` - Minimal, plus all Red Hat-supported collections and dependencies -While these environments cover many automation use cases, you can add additional items to customize these containers for your specific needs. The following procedure adds the `kubernetes.core` collection to the `ee-minimal` default image: +While these environments cover many automation use cases, you can add additional items to customize these containers for your specific needs. +The following procedure adds the `kubernetes.core` collection to the `ee-minimal` default image: .Procedure -. Log in to `registry.redhat.io` via Podman: +. Log in to `registry.redhat.io` through Podman: + ---- $ podman login -u="[username]" -p="[token/hash]" registry.redhat.io @@ -30,8 +31,10 @@ collections: - kubernetes.core ---- ==== -.. For more information about definition files and their content, see the <>. -. In the {ExecEnvShort} definition file, specify the original `ee-minimal` container's URL and tag in the `EE_BASE_IMAGE` field. In doing so, your final `execution-environment.yml` file will look like the following: ++ +For more information about definition files and their content, see the <>. +. In the {ExecEnvShort} definition file, specify the original `ee-minimal` container's URL and tag in the `EE_BASE_IMAGE` field. +In doing so, your final `execution-environment.yml` file appears similar to the following: + .A customized `execution-environment.yml` file [example] @@ -91,7 +94,8 @@ $ podman tag [username]/new-ee [automation-hub-IP-address]/[username]/new-ee + [NOTE] ===== -You must have `admin` or appropriate container repository permissions for {HubName} to push a container. For more information, see link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/managing_automation_content/index#managing-containers-hub[Manage containers in private automation hub]. +You must have `admin` or appropriate container repository permissions for {HubName} to push a container. +For more information, see link:{URLHubManagingContent}/managing-containers-hub[Manage containers in private automation hub]. ===== + ----- diff --git a/downstream/modules/builder/proc-installing-builder.adoc b/downstream/modules/builder/proc-installing-builder.adoc index e28aa7410..25ae2f72c 100644 --- a/downstream/modules/builder/proc-installing-builder.adoc +++ b/downstream/modules/builder/proc-installing-builder.adoc @@ -3,8 +3,9 @@ = Installing {Builder} .Prerequisites -* You have installed the Podman container runtime. -* You have valid subscriptions attached on the host. Doing so allows you to access the subscription-only resources needed to install `ansible-builder`, and ensures that the necessary repository for `ansible-builder` is automatically enabled. See link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/access_management_and_authentication/index#proc-attaching-subscriptions[Attaching your Red Hat {PlatformNameShort} subscription] for more information. +* You have valid subscriptions attached on the host. +Doing so allows you to access the subscription-only resources needed to install `ansible-builder`, and ensures that the necessary repository for `ansible-builder` is automatically enabled. +See link:{URLCentralAuth}/assembly-gateway-licensing#proc-attaching-subscriptions[Attaching your Red Hat {PlatformNameShort} subscription] for more information. .Procedure diff --git a/downstream/modules/builder/ref-build-args-base-image.adoc b/downstream/modules/builder/ref-build-args-base-image.adoc index f0252009a..d8daaf5fa 100644 --- a/downstream/modules/builder/ref-build-args-base-image.adoc +++ b/downstream/modules/builder/ref-build-args-base-image.adoc @@ -2,20 +2,20 @@ = Build args and base image -The `build_arg_defaults` section of the definition file is a dictionary whose keys can provide default values for arguments to {Builder}. See the following table for a list of values that can be used in `build_arg_defaults`: +The `build_arg_defaults` section of the definition file is a dictionary whose keys can provide default values for arguments to {Builder}. The following table lists values that can be used in `build_arg_defaults`: [cols="a,a"] -|=== +|==== | Value | Description | `ANSIBLE_GALAXY_CLI_COLLECTION_OPTS` | Allows the user to pass arbitrary arguments to the ansible-galaxy CLI during the collection installation phase. For example, the –pre flag to enable the installation of pre-release collections, or -c to disable verification of the server's SSL certificate. | `ANSIBLE_GALAXY_CLI_ROLE_OPTS` -| Allows the user to pass any flags, such as –no-deps, to the role installation. +| Allows the user to pass any flags, such as `–no-deps`, to the role installation. -|=== +|==== -The values given inside `build_arg_defaults` will be hard-coded into the `Containerfile`, so these values will persist if `podman build` is called manually. +The values given inside `build_arg_defaults` are hard-coded into the `Containerfile`, so these values persist if `podman build` is called manually. -NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value will take higher precedence. +NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value takes higher precedence. diff --git a/downstream/modules/builder/ref-content-needed-for-builder.adoc b/downstream/modules/builder/ref-content-needed-for-builder.adoc new file mode 100644 index 000000000..79d8abfe3 --- /dev/null +++ b/downstream/modules/builder/ref-content-needed-for-builder.adoc @@ -0,0 +1,19 @@ +[id="ref-content-needed-for-builder"] + += Content needed for an execution environment + +Ansible-builder is used to create an {ExecEnvShort}. + +An {ExecEnvShort} must contain: + +* Ansible +* Ansible Runner +* Ansible Collections +* Python and system dependencies of: +** modules or plugins in collections +** content in ansible-base +**custom user needs + +Building a new {ExecEnvShort} involves a definition that specifies which content you want to include in your {ExecEnvShort}, such as collections, Python requirements, and system-level packages. +The definition must be a `.yml` file +The content from the output generated from migrating to {ExecEnvShort}s has some of the required data that can be piped to a file or pasted into this definition file. diff --git a/downstream/modules/builder/ref-definition-file-images.adoc b/downstream/modules/builder/ref-definition-file-images.adoc index 8f21512c5..fe644f5af 100644 --- a/downstream/modules/builder/ref-definition-file-images.adoc +++ b/downstream/modules/builder/ref-definition-file-images.adoc @@ -2,9 +2,10 @@ = Images -The `images` section of the definition file identifies the base image. Verification of signed container images is supported with the `podman` container runtime. +The `images` section of the definition file identifies the base image. +Verification of signed container images is supported with the `podman` container runtime. -See the following table for a list of values that you can use in `images`: +The following table shows a list of values that you can use in `images`: [cols="a,a"] |=== @@ -19,4 +20,7 @@ The default image is `registry.redhat.io/ansible-automation-platform-24/ee-minim |=== -NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value will take higher precedence. +[NOTE] +==== +If the same variable is specified in the CLI `--build-arg` flag, the CLI value takes higher precedence. +==== diff --git a/downstream/modules/builder/ref-example-file-to-build-image.adoc b/downstream/modules/builder/ref-example-file-to-build-image.adoc new file mode 100644 index 000000000..cedaeb945 --- /dev/null +++ b/downstream/modules/builder/ref-example-file-to-build-image.adoc @@ -0,0 +1,31 @@ +[id="ref-example-file-to-build-image"] + += Example YAML file to build an image + +The ansible-builder build command takes an execution environment definition as an input. +It outputs the build context necessary for building an execution environment image, and then builds that image. +The image can be re-built with the build context elsewhere, and produces the same result. +By default, the builder searches for a file named `execution-environment.yml` in the current directory. +The following example `execution-environment.yml` file can be used as a starting point: + +---- +--- +version: 3 +dependencies: + galaxy: requirements.yml +The content of requirements.yml: +--- +collections: + - name: awx.awx +To build an execution environment using the preceding files and run the following command: +ansible-builder build +... +STEP 7: COMMIT my-awx-ee +--> 09c930f5f6a +09c930f5f6ac329b7ddb321b144a029dbbfcc83bdfc77103968b7f6cdfc7bea2 +Complete! The build context can be found at: context +---- + +In addition to producing a ready-to-use container image, the build context is preserved. +This can be rebuilt at a different time or location with the tools of your choice, such as docker build or podman build. + diff --git a/downstream/modules/builder/ref-scenario-update-hub-ca-cert.adoc b/downstream/modules/builder/ref-scenario-update-hub-ca-cert.adoc index 5929caa16..5d244089c 100644 --- a/downstream/modules/builder/ref-scenario-update-hub-ca-cert.adoc +++ b/downstream/modules/builder/ref-scenario-update-hub-ca-cert.adoc @@ -14,7 +14,7 @@ Use this example to customize the default definition file to include a CA certif Customizing the CA certificate using `prepend_base` means that the resulting CA configuration appears in all other build stages and the final image, because all other build stages inherit from the base image. ==== ------ +---- additional_build_files: # copy the CA public key into the build context, we will copy and use it in the base image later - src: files/rootCA.crt @@ -32,4 +32,4 @@ options: [galaxy] server_list = automation_hub ------ +---- diff --git a/downstream/modules/builder/ref-scenario-using-authentication-ee.adoc b/downstream/modules/builder/ref-scenario-using-authentication-ee.adoc index 09a0722fd..5dd9c47a1 100644 --- a/downstream/modules/builder/ref-scenario-using-authentication-ee.adoc +++ b/downstream/modules/builder/ref-scenario-using-authentication-ee.adoc @@ -10,6 +10,7 @@ Use the following example to customize the default definition file to pass {HubN * You have created an API token, as in link:{URLHubManagingContent}/managing-cert-valid-content#proc-create-api-token[Retrieving the API token for your Red Hat Certified Collection] and stored it in a secure location, for example in a file named `token.txt`. * Define a build argument that gets populated with the {HubName} API token: ++ ---- export ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN=$(cat ) ---- diff --git a/downstream/modules/platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc b/downstream/modules/platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc index e89869e5c..3bf0d190d 100644 --- a/downstream/modules/platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc +++ b/downstream/modules/platform/con-building-an-execution-environment-in-a-disconnected-environment.adoc @@ -8,20 +8,22 @@ Creating execution environments for {PlatformNameShort} is a common task which works differently in disconnected environments. When building a custom {ExecEnvShort}, the ansible-builder tool defaults to downloading content from the following locations on the internet: -* Red Hat {HubNameStart} ({Console}) or {Galaxy} (galaxy.ansible.com) for any Ansible content collections added to the {ExecEnvShort} image. +* Red Hat {HubNameStart} (`{Console}`) or {Galaxy} (`galaxy.ansible.com`) for any Ansible content collections added to the {ExecEnvShort} image. -* PyPI (pypi.org) for any python packages required as collection dependencies. +* PyPI (`pypi.org`) for any python packages required as collection dependencies. * RPM repositories such as the RHEL or UBI repositories (cdn.redhat.com) for adding or updating RPMs to the {ExecEnvShort} image, if needed. -* registry.redhat.io for access to the base container images. +* `registry.redhat.io` for access to the base container images. Building an {ExecEnvShort} image in a disconnected environment requires mirroring content from these locations. For information about importing collections from {Galaxy} or {HubName} into a {PrivateHubName}, see link:{URLHubManagingContent}/managing-collections-hub#proc-import-collection[Importing an automation content collection in {HubName}] . -Mirrored PyPI content once transferred into the disconnected network can be made available by using a web server or an artifact repository such as Nexus. The RHEL and UBI repository content can be exported from an internet-facing Red Hat Satellite Server, copied into the disconnected environment, then imported into a disconnected Satellite so it is available for building custom {ExecEnvShort}s. See link:{BaseURL}/red_hat_satellite/{SatelliteVers}/html-single/installing_satellite_server_in_a_disconnected_network_environment/index#iss_export_sync_in_an_air_gapped_scenario[ISS Export Sync in an Air-Gapped Scenario] for details. +Mirrored PyPI content once transferred into the disconnected network can be made available by using a web server or an artifact repository. The RHEL and UBI repository content can be exported from an internet-facing Red Hat Satellite Server, copied into the disconnected environment, then imported into a disconnected Satellite so it is available for building custom {ExecEnvShort}s. See link:{BaseURL}/red_hat_satellite/{SatelliteVers}/html-single/installing_satellite_server_in_a_disconnected_network_environment/index#iss_export_sync_in_an_air_gapped_scenario[ISS Export Sync in an Air-Gapped Scenario] for details. -The default base container image, ee-minimal-rhel8, is used to create custom {ExecEnvShort} images and is included with the bundled installer. This image is added to the {PrivateHubName} at install time. If a different base container image such as ee-minimal-rhel9 is required, it must be imported to the disconnected network and added to the {PrivateHubName} container registry. +The default base container image, `ee-minimal-rhel8`, is used to create custom {ExecEnvShort} images and is included with the bundled installer. +This image is added to the {PrivateHubName} at install time. +If a different base container image such as `ee-minimal-rhel9` is required, it must be imported to the disconnected network and added to the {PrivateHubName} container registry. Once all of the prerequisites are available on the disconnected network, the ansible-builder command can be used to create custom {ExecEnvShort} images. diff --git a/downstream/titles/builder/master.adoc b/downstream/titles/builder/master.adoc index a09a01661..55fac0be3 100644 --- a/downstream/titles/builder/master.adoc +++ b/downstream/titles/builder/master.adoc @@ -9,7 +9,7 @@ include::attributes/attributes.adoc[] // Book Title = Creating and using execution environments -Use {ExecEnvshort} builder to create consistent and reproducible containers for your {PlatformName} needs. +Use the {ExecEnvshort} builder (ansible-builder) to create consistent and reproducible containers for your {PlatformName} needs. include::{Boilerplate}[]