• Overview
• BuildRun Controller
• Configuring a BuildRun
  • Defining the BuildRef
  • Defining the ServiceAccount
• BuildRun Status
  • Understanding the state of a BuildRun
  • Understanding failed BuildRuns
• Relationship with Tekton Tasks

The resource BuildRun (buildruns.dev/v1alpha1) is the build process of a Build resource definition which is executed in Kubernetes.

A BuildRun resource allows the user to define:

• The BuildRun name, through which the user can monitor the status of the image construction.
• A referenced Build instance to use during the build construction.
• A service account for hosting all related secrets in order to build the image.

A BuildRun is available within a namespace.

The controller watches for:

• Updates on a Build resource (CRD instance)
• Updates on a TaskRun resource (CRD instance)

When the controller reconciles it:

• Looks for any existing owned TaskRuns and update its parent BuildRun status.
• Retrieves the specified SA and sets this with the specify output secret on the Build resource.
• Generates a new tekton TaskRun if it does not exist, and set a reference to this resource(as a child of the controller).
• On any subsequent updates on the TaskRun, the parent BuildRun resource instance will be updated.

The BuildRun definition supports the following fields:

• Required:

  • apiVersion - Specifies the API version, for example shipwright.io/v1alpha1.
  • kind - Specifies the Kind type, for example BuildRun.
  • metadata - Metadata that identify the CRD instance, for example the name of the BuildRun.
  • spec.buildRef - Specifies an existing Build resource instance to use.

• Optional:

  • spec.serviceAccount - Refers to the SA to use when building the image. (defaults to the default SA)
  • spec.timeout - Defines a custom timeout. The value needs to be parsable by ParseDuration, for example 5m. The value overwrites the value that is defined in the Build.
  • spec.output.image - Refers to a custom location where the generated image would be pushed. The value will overwrite the output.image value which is defined in Build. ( Note: other properties of the output, for example, the credentials cannot be specified in the buildRun spec. )

A BuildRun resource can reference a Build resource, that indicates what image to build. For example:

apiVersion: shipwright.io/v1alpha1
kind: BuildRun
metadata:
  name: buildpack-nodejs-buildrun-namespaced
spec:
  buildRef:
    name: buildpack-nodejs-build-namespaced

A BuildRun resource can define a serviceaccount to use. Usually this SA will host all related secrets referenced on the Build resource, for example:

apiVersion: shipwright.io/v1alpha1
kind: BuildRun
metadata:
  name: buildpack-nodejs-buildrun-namespaced
spec:
  buildRef:
    name: buildpack-nodejs-build-namespaced
  serviceAccount:
    name: pipeline

You can also use set the spec.serviceAccount.generate path to true. This will generate the service account during runtime for you.

Note: When the SA is not defined, the BuildRun will default to the default SA in the namespace.

The BuildRun resource is updated as soon as the current image building status changes:

$ kubectl get buildrun buildpacks-v3-buildrun
NAME                    SUCCEEDED   REASON    MESSAGE   STARTTIME   COMPLETIONTIME
buildpacks-v3-buildrun  Unknown     Pending   Pending   1s

And finally:

$ kubectl get buildrun buildpacks-v3-buildrun
NAME                    SUCCEEDED   REASON      MESSAGE                              STARTTIME   COMPLETIONTIME
buildpacks-v3-buildrun  True        Succeeded   All Steps have completed executing   4m28s       16s

The above allows users to get an overview of the building mechanism state.

A BuildRun resource stores the relevant information regarding the state of the object under Status.Conditions.

Conditions allow users to easily understand the resource state, without needing to understand resource-specific details.

For the BuildRun we use a Condition of the type Succeeded, which is a well-known type for resources that run to completion.

The Status.Conditions hosts different fields, like Status, Reason and Message. Users can expect this fields to be populated with relevant information.

The following table illustrates the different states a BuildRun can have under its Status.Conditions:

Note: We heavily rely on the Tekton TaskRun Conditions for populating the BuildRun ones, with some exceptions.

To make it easier for users to understand why did a BuildRun failed, users can infer from the Status.FailedAt field, the pod and container where the failure took place.

In addition, the Status.Conditions will host under the Message field a compacted message containing the kubectl command to trigger, in order to retrieve the logs.

For every BuildRun controller reconciliation, the buildSpec in the Status of the BuildRun is updated if an existing owned TaskRun is present. During this update, a Build resource snapshot is generated and embedded into the status.buildSpec path of the BuildRun. A buildSpec is just a copy of the original Build spec, from where the BuildRun executed a particular image build. The snapshot approach allows developers to see the original Build configuration.

The BuildRun resource abstracts the image construction by delegating this work to the Tekton Pipeline TaskRun. Compared to a Tekton Pipeline Task, a TaskRun runs all steps until completion of the Task or until a failure occurs in the Task.

The BuildRun controller during the Reconcile will generate a new TaskRun. During the execution, the controller will embed in the TaskRun Task definition the requires steps to execute. These steps are define in the strategy defined in the Build resource, either a ClusterBuildStrategy or a BuildStrategy.