Changes to builder doc

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]
 

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]
 

downstream/modules/builder/con-about-ee.adoc

@@ -4,13 +4,17 @@
 
 [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
 * Python 3.8-3.11
 * {Runner}
 * Ansible content collections and their dependencies
 * System dependencies
+
+

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.

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.
 
 |===
 

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.
 

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

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]
 ====
 ----

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`:
 
 ====
 ----

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]

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.

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.

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.
 

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 <<assembly-definition-file-breakdown,definition file breakdown section>>.
-. 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 <<assembly-definition-file-breakdown,definition file breakdown section>>.
+. 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].
 =====
 +
 -----

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