Configuring build runs | Configure | builds for Red Hat OpenShift 1.2

Configurable fields in build run
Build reference definition
Build specification definition
Parameter values definition for a build run
Service account definition
Retention parameters definition for a build run
Volumes definition for a build run
Environment variables definition
Build run status
Relationship of build run with Tekton tasks
Build run cancellation
Automatic build run deletion

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.

Configurable fields in build run

You can use the following fields in your BuildRun custom resource (CR):

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

You cannot use the spec.build.name and spec.build.spec fields together in the same CR because they are mutually exclusive.

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

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>

You cannot use the spec.build.name and spec.build.spec fields together in the same CR because they are mutually exclusive.

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

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.

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.

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

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.

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>

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

Build run status

The BuildRun resource updates whenever the image building status changes, as shown in the following examples:

Example: BuildRun with Unknown status

$ oc get buildrun buildah-buildrun-mp99r
NAME                    SUCCEEDED   REASON    STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  Unknown     Unknown      1s

Example: BuildRun with True status

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

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

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

The status.failureDetails field also provides error details for all operations related to Git.

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

You get to see the digest and size of the output image only if it is defined in your build strategy.

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.

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.

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"

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.