[build-docs-1.6] RHDEVDOCS-6889: CQA 2.0: Configure

configuring/configuring-build-runs.adoc

@@ -8,12 +8,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-In a `BuildRun` custom resource (CR), you can configure a build run by defining the build reference, build specification, parameter values, service account, output, retention parameters, and volumes to configure a build run. You can also configure build pods by using a `Build` CR.
-
-A `BuildRun` resource is available for use within a namespace.
-
-To configure a build run, create a `BuildRun` resource YAML file and apply it to the {ocp-product-title} cluster.
-
+As a platform engineer, you can configure build runs by defining the build reference, parameters, service account, output settings, retention rules, and volumes in a `BuildRun` custom resource (CR). You can use a `BuildRun` CR to manage how individual builds execute within a namespace on the cluster.
 
 include::modules/ob-configurable-fields-in-build-run.adoc[leveloffset=+1]
 
@@ -51,4 +46,9 @@ include::modules/ob-configuring-pods-in-build-run.adoc[leveloffset=+1]
 
 // [role="_additional-resources"]
 // == Additional resources
+[role="_additional-resources"]
+[id="additional-resources_installing-openshift-builds"]
+== Additional resources
+
+* xref:../work_with_builds/creating-container-images.adoc#creating-container-images[Creating container images]
 

configuring/configuring-build-strategies.adoc

@@ -8,10 +8,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-In a `BuildStrategy` or `ClusterBuildStrategy` custom resource (CR), you can define strategy parameters, system parameters, step resources definitions, annotations, and volumes to configure a build strategy. A `BuildStrategy` resource is available for use within a namespace, and a `ClusterBuildStrategy` resource is available for use throughout the cluster.
-
-To configure a build strategy, create a `BuildStrategy` or `ClusterBuildStrategy` resource YAML file and apply it to the {ocp-product-title} cluster.
-
+As a platform engineer, you can define consistent build strategies by specifying parameters, system settings, resource requirements, annotations, and volumes in `BuildStrategy` or `ClusterBuildStrategy` custom resources (CR). These strategies enable controlled and reusable build execution across the cluster.
 
 include::modules/ob-defining-strategy-parameters.adoc[leveloffset=+1]
 

configuring/configuring-openshift-builds.adoc

@@ -8,12 +8,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-In a `Build` custom resource (CR), you can configure a build by defining the source, build strategy, parameter values, output, retention parameters, and volumes. You can also configure build pods by using a `Build` CR.
-
-A `Build` resource is available for use within a namespace.
-
-To configure a build, create a `Build` resource YAML file and apply it to the {ocp-product-title} cluster.
-
+As a platform engineer, you can define the source, strategy, parameters, outputs, retention rules, and volumes in a `Build` custom resource (CR) to configure builds. A `Build` CR enables consistent build pod configuration and provides a namespace-scoped method for managing build execution on the cluster.
 
 include::modules/ob-configurable-fields-in-build.adoc[leveloffset=+1]
 

modules/ob-automatic-build-run-deletion.adoc

@@ -7,7 +7,9 @@
 = Automatic build run deletion
 
 [role="_abstract"]
-To automatically delete a build run, you can add the following retention parameters in the `build` or `buildrun` specification:
+Automatically manage the lifecycle of build runs by defining retention and TTL parameters.
+
+Add the following retention parameters in the `build` or `buildrun` specification to automatically delete a build run:
 
 * `buildrun` TTL parameters: Ensures that build runs only exist for a defined duration of time after completion.
 ** `buildrun.spec.retention.ttlAfterFailed`: The build run is deleted if the specified time has passed and the build run has failed.

modules/ob-build-run-status.adoc

@@ -7,30 +7,37 @@
 = Build run status
 
 [role="_abstract"]
-The `BuildRun` resource updates whenever the image building status changes, as shown in the following examples:
+Monitor the progress and completion of your image builds by checking the status of the `BuildRun` custom resource (CR).
+A `BuildRun` CR stores status information in the status.conditions field. This field includes the status, the reason for that status, and a descriptive message. For example, a `Succeeded` condition type means the build finished successfully.
+
+The following examples show how to view the status of a specific BuildRun CR.
+
+Unknown status::
+An `Unknown` status indicates the build is still starting or in progress. The following example shows a `BuildRun` with `Unknown` status:
 
-.Example: `BuildRun` with `Unknown` status
 [source,terminal]
 ----
 $ oc get buildrun buildah-buildrun-mp99r
 ----
-.Example output
+Example output:
 [source,terminal]
 ----
 NAME                    SUCCEEDED   REASON    STARTTIME   COMPLETIONTIME
 buildah-buildrun-mp99r  Unknown     Unknown      1s
 ----
 
-.Example: `BuildRun` with `True` status
+True status::
+A `True` status indicates that the build completed successfully. The following example shows a BuildRun` with `True` status:
+
 [source,terminal]
 ----
 $ oc get buildrun buildah-buildrun-mp99r
 ----
-.Example output
+Example output:
 [source,terminal]
 ----
-NAME                   SUCCEEDED   REASON     STARTTIME   COMPLETIONTIME
+NAME                   SUCCEEDED     REASON     STARTTIME   COMPLETIONTIME
 buildah-buildrun-mp99r  True        Succeeded      29m       20m
 ----
 
-A `BuildRun` resource stores the status-related information in the `status.conditions` field. For example, a condition with the type `Succeeded` indicates that resources have successfully completed their operation. The `status.conditions` field includes significant information like status, reason, and message for the `BuildRun` resource.
+A `BuildRun` CR stores the status-related information in the `status.conditions` field. For example, a condition with the type `Succeeded` indicates that resources have successfully completed their operation. The `status.conditions` field includes significant information like status, reason, and message for the `BuildRun` CR.

modules/ob-build-snapshot.adoc

@@ -7,6 +7,6 @@
 = Build snapshot
 
 [role="_abstract"]
-For each build run reconciliation, the `buildSpec` field in the status of the `BuildRun` resource updates if an existing task run is part of that build run. 
+A build snapshot records the exact configuration used for a specific build run.
 
-During this update, a `Build` resource snapshot generates and embeds into the `status.buildSpec` field of the `BuildRun` resource. Due to this, the `buildSpec` field contains an exact  copy of the original `Build` specification, which was used to execute a particular image build. By using the build snapshot, you can see the original `Build` resource configuration.
+When a build run reconciles, the `status.buildSpec` field in the `BuildRun` custom resource (CR) updates. This field stores a complete copy of the original `Build` specification used for that specific image build. You can use this snapshot to verify the settings used during execution, even if the original `Build` CR changes later.

modules/ob-canceling-a-build-run.adoc

@@ -7,10 +7,9 @@
 = Build run cancellation
 
 [role="_abstract"]
-You can cancel an active `BuildRun` instance by setting its state to `BuildRunCanceled`. When you cancel a `BuildRun` instance, the underlying `TaskRun` resource is also marked as canceled.
+To stop an active `BuildRun` resource, set the `state` field of the `BuildRun` resource to `BuildRunCanceled`. Canceling a `BuildRun` also cancels the underlying `TaskRun` resource.
 
 The following example shows a canceled build run for a `BuildRun` resource:
-+
 [source,yaml]
 ----
 apiVersion: shipwright.io/v1beta1

modules/ob-configurable-fields-in-build-run.adoc

@@ -7,7 +7,9 @@
 = Configurable fields in build run
 
 [role="_abstract"]
-You can use the following required and optional fields in your `BuildRun` custom resource (CR):
+Configure a `BuildRun` custom resource (CR) by specifying input parameters, service account, outputs, and lifecycle settings.
+
+The following table describes the required fields in your `BuildRun` custom resource (CR):
 
 .Required fields in the `BuildRun` CR
 [options="header",cols="30%,15%,55%"]
@@ -25,6 +27,8 @@ You can use the following required and optional fields in your `BuildRun` custom
 | Indicates the metadata that identifies the custom resource definition instance. For example, the name of the `BuildRun` resource.
 |===
 
+The following table describes optional fields in your `BuildRun` custom resource (CR):
+
 .Optional fields in the `BuildRun` CR
 [options="header",cols="30%,15%,55%"]
 [cols="1,1"]

modules/ob-configurable-fields-in-build.adoc

@@ -7,7 +7,9 @@
 = Configurable fields in build
 
 [role="_abstract"]
-You can use the following required and optional fields in your `Build` custom resource (CR):
+Configure a `Build` custom resource (CR) by specifying its inputs, execution settings, outputs, and lifecycle behavior. These parameters control the configuration and behavior of a Build CR.
+
+The following table describes the required fields in your `Build` CR:
 
 .Required fields in the `Build` CR
 [options="header",cols="30%,15%,55%"]
@@ -22,38 +24,40 @@ You can use the following required and optional fields in your `Build` custom re
 | Specifies the type of the resource, for example, `Build`.
 
 | `metadata`
-| Denotes the metadata that identifies the custom resource definition instance, for example, the name of the `Build` resource.
+| Specifies the metadata that identifies the custom resource definition instance, for example, the name of the `Build` resource.
 
 | `spec.source`
-| Denotes the location of the source code, for example, a Git repository or source bundle image.
+| Specifies the location of the source code, for example, a Git repository or source bundle image.
 
 | `spec.strategy`
-| Denotes the name and type of the strategy used for the `Build` resource.
+| Specifies the name and type of the strategy used for the `Build` resource.
 
 | `spec.output`
-| Denotes the location where the generated image will be pushed.
+| Specifies the location where the system pushes the generated image.
 
 | `spec.output.pushSecret`
-| Denotes an existing secret to get access to the container registry.
+| Specifies an existing secret to gain access to the container registry.
 |===
 
+The following table describes the optional fields in your `Build` CR:
+
 .Optional fields in the `Build` CR
 [options="header",cols="30%,15%,55%"]
 [cols="1,1"]
 |===
 | Field | Description
 
 | `spec.paramValues`
-| Denotes a name-value list to specify values for parameters defined in the build strategy.
+| Specifies a name-value list to set values for parameters defined in the build strategy.
 
 | `spec.timeout`
 | Defines a custom timeout. The default value is ten minutes. You can overwrite this field value in your `BuildRun` resource.
 
 | `spec.output.annotations`
-| Denotes a list of key-value pairs that you can use to annotate the output image.
+| Specifies a list of key-value pairs that you can use to annotate the output image.
 
 | `spec.output.labels`
-| Denotes a list of key-value pairs that you can use to label the output image.
+| Specifies a list of key-value pairs that you can use to label the output image.
 
 | `spec.env`
 | Defines additional environment variables that you can pass to the build container. The available variables depend on the tool used by your build strategy.

modules/ob-configuring-pods-in-build-run.adoc

@@ -7,16 +7,17 @@
 = Pod configuration
 
 [role="_abstract"]
-You can use the following optional `BuildRun` CR fields to configure {builds-shortname} pods:
+Configure pod scheduling and placement for {builds-shortname} by using optional `BuildRun` Custom Resource (CR) fields.
 
-* The `spec.tolerations` field specifies the tolerations for the {builds-shortname} pod with the following limitation:
-+
-** Only the `NoSchedule` taint effect is supported.
-+
-* The `spec.nodeSelector` field specifies which nodes the {builds-shortname} pod should run on.
-* The `spec.schedulerName` field specifies the scheduler for the {builds-shortname} pod.
+Use the following fields to configure {builds-shortname} pods:
+
+* `spec.tolerations`: Specifies pod tolerations. Note: Only the NoSchedule taint effect is supported.
+
+* `spec.nodeSelector`: Specifies the nodes where the pod must run.
+
+* `spec.schedulerName`: Specifies a custom scheduler for the pod.
 
 [NOTE]
 ====
-If the fields are specified in both the `Build` and `BuildRun` CRs, the values in `BuildRun` CR are used.
-====
+If you define these fields in both the `Build` and `BuildRun` CRs, the `BuildRun` values take priority.
+====

modules/ob-configuring-pods-in-build.adoc

@@ -7,7 +7,9 @@
 = Pod configuration
 
 [role="_abstract"]
-You can use the following optional `Build` CR fields to configure {builds-shortname} pods:
+Configure pod scheduling and placement for {builds-shortname} by using optional `BuildRun` Custom Resource (CR) fields
+
+Use the following optional `Build` CR fields to configure {builds-shortname} pods:
 
 * The `spec.tolerations` field specifies the tolerations for the {builds-shortname} pod with the following limitation:
 +
@@ -18,6 +20,6 @@ You can use the following optional `Build` CR fields to configure {builds-shortn
 
 [NOTE]
 ====
-If the fields are specified in both the `Build` and `BuildRun` CRs, the values in `BuildRun` CR are used.
+If you define these fields in the Build and BuildRun CRs, the BuildRun values take priority.
 ====
 

modules/ob-defining-annotations.adoc

@@ -7,12 +7,12 @@
 = Annotations definition
 
 [role="_abstract"]
-You can define annotations for a build strategy or a cluster build strategy like for any other Kubernetes object. The build strategy first propagates annotations to the `TaskRun` resource. Then, Tekton propagates them to the pod.
+Define annotations for a `BuildStrategy` or `ClusterBuildStrategy` in the same way as for any Kubernetes object. The build strategy passes these annotations to the `TaskRun` resource. Then, Tekton passes them to the pod.
 
 You can use annotations for the following purposes:
 
-* To limit the network bandwidth the pod is allowed to use, the `kubernetes.io/ingress-bandwidth` and `kubernetes.io/egress-bandwidth` annotations are defined in the Kubernetes network traffic shaping feature.
-* To define the AppArmor profile of a container, the `container.apparmor.security.beta.kubernetes.io/<container_name>` annotation is used.
+* Network bandwidth: Use `kubernetes.io/ingress-bandwidth` or `kubernetes.io/egress-bandwidth` to limit the network bandwidth.
+* Security profiles: Use `container.apparmor.security.beta.kubernetes.io/<container_name>` to define AppArmor profiles of a container.
 
 The following example shows the usage of annotations in a build strategy:
 
@@ -29,7 +29,7 @@ spec:
   # ...
 ----
 
-The following annotations are not propagated:
+The following annotations are not passed to resources:
 
 * `kubectl.kubernetes.io/last-applied-configuration`
 * `clusterbuildstrategy.shipwright.io/*`

modules/ob-defining-param-values-in-build-run.adoc

@@ -7,9 +7,9 @@
 = Parameter values definition for a build run
 
 [role="_abstract"]
-You can specify values for the build strategy parameters in your `BuildRun` CR. If you have provided a value for a parameter that is also defined in the `Build` resource with the same name, then the value defined in the `BuildRun` resource takes priority.
+You can define values for build strategy parameters in your BuildRun custom resource (CR). Values set in the BuildRun resource override any values with the same name in the Build resource.
 
-In the following example, the value of the `cache` parameter in the `BuildRun` resource overrides the value of the `cache` parameter, which is defined in the `Build` resource:
+In the following example, the `cache` value in the `BuildRun` overrides the `cache` value in the `Build` resource:
 
 [source,yaml]
 ----
@@ -30,6 +30,11 @@ spec:
   output:
   # ...
 ----
+where
+
+`<your_build>`:: Specifies the name of the `Build` CR.
+`<your_namespace>`:: Specifies the namespace of the `Build` CR.
+`<your_strategy>`:: Specifies the strategy used for the `Build` CR.
 
 [source,yaml]
 ----
@@ -45,3 +50,8 @@ spec:
   - name: cache
     value: registry
 ----
+where
+
+`<your_buildrun>`:: Specifies the name of the `Buildrun` CR.
+`<your_namespace>`:: Specifies the namespace of the `Buildrun` CR.
+`<your_build>`:: Specifies the name of the `Build`.

modules/ob-defining-param-values.adoc

@@ -7,18 +7,17 @@
 = Parameter values definition for a build
 
 [role="_abstract"]
-You can specify values for the build strategy parameters in your `Build` CR. By specifying parameter values, you can control how the steps of the build strategy work. You can also overwrite the values in the `BuildRun` resource. 
-
-For all parameters, you must specify values either directly or by using reference keys from config maps or secrets. 
+You can set build strategy parameters in your `Build` custom resource (CR). These settings control how your build runs. For every parameter, you must provide a value. You can provide the values directly or reference keys in `ConfigMaps` or `Secrets`. 
 
 [NOTE]
-==== 
-The usage of the parameter in the build strategy steps limits the usage of config maps and secrets. You can only use config maps and secrets if the parameter is used in the command, argument, or environment variable.
 ====
+You can only use `ConfigMaps` or `Secrets` if the parameter appears in a command, argument, or environment variable in the build strategy.
+====
+
+The following are the requirements of using parameters values definition for a build:
 
-When using the `paramValues` field in your `Build` CR, avoid the following scenarios:
+* Mapping: Every `spec.paramValues` name must match a parameter defined in the `BuildStrategy` CR.
 
-* Specifying a `spec.paramValues` name that does not match one of the `spec.parameters` defined in the `BuildStrategy` CR.
-* Specifying a `spec.paramValues` name that collides with the Shipwright reserved parameters. These parameters include `BUILDER_IMAGE`, `CONTEXT_DIR`, and any name starting with `shp-`.
+* Reserved names: Do not use reserved names like `BUILDER_IMAGE`, `CONTEXT_DIR`, or any name starting with `shp-`.
 
-Also, ensure that you understand the content of your strategy before defining the `paramValues` field in the `Build` CR.
+* Resources: You can only use `ConfigMaps` or `Secrets` if the parameter is used in a command, argument, or environment variable.

modules/ob-defining-retention-parameters-in-build-run.adoc

@@ -7,13 +7,13 @@
 = Retention parameters definition for a build run
 
 [role="_abstract"]
-You can specify the duration for which a completed build run can exist in your `BuildRun` resource. Retention parameters provide a way to clean your `BuildRun` instances automatically. You can set the value of the following retention parameters in your `BuildRun` CR:
+Use retention parameters in your `BuildRun` custom resource (CR) to automatically delete completed build runs. In your `BuildRun` custom resource (CR), use the following retention parameters:
 
-* `retention.ttlAfterFailed`: Specifies the duration for which a failed build run can exist
-* `retention.ttlAfterSucceeded`: Specifies the duration for which a successful build run can exist
+* `retention.ttlAfterFailed`: Duration a failed build run remains before deletion.
 
-The following example shows how to define retention parameters in your `BuildRun` CR:
+* `retention.ttlAfterSucceeded`: Duration a successful build run remains before deletion.
 
+The following example shows how to define retention parameters in your `BuildRun` CR:
 [source,yaml]
 ----
 apiVersion: shipwright.io/v1beta1
@@ -27,8 +27,6 @@ spec:
     ttlAfterFailed: 10m
     ttlAfterSucceeded: 10m
 ----
-
-
 [NOTE]
 ====
 If you have defined a retention parameter in both `BuildRun` and `Build` CRs, the value defined in the `BuildRun` CR overrides the value of the retention parameter defined in the `Build` CR.