Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 3. Configuring build runs

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.

3.1. Configurable fields in build run
Link kopieren

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):

Expand
Table 3.1. Required fields in the BuildRun CR
FieldDescription

apiVersion

Specifies the API version of the resource. For example, shipwright.io/v1beta1.

kind

Specifies the type of the resource. For example, BuildRun.

metadata

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):

Expand
Table 3.2. Optional fields in the BuildRun CR
FieldDescription

spec.build.name

Specifies an existing Build resource instance to use. You cannot use this field with the spec.build.spec field.

spec.build.spec

Specifies an embedded Build resource instance to use. You cannot use this field with the spec.build.name field.

spec.serviceAccount

Indicates the service account to use when building the image.

spec.timeout

Defines a custom timeout. This field value overwrites the value of the spec.timeout field defined in your Build resource.

spec.paramValues

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

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

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

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 used by your build strategy.

spec.nodeSelector

Specifies which nodes Builds should run on.

spec.tolerations

Specifies the tolerations for the Builds pod.

spec.schedulerName

Specifies the scheduler for the Builds pod

Important

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
Link kopieren

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 custom resource (CR) that configures the spec.build.name field: 

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: buildah-buildrun
spec:
  build:
    name: buildah-build
Copy to Clipboard Toggle word wrap

3.3. Build specification definition
Link kopieren

Define a complete build specification into your BuildRun resource using the spec.build.spec field. This builds an image without creating and maintaining a dedicated Build custom resource. The following example shows a BuildRun custom resource (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>
Copy to Clipboard Toggle word wrap

where

<path_to_image>
Specifies the path to the image file.
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
Link kopieren

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 cache value in the BuildRun overrides the cache value 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:
  # ...
Copy to Clipboard Toggle word wrap

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. 
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: <your_buildrun>
  namespace: <your_namespace>
spec:
  build:
    name: <your_build>
  paramValues:
  - name: cache
    value: registry
Copy to Clipboard Toggle word wrap

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.

3.5. Service account definition
Link kopieren

Define a service account in your BuildRun resource to provide access to the secrets referenced by 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
Copy to Clipboard Toggle word wrap

  • spec.serviceAccount:: Defines the name of the generated service account corresponding to the name of the BuildRun resource. You can also set the value to ".generate" to generate the service account during runtime.

    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
Link kopieren

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: Duration a failed build run remains before deletion.
  • retention.ttlAfterSucceeded: Duration a successful build run remains before deletion.

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
Copy to Clipboard Toggle word wrap
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
Link kopieren

Define volumes in your BuildRun custom resource (CR) to override the volumes in the BuildStrategy resource. If a volume isn’t overridden, the build run fails. If both Build and BuildRun override the same volume, the value in BuildRun takes precedence.

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>
Copy to Clipboard Toggle word wrap

where:

<build_name>
Specifies the name of the Buildrun CR.
<buildrun_name>
Specifies the name of the Build CR.
<volume_name>
Specifies the name of the volume of the Build CR.
<configmap_name>
Specifies the name of the ConfigMap of the Build CR.

3.8. Environment variables definition
Link kopieren

You can set environment variables in your BuildRun custom resource (CR). These variables pass information to the build container. You can use literal values or the Kubernetes downward API.

The following example shows how to define 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>"
Copy to Clipboard Toggle word wrap

where:

env.name
Defines the names of the environment variables in the BuildRun CR.
env.value
Defines the values of the environment variables in the BuildRun CR.

The following example shows a BuildRun resource that uses the Kubernetes downward API 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
Copy to Clipboard Toggle word wrap

where:

<pod_name>
Specifies the name of the pod.

The following example shows a BuildRun resource that uses the Kubernetes downward API 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
Copy to Clipboard Toggle word wrap

where:

<my_container>
Specifies the name of the container.

3.9. Build run status
Link kopieren

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: 
$ oc get buildrun buildah-buildrun-mp99r
Copy to Clipboard Toggle word wrap

Example output: 

NAME                    SUCCEEDED   REASON    STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  Unknown     Unknown      1s
Copy to Clipboard Toggle word wrap
True status
A True status indicates that the build completed successfully. The following example shows a BuildRun` with True status: 
$ oc get buildrun buildah-buildrun-mp99r
Copy to Clipboard Toggle word wrap

Example output: 

NAME                   SUCCEEDED     REASON     STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  True        Succeeded      29m       20m
Copy to Clipboard Toggle word wrap

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.

3.9.1. Build run statuses description
Link kopieren

A BuildRun custom resource (CR) can have different statuses during the image building process. Track the state of your build using the status field.

The following table covers the different statuses of a build run:

Expand
Table 3.3. Statuses of a build run
StatusCauseDescription

Unknown

Pending

The BuildRun resource waits for a pod in status Pending.

Unknown

Running

The controller validates and starts the BuildRun.

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

The system detected an incorrectly typed build strategy parameter value. 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
Link kopieren

If a build fails, check the status.failureDetails field in the BuildRun custom resource (CR). This field provides the error message, the reason for the failure, and the specific container or pod where the error occurred. You can see the message and reason for failure only if it is 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
Copy to Clipboard Toggle word wrap
Note

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

3.9.3. Step results in build run status
Link kopieren

After a BuildRun custom resource (CR) 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 CR, 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 CR 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
Copy to Clipboard Toggle word wrap

The following example shows a BuildRun CR with step results for a local source code: 

# ...
status:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    bundle:
      digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7
Copy to Clipboard Toggle word wrap
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
Link kopieren

A build snapshot records the exact configuration used for a specific build run.

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.

3.10. Relationship of build run with Tekton tasks
Link kopieren

A BuildRun uses Tekton TaskRun resources to build your image. The TaskRun follows the steps defined in your build strategy until the build finishes or fails.

When you create a BuildRun, the build controller starts a new TaskRun. The BuildRun resource assigns the task of image construction to this TaskRun. The TaskRun then runs every step defined in your build strategy.

3.11. Build run cancellation
Link kopieren

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: 

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: buildah-buildrun
spec:
  # [...]
  state: "BuildRunCanceled"
Copy to Clipboard Toggle word wrap

3.12. Automatic build run deletion
Link kopieren

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

3.13. Pod configuration
Link kopieren

Configure pod scheduling and placement for Builds by using optional BuildRun Custom Resource (CR) fields.

Use the following fields to configure Builds 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 you define these fields in both the Build and BuildRun CRs, the BuildRun values take priority.

Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red HatNach oben