Chapter 3. Configuring build runs In a BuildRun custom resource (CR), you can define the build reference, build specification, parameter values, service account, output, retention parameters, and volumes to configure a build run. A BuildRun resource is available for use within a namespace. For configuring a build run, create a BuildRun resource YAML file and apply it to the OpenShift Container Platform cluster. 3.1. Configurable fields in build run You can use the following fields in your BuildRun custom resource (CR): Table 3.1. Fields in the BuildRun CR Field Presence Description apiVersion Required Specifies the API version of the resource. For example, shipwright.io/v1beta1 . kind Required Specifies the type of the resource. For example, BuildRun . metadata Required Indicates the metadata that identifies the custom resource definition instance. For example, the name of the BuildRun resource. spec.build.name Optional Specifies an existing Build resource instance to use. You cannot use this field with the spec.build.spec field. spec.build.spec Optional Specifies an embedded Build resource instance to use. You cannot use this field with the spec.build.name field. spec.serviceAccount Optional Indicates the service account to use when building the image. spec.timeout Optional Defines a custom timeout. This field value overwrites the value of the spec.timeout field defined in your Build resource. spec.paramValues Optional Indicates a name-value list to specify values for parameters defined in the build strategy. The parameter value overwrites the value of the parameter that is defined with the same name in your Build resource. spec.output.image Optional Indicates a custom location where the generated image will be pushed. This field value overwrites the value of the output.image field defined in your Build resource. spec.output.pushSecret Optional Indicates an existing secret to get access to the container registry. This secret will be added to the service account along with other secrets requested by the Build resource. spec.env Optional Defines additional environment variables that you can pass to the build container. This field value overrides any environment variables that are specified in the Build resource. The available variables depend on the tool that is used by your build strategy. Note You cannot use the spec.build.name and spec.build.spec fields together in the same CR because they are mutually exclusive. 3.2. Build reference definition You can configure the spec.build.name field in your BuildRun resource to reference a Build resource that indicates an image to build. The following example shows a BuildRun CR that configures the spec.build.name field: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build 3.3. Build specification definition You can embed a complete build specification into your BuildRun resource using the spec.build.spec field. By embedding specifications, you can build an image without creating and maintaining a dedicated Build custom resource. The following example shows a BuildRun CR that configures the spec.build.spec field: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: standalone-buildrun spec: build: spec: source: git: url: https://github.com/shipwright-io/sample-go.git contextDir: source-build strategy: kind: ClusterBuildStrategy name: buildah output: image: <path_to_image> Note You cannot use the spec.build.name and spec.build.spec fields together in the same CR because they are mutually exclusive. 3.4. Parameter values definition for a build run 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. 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: apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: cache value: disabled strategy: name: <your_strategy> kind: ClusterBuildStrategy source: # ... output: # ... apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <your_buildrun> namespace: <your_namespace> spec: build: name: <your_build> paramValues: - name: cache value: registry 3.5. Service account definition You can define a service account in your BuildRun resource. The service account hosts all secrets referenced in your Build resource, as shown in the following example: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build serviceAccount: pipeline 1 1 You can also set the value of the spec.serviceAccount field to ".generate" to generate the service account during runtime. The name of the generated service account corresponds with the name of the BuildRun resource. Note When you do not define the service account, the BuildRun resource uses the pipeline service account if it exists in the namespace. Otherwise, the BuildRun resource uses the default service account. 3.6. Retention parameters definition for a build run 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: 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 The following example shows how to define retention parameters in your BuildRun CR: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buidrun-retention-ttl spec: build: name: build-retention-ttl retention: 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. 3.7. Volumes definition for a build run You can define volumes in your BuildRun CR. The defined volumes override the volumes specified in the BuildStrategy resource. If a volume is not overridden, then the build run fails. In case the Build and BuildRun resources override the same volume, the volume defined in the BuildRun resource is used for overriding. The following example shows a BuildRun CR that uses the volumes field: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <buildrun_name> spec: build: name: <build_name> volumes: - name: <volume_name> configMap: name: <configmap_name> 3.8. Environment variables definition You can use environment variables in your BuildRun CR based on your needs. The following example shows how to define environment variables: Example: Defining a BuildRun resource with environment variables apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <example_var_1> value: "<example_value_1>" - name: <example_var_2> value: "<example_value_2>" The following example shows a BuildRun resource that uses the Kubernetes downward API to expose a pod as an environment variable: Example: Defining a BuildRun resource to expose a pod as an environment variable apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <pod_name> valueFrom: fieldRef: fieldPath: metadata.name The following example shows a BuildRun resource that uses the Kubernetes downward API to expose a container as an environment variable: Example: Defining a BuildRun resource to expose a container as an environment variable apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: MEMORY_LIMIT valueFrom: resourceFieldRef: containerName: <my_container> resource: limits.memory 3.9. Build run status The BuildRun resource updates whenever the image building status changes, as shown in the following examples: Example: BuildRun with Unknown status USD oc get buildrun buildah-buildrun-mp99r NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME buildah-buildrun-mp99r Unknown Unknown 1s Example: BuildRun with True status USD oc get buildrun buildah-buildrun-mp99r 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. 3.9.1. Build run statuses description A BuildRun custom resource (CR) can have different statuses during the image building process. The following table covers the different statuses of a build run: Table 3.2. Statuses of a build run Status Cause Description Unknown Pending The BuildRun resource waits for a pod in status Pending . Unknown Running The BuildRun resource has been validated and started to perform its work. Unknown BuildRunCanceled The user has requested to cancel the build run. This request triggers the build run controller to make a request for canceling the related task runs. Cancellation is still under process when this status is present. True Succeeded The pod for the BuildRun resource is created. False Failed The BuildRun resource is failed in one of the steps. False BuildRunTimeout The execution of the BuildRun resource is timed out. False UnknownStrategyKind The strategy type defined in the Kind field is unknown. You can define these strategy types: ClusterBuildStrategy and BuildStrategy . False ClusterBuildStrategyNotFound The referenced cluster-scoped strategy was not found in the cluster. False BuildStrategyNotFound The referenced namespace-scoped strategy was not found in the cluster. False SetOwnerReferenceFailed Setting the ownerReferences field from the BuildRun resource to the related TaskRun resource failed. False TaskRunIsMissing The TaskRun resource related to the BuildRun resource was not found. False TaskRunGenerationFailed The generation of a TaskRun specification has failed. False MissingParameterValues You have not provided any value for some parameters that are defined in the build strategy without any default. You must provide the values for those parameters in the Build or the BuildRun CR. False RestrictedParametersInUse A value for a system parameter was provided, which is not allowed. False UndefinedParameter A value for a parameter was provided that is not defined in the build strategy. False WrongParameterValueType A value was provided for a build strategy parameter with the wrong type. For example, if the parameter is defined as an array or a string in the build strategy, you must provide a set of values or a direct value accordingly. False InconsistentParameterValues A value for a parameter contained more than one of these values: value , configMapValue , and secretValue . You must provide only one of the mentioned values to maintain consistency. False EmptyArrayItemParameterValues An item inside the values of an array parameter contained none of these values: value , configMapValue , and secretValue . You must provide only one of the mentioned values as null array items are not allowed. False IncompleteConfigMapValueParameterValues A value for a parameter contained a configMapValue value where the name or the value field was empty. You must specify the empty field to point to an existing config map key in your namespace. False IncompleteSecretValueParameterValues A value for a parameter contained a secretValue value where the name or the value field was empty. You must specify the empty field to point to an existing secret key in your namespace. False ServiceAccountNotFound The referenced service account was not found in the cluster. False BuildRegistrationFailed The referenced build in the BuildRun resource is in a Failed state. False BuildNotFound The referenced build in the BuildRun resource was not found. False BuildRunCanceled The BuildRun and related TaskRun resources were canceled successfully. False BuildRunNameInvalid The defined build run name in the metadata.name field is invalid. You must provide a valid label value for the build run name in your BuildRun CR. False BuildRunNoRefOrSpec The BuildRun resource does not have either the spec.build.name or spec.build.spec field defined. False BuildRunAmbiguousBuild The defined BuildRun resource uses both the spec.build.name and spec.build.spec fields. Only one of the parameters is allowed at a time. False BuildRunBuildFieldOverrideForbidden The defined spec.build.name field uses an override in combination with the spec.build.spec field, which is not allowed. Use the spec.build.spec field to directly specify the respective value. False PodEvicted The build run pod was evicted from the node it was running on. 3.9.2. Failed build runs When a build run fails, you can check the status.failureDetails field in your BuildRun CR to identify the exact point where the failure happened in the pod or container. The status.failureDetails field includes an error message and a reason for the failure. You only see the message and reason for failure if they are defined in your build strategy. The following example shows a failed build run: # ... status: # ... failureDetails: location: container: step-source-default pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr message: The source repository does not exist, or you have insufficient permission to access it. reason: GitRemotePrivate Note The status.failureDetails field also provides error details for all operations related to Git. 3.9.3. Step results in build run status After a BuildRun resource completes its execution, the .status field contains the .status.taskResults result emitted from the steps generated by the build run controller. The result includes the image digest or the commit SHA of the source code that is used for building the image. In a BuildRun resource, the .status.sources field contains the result from the execution of source steps and the .status.output field contains the result from the execution of output steps. The following example shows a BuildRun resource with step results for a Git source: Example: A BuildRun resource with step results for a Git source # ... status: buildSpec: # ... output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default git: commitAuthor: xxx xxxxxx commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde branchName: main The following example shows a BuildRun resource with step results for a local source code: Example: A BuildRun resource with step results for a local source code # ... status: buildSpec: # ... output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default bundle: digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7 Note You get to see the digest and size of the output image only if it is defined in your build strategy. 3.9.4. Build snapshot 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. 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. 3.10. Relationship of build run with Tekton tasks The BuildRun resource delegates the task of image construction to the Tekton TaskRun resource, which runs all steps until either the completion of the task, or a failure occurs in the task. During the build run reconciliation, the build run controller generates a new TaskRun resource. The controller embeds the required steps for a build run execution in the TaskRun resource. The embedded steps are defined in your build strategy. 3.11. Build run cancellation 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. The following example shows a canceled build run for a BuildRun resource: apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: # [...] state: "BuildRunCanceled" 3.12. Automatic build run deletion To automatically delete a build run, you can add the following retention parameters in the build or buildrun specification: 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. buildrun.spec.retention.ttlAfterSucceeded : The build run is deleted if the specified time has passed and the build run has succeeded. build TTL parameters: Ensures that build runs for a build only exist for a defined duration of time after completion. build.spec.retention.ttlAfterFailed : The build run is deleted if the specified time has passed and the build run has failed for the build. build.spec.retention.ttlAfterSucceeded : The build run is deleted if the specified time has passed and the build run has succeeded for the build. build limit parameters: Ensures that only a limited number of succeeded or failed build runs can exist for a build. build.spec.retention.succeededLimit : Defines the number of succeeded build runs that can exist for the build. build.spec.retention.failedLimit : Defines the number of failed build runs that can exist for the build.

Commands:
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: standalone-buildrun spec: build: spec: source: git: url: https://github.com/shipwright-io/sample-go.git contextDir: source-build strategy: kind: ClusterBuildStrategy name: buildah output: image: <path_to_image>
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: cache value: disabled strategy: name: <your_strategy> kind: ClusterBuildStrategy source: # output: #
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <your_buildrun> namespace: <your_namespace> spec: build: name: <your_build> paramValues: - name: cache value: registry
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build serviceAccount: pipeline 1
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buidrun-retention-ttl spec: build: name: build-retention-ttl retention: ttlAfterFailed: 10m ttlAfterSucceeded: 10m
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <buildrun_name> spec: build: name: <build_name> volumes: - name: <volume_name> configMap: name: <configmap_name>
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <example_var_1> value: "<example_value_1>" - name: <example_var_2> value: "<example_value_2>"
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <pod_name> valueFrom: fieldRef: fieldPath: metadata.name
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: MEMORY_LIMIT valueFrom: resourceFieldRef: containerName: <my_container> resource: limits.memory
oc get buildrun buildah-buildrun-mp99r NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME buildah-buildrun-mp99r Unknown Unknown 1s
oc get buildrun buildah-buildrun-mp99r NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME buildah-buildrun-mp99r True Succeeded 29m 20m
status: # failureDetails: location: container: step-source-default pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr message: The source repository does not exist, or you have insufficient permission to access it. reason: GitRemotePrivate
status: buildSpec: # output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default git: commitAuthor: xxx xxxxxx commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde branchName: main
status: buildSpec: # output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default bundle: digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: # [...] state: "BuildRunCanceled"