buildruns.shipwright.io/v1alpha1) is the build process of a
Build resource definition executed in Kubernetes.
BuildRun resource allows the user to define:
BuildRunname, through which the user can monitor the status of the image construction.
Buildinstance to use during the build construction.
BuildRun is available within a namespace.
The controller watches for:
Buildresource (CRD instance)
TaskRunresource (CRD instance)
When the controller reconciles it:
TaskRunsand updates its parent
SAand sets this with the specify output secret on the
TaskRunand sets a reference to this resource(as a child of the controller).
TaskRun, the controller will update the parent
BuildRun definition supports the following fields:
apiVersion- Specifies the API version, for example
kind- Specifies the Kind type, for example
metadata- Metadata that identify the CRD instance, for example the name of the
spec.buildRef- Specifies an existing
Buildresource instance to use. It cannot be used together with
spec.buildSpec- Specifies an embedded (transient) Build resource to use. It cannot be used together with
spec.serviceAccount- Refers to the SA to use when building the image. (defaults to the
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
spec.paramValues- Refers to a name-value(s) list to specify values for
parametersdefined in the
BuildStrategy. This value overwrites values defined with the same name in the Build.
spec.output.image- Refers to a custom location where the generated image would be pushed. The value will overwrite the
output.imagevalue defined in
Build. ( Note: other properties of the output, for example, the credentials, cannot be specified in the buildRun spec. )
spec.output.credentials.name- Reference an existing secret to get access to the container registry. This secret will be added to the service account along with the ones requested by the
spec.env- Specifies additional environment variables that should be passed to the build container. Overrides any environment variables that are specified in the
Buildresource. The available variables depend on the tool used by the chosen build strategy.
BuildSpec are mutually exclusive. Furthermore, the overrides for
env can only be combined with
buildRef, but not with
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
BuildRef, a complete
BuildSpec can be embedded into the
BuildRun for the build.
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: standalone-buildrun spec: buildSpec: source: url: https://github.com/shipwright-io/sample-go.git contextDir: source-build strategy: kind: ClusterBuildStrategy name: buildpacks-v3 output: image: foo/bar:latest
BuildRun resource can define paramValues for parameters specified in the build strategy. If a value has been provided for a parameter with the same name in the
Build already, then the value from the
BuildRun will have precedence.
For example, the following
BuildRun overrides the value for sleep-time param, which is defined in the a-build
--- apiVersion: shipwright.io/v1alpha1 kind: Build metadata: name: a-build namespace: a-namespace spec: paramValues: - name: cache value: disabled strategy: name: buildkit kind: ClusterBuildStrategy source: ... output: ... --- apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: a-buildrun namespace: a-namespace spec: buildRef: name: a-build paramValues: - name: cache value: registry
See more about paramValues usage in the related Build resource docs.
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. The name of the generated service account is the name of the BuildRun.
Note: When the service account is not defined, the
BuildRun uses the
pipeline service account if it exists in the namespace, and falls back to the
default service account.
Buildrun resource can specify how long a completed BuildRun can exist. Instead of manually cleaning up old BuildRuns, retention parameters provide an alternate method for cleaning up BuildRuns automatically.
As part of the buildrun retention parameters, we have the following fields:
retention.ttlAfterFailed- Specifies the duration for which a failed buildrun can exist.
retention.ttlAfterSucceeded- Specifies the duration for which a successful buildrun can exist.
An example of a user using buildrun TTL parameters.
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buidrun-retention-ttl spec: buildRef: name: build-retention-ttl retention: ttlAfterFailed: 10m ttlAfterSucceeded: 10m
NOTE In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications.
BuildRuns can declare
volumes. They must override
volumes defined by the according
BuildStrategy. If a
overridable then the
BuildRun will eventually fail.
BuildRun that refers to this
Build override the same
volume, one that is defined in the
is the one used eventually.
Volumes follow the declaration of Pod Volumes, so
all the usual
volumeSource types are supported.
Here is an example of
BuildRun object that overrides
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buildrun-name spec: buildRef: name: build-name volumes: - name: volume-name configMap: name: test-config
To cancel a
BuildRun that’s currently executing, update its status to mark it as canceled.
When you cancel a
BuildRun, the underlying
TaskRun is marked as canceled per the Tekton cancel
Example of canceling a
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: # [...] state: "BuildRunCanceled"
We have two controllers that ensure that buildruns can be deleted automatically if required. This is ensured by adding
retention parameters in either the build specifications or the buildrun specifications.
buildrun.spec.retention.ttlAfterFailed: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed.
buildrun.spec.retention.ttlAfterSucceeded: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded.
build.spec.retention.ttlAfterFailed: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed.
build.spec.retention.ttlAfterSucceeded: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded.
build.spec.retention.succeededLimit- Defines number of succeeded BuildRuns for a Build that can exist.
build.spec.retention.failedLimit- Defines number of failed BuildRuns for a Build that can exist.
An example of a
BuildRun that specifies environment variables:
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: buildRef: name: buildpack-nodejs-build-namespaced env: - name: EXAMPLE_VAR_1 value: "example-value-1" - name: EXAMPLE_VAR_2 value: "example-value-2"
Example of a
BuildRun that uses the Kubernetes Downward API to
Pod field as an environment variable:
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: buildRef: name: buildpack-nodejs-build-namespaced env: - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name
Example of a
BuildRun that uses the Kubernetes Downward API to
Container field as an environment variable:
apiVersion: shipwright.io/v1alpha1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: buildRef: name: buildpack-nodejs-build-namespaced env: - name: MEMORY_LIMIT valueFrom: resourceFieldRef: containerName: my-container resource: limits.memory
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
$ 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.
BuildRun resource stores the relevant information regarding the object’s state under
Conditions allow users to quickly understand the resource state without needing to understand resource-specific details.
BuildRun, we use a Condition of the type
Succeeded, which is a well-known type for resources that run to completion.
status.conditions hosts different fields, like
message. Users can expect these fields to be populated with relevant information.
The following table illustrates the different states a BuildRun can have under its
|Status||Reason||CompletionTime is set||Description|
|Unknown||Pending||No||The BuildRun is waiting on a Pod in status Pending.|
|Unknown||Running||No||The BuildRun has been validated and started to perform its work.|
|Unknown||Running||No||The BuildRun has been validated and started to perform its work.|
|Unknown||BuildRunCanceled||No||The user requested the BuildRun to be canceled. This results in the BuildRun controller requesting the TaskRun be canceled. Cancellation has not been done yet.|
|True||Succeeded||Yes||The BuildRun Pod is done.|
|False||Failed||Yes||The BuildRun failed in one of the steps.|
|False||BuildRunTimeout||Yes||The BuildRun timed out.|
|False||UnknownStrategyKind||Yes||The Build specified strategy Kind is unknown. (options: ClusterBuildStrategy or BuildStrategy)|
|False||ClusterBuildStrategyNotFound||Yes||The referenced cluster strategy was not found in the cluster.|
|False||BuildStrategyNotFound||Yes||The referenced namespaced strategy was not found in the cluster.|
|False||SetOwnerReferenceFailed||Yes||Setting ownerreferences from the BuildRun to the related TaskRun failed.|
|False||TaskRunIsMissing||Yes||The BuildRun related TaskRun was not found.|
|False||TaskRunGenerationFailed||Yes||The generation of a TaskRun spec failed.|
|False||MissingParameterValues||Yes||No value has been provided for some parameters that are defined in the build strategy without any default. Values for those parameters must be provided through the Build or the BuildRun.|
|False||RestrictedParametersInUse||Yes||A value for a system parameter was provided. This is not allowed.|
|False||UndefinedParameter||Yes||A value for a parameter was provided that is not defined in the build strategy.|
|False||WrongParameterValueType||Yes||A value was provided for a build strategy parameter using the wrong type. The parameter is defined as |
|False||InconsistentParameterValues||Yes||A value for a parameter contained more than one of |
|False||EmptyArrayItemParameterValues||Yes||An item inside the |
|False||IncompleteConfigMapValueParameterValues||Yes||A value for a parameter contained a |
|False||IncompleteSecretValueParameterValues||Yes||A value for a parameter contained a |
|False||ServiceAccountNotFound||Yes||The referenced service account was not found in the cluster.|
|False||BuildRegistrationFailed||Yes||The related Build in the BuildRun is in a Failed state.|
|False||BuildNotFound||Yes||The related Build in the BuildRun was not found.|
|False||BuildRunCanceled||Yes||The BuildRun and underlying TaskRun were canceled successfully.|
|False||BuildRunNameInvalid||Yes||The defined |
|False||BuildRunNoRefOrSpec||Yes||BuildRun does not have either |
|False||BuildRunAmbiguousBuild||Yes||The defined |
|False||BuildRunBuildFieldOverrideForbidden||Yes||The defined |
|False||PodEvicted||Yes||The BuildRun Pod was evicted from the node it was running on. See API-initiated Eviction and Node-pressure Eviction for more information.|
Note: We heavily rely on the Tekton TaskRun Conditions for populating the BuildRun ones, with some exceptions.
[DEPRECATED] To make it easier for users to understand why did a BuildRun failed, users can infer the pod and container where the failure took place from the
In addition, the
status.conditions hosts a compacted message under the’ message’ field that contains the
kubectl command to trigger and retrieve the logs.
Lastly, users can check the
status.failureDetails field, which includes the same information available in the
as well as a human-readable error message and reason.
The message and reason are only included if the build strategy provides them.
Example of failed BuildRun:
# [...] 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
All git-related operations support error reporting via
status.failureDetails. The following table explains the possible
|Basic authentication has failed. Check your username or password. Note: GitHub requires a personal access token instead of your regular password.|
|The key is invalid for the specified target. Please make sure that the Git repository exists, you have sufficient permissions, and the key is in the right format.|
|The remote revision does not exist. Check the revision specified in your Build.|
|The source repository does not exist, or you have insufficient permissions to access it.|
|You are trying to access a non-existing or private repository without having sufficient permissions to access it via HTTPS.|
|Basic Auth incomplete: Both username and password must be configured.|
|Credential/URL inconsistency: SSH credentials were provided, but the URL is not an SSH Git URL.|
|Credential/URL inconsistency: No SSH credentials provided, but the URL is an SSH Git URL.|
|The specific error reason is unknown. Check the error message for more information.|
After completing a
.status field contains the results (
.status.taskResults) emitted from the
TaskRun steps generated by the
BuildRun controller as part of processing the
BuildRun. These results contain valuable metadata for users, like the image digest or the commit sha of the source code used for building.
The results from the source step will be surfaced to the
.status.sources, and the results from
the output step will be surfaced to the
.status.output field of a
Example of a
BuildRun with surfaced results for
git source (note that the
branchName is only included if the Build does not specify any
# [...] status: buildSpec: # [...] output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default git: commitAuthor: xxx xxxxxx commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde branchName: main
Another example of a
BuildRun with surfaced results for local source code(
# [...] status: buildSpec: # [...] output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default bundle: digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7
Note: The digest and size of the output image are only included if the build strategy provides them. See System results.
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
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
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
During the Reconcile, the
BuildRun controller will generate a new
TaskRun. The controller will embed in the
Task definition the requires
steps to execute during the execution. These
steps are defined in the strategy defined in the
Build resource, either a
ClusterBuildStrategy or a