Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 3. Configuring build runs

In a BuildRun custom resource (CR), you can configure a build run by defining the build reference, build specification, parameter values, service account, output, retention parameters, and volumes to configure a build run. You can also configure build pods by using a Build CR.

A BuildRun resource is available for use within a namespace.

To configure 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
Copier lien

You can use the following required and optional 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.

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
Copier lien

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

3.3. Build specification definition
Copier lien

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

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

3.5. Service account definition
Copier lien

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

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
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
Copier lien

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

3.8. Environment variables definition
Copier lien

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

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

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

3.9. Build run status
Copier lien

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

Example: BuildRun with True status

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

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
Copier lien

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:

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 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
Copier lien

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
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
Copier lien

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

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
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
Copier lien

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
Copier lien

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
Copier lien

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

3.12. Automatic build run deletion
Copier lien

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.

3.13. Pod configuration
Copier lien

You can use the following optional BuildRun CR fields to configure Builds pods:

  • The spec.tolerations field specifies the tolerations for the Builds pod with the following limitation:

    • Only the NoSchedule taint effect is supported.
  • The spec.nodeSelector field specifies which nodes the Builds pod should run on.
  • The spec.schedulerName field specifies the scheduler for the Builds pod.
Note

If the fields are specified in both the Build and BuildRun CRs, the values in BuildRun CR are used.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat