Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

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

Chapter 1. Configuring Builds

As a platform engineer, you can define the source, strategy, parameters, outputs, retention rules, and volumes in a Build custom resource (CR) to configure builds. A Build CR enables consistent build pod configuration and provides a namespace-scoped method for managing build execution on the cluster.

1.1. Configurable fields in build
Link kopieren

Configure a Build custom resource (CR) by specifying its inputs, execution settings, outputs, and lifecycle behavior. These parameters control the configuration and behavior of a Build CR.

The following table describes the required fields in your Build CR:

Expand
Table 1.1. Required fields in the Build CR
FieldDescription

apiVersion

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

kind

Specifies the type of the resource, for example, Build.

metadata

Specifies the metadata that identifies the custom resource definition instance, for example, the name of the Build resource.

spec.source

Specifies the location of the source code, for example, a Git repository or source bundle image.

spec.strategy

Specifies the name and type of the strategy used for the Build resource.

spec.output

Specifies the location where the system pushes the generated image.

spec.output.pushSecret

Specifies an existing secret to gain access to the container registry.

The following table describes the optional fields in your Build CR:

Expand
Table 1.2. Optional fields in the Build CR
FieldDescription

spec.paramValues

Specifies a name-value list to set values for parameters defined in the build strategy.

spec.timeout

Defines a custom timeout. The default value is ten minutes. You can overwrite this field value in your BuildRun resource.

spec.output.annotations

Specifies a list of key-value pairs that you can use to annotate the output image.

spec.output.labels

Specifies a list of key-value pairs that you can use to label the output image.

spec.env

Defines additional environment variables that you can pass to the build container. The available variables depend on the tool used by your build strategy.

spec.retention.ttlAfterFailed

Specifies the duration for which a failed build run can exist.

spec.retention.ttlAfterSucceeded

Specifies the duration for which a successful build run can exist.

spec.retention.failedLimit

Specifies the number of failed build runs that can exist.

spec.retention.succeededLimit

Specifies the number of successful build runs that can exist.

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

1.2. Source definition
Link kopieren

Configure the source code location for your build in the Build custom resource (CR).

The following source fields specify how the build accesses the Git repository and selects the source content:

  • source.git.url: The Git repository location.
  • source.git.cloneSecret: The secret containing SSH keys for private repositories.
  • source.git.revision: The specific commit, tag, or branch (defaults to the default branch).
  • source.contextDir: The subdirectory containing the source code.

The build controller does not validate the Git repository by default. To enable validation, set shipwright.io/verify.repository annotation to true in your Build CR, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
  annotations:
    build.shipwright.io/verify.repository: "true"
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
Copy to Clipboard Toggle word wrap

The build controller validates the existence of a Git repository in the following scenarios:

  • When you use the endpoint URL with an HTTP or HTTPS protocol.
  • When you have defined an SSH protocol, such as git@, but not a referenced secret, such as source.git.cloneSecret.

The following configurations show how you can configure a build with different set of source inputs.

Configure a build with credentials

Configure a build to access a private Git repository by referencing a secret that contains the repository credentials, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-build
spec:
  source:
    git:
      url: https://github.com/sclorg/nodejs-ex
      cloneSecret: source-repository-credentials
Copy to Clipboard Toggle word wrap
Configure a build with a context path

Configure a build to use a specific context directory within the Git repository when the source code is not located at the repository root, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-custom-context-dockerfile
spec:
  source:
    git:
      url: https://github.com/userjohn/npm-simple
    contextDir: docker-build
Copy to Clipboard Toggle word wrap
Configure a build with a tag

Configure a build to use a specific Git tag, such as v0.1.0, as the source revision, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-go
      revision: v0.1.0
Copy to Clipboard Toggle word wrap
Configure a build with environment variables

Configure a build to pass environment variables to the build container during build execution, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  env:
    - name: <example_var_1>
      value: "<example_value_1>"
    - name: <example_var_2>
      value: "<example_value_2>"
Copy to Clipboard Toggle word wrap

1.3. Strategy definition
Link kopieren

The build strategy determines how source code transforms into a container image. Supported strategies include buildah, source-to-image, and buildpacks. Define the strategy in the spec.strategy field of your Build CR.

To configure a build strategy, define the spec.strategy.name and spec.strategy.kind fields in the Build CR, as shown in the following example: 

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

1.4. Parameter values definition for a build
Link kopieren

You can set build strategy parameters in your Build custom resource (CR). These settings control how your build runs. For every parameter, you must provide a value. You can provide the values directly or reference keys in ConfigMaps or Secrets.

Note

You can only use ConfigMaps or Secrets if the parameter appears in a command, argument, or environment variable in the build strategy.

The following are the requirements of using parameters values definition for a build:

  • Mapping: Every spec.paramValues name must match a parameter defined in the BuildStrategy CR.
  • Reserved names: Do not use reserved names like BUILDER_IMAGE, CONTEXT_DIR, or any name starting with shp-.
  • Resources: You can only use ConfigMaps or Secrets if the parameter is used in a command, argument, or environment variable.

1.4.1. Example configuration for defining parameter values
Link kopieren

The following examples show how to set parameters in a build strategy. You can use a Build custom resource (CR) to give these parameters specific values. You can also assign values to array parameters.

Define parameters in a ClusterBuildStrategy CR

The following example shows a ClusterBuildStrategy CR with several parameters: 

apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: buildah
spec:
  parameters:
    - name: build-args
      description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE."
      type: array
      defaults: []
    # ...
    - name: storage-driver
      description: "The storage driver to use, such as 'overlay' or 'vfs'."
      type: string
      default: "vfs"
# ...
steps:
# ...
Copy to Clipboard Toggle word wrap
Assign values to parameters in a Build CR

As shown in the previous example, the ClusterBuildStrategy CR defines a storage-driver parameter. You can change its value in your Build CR like this: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: <your_build>
  namespace: <your_namespace>
spec:
  paramValues:
  - name: storage-driver
    value: "overlay"
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  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.
Creating a ConfigMap CR to control a parameter centrally
To use the same value for a parameter for multiple builds, use a ConfigMap. This allows you to change the value in one place and control its usage centrally. See the following example configuration: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: buildah-configuration
  namespace: <your_namespace>
data:
  storage-driver: overlay
Copy to Clipboard Toggle word wrap

+

where:

<your_namespace>
Specifies the namespace of the ConfigMap CR.

+ You can use the created ConfigMap CR as a parameter value in your Build CR, as shown in the following example:

+ 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: <your_build>
  namespace: <your_namespace>
spec:
  paramValues:
  - name: storage-driver
    configMapValue:
      name: buildah-configuration
      key: storage-driver
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
  # ...
Copy to Clipboard Toggle word wrap

+

where:

metadata
Specifies the metadata for your build CR.
Assign value to a parameter of the array type in a Build CR

You can also assign values to parameters of the type array. For example, use registries-search to tell the build where to look for images, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: <your_build>
  namespace: <your_namespace>
spec:
  paramValues:
  - name: storage-driver
    configMapValue:
      name: buildah-configuration
      key: storage-driver
  - name: registries-search
    values:
    - value: registry.redhat.io
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
  # ...
Copy to Clipboard Toggle word wrap

where:

metadata
Specifies the metadata for your build CR.
Reference a secret in a Build CR

You can reference to a Secret to a parameter. The following example shows how to block specific registries using a Secret: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: <your_build>
  namespace: <your_namespace>
spec:
  paramValues:
  - name: storage-driver
    configMapValue:
      name: buildah-configuration
      key: storage-driver
  - name: registries-block
    values:
    - secretValue:
        name: registry-configuration
        key: reg-blocked
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
  # ...
Copy to Clipboard Toggle word wrap

where:

metadata
Specifies the metadata for your build CR.
values.secretValue
Specifies the value that references a secret.

1.5. Builder or docker file definition
Link kopieren

Use the spec.paramValues field in your Build custom resource (CR) to specify the image or file used to build your output image.

The following example specifies a Dockerfile image in a Build CR: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  paramValues:
  - name: dockerfile
    value: Dockerfile
Copy to Clipboard Toggle word wrap

You can also use a builder image as part of the source-to-image build strategy in your Build CR, as shown in the following example: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-nodejs
    contextDir: source-build/
  strategy:
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues:
  - name: builder-image
    value: docker.io/centos/nodejs-10-centos7
Copy to Clipboard Toggle word wrap

1.6. Output definition
Link kopieren

In your Build custom resource (CR), you must choose an output location. This is where the system pushes your finished image. If you use a private registry, you must also provide a secret to log in. You can also add annotations and labels to your image.

Note

If you add annotations or labels, the system pushes the image twice. The first push comes from build strategy. The second push changes the image configuration and adds the annotations and labels.

The following example defines a public registry where the image is pushed: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-nodejs
    contextDir: source-build/
  strategy:
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues:
  - name: builder-image
    value: docker.io/centos/nodejs-10-centos7
  output:
    image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex
Copy to Clipboard Toggle word wrap

The following example defines a private registry where the image is pushed: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-nodejs
    contextDir: source-build/
  strategy:
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues:
  - name: builder-image
    value: docker.io/centos/nodejs-10-centos7
  output:
    image: us.icr.io/source-to-image-build/nodejs-ex
    pushSecret: icr-knbuild
Copy to Clipboard Toggle word wrap

The following example defines annotations and labels for the image: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: s2i-nodejs-build
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-nodejs
    contextDir: source-build/
  strategy:
    name: source-to-image
    kind: ClusterBuildStrategy
  paramValues:
  - name: builder-image
    value: docker.io/centos/nodejs-10-centos7
  output:
    image: us.icr.io/source-to-image-build/nodejs-ex
    pushSecret: icr-knbuild
    annotations:
      "org.opencontainers.image.source": "https://github.com/org/repo"
      "org.opencontainers.image.url": "https://my-company.com/images"
    labels:
      "maintainer": "team@my-company.com"
      "description": "This is my cool image"
Copy to Clipboard Toggle word wrap

1.7. Retention parameters definition for a build
Link kopieren

Define retention parameters in your Build custom resource (CR). These parameters manage the lifecycle of your BuildRun instances.

You can define retention parameters for the following purposes:

  • To specify how long a completed build run can exist
  • To specify the number of succeeded or failed build runs that can exist for a build

You can set the value of the following retention parameters in your Build custom resource (CR):

  • retention.succeededLimit: The number of successful build runs that can exist for a build.
  • retention.failedLimit: The number of failed build runs that can exist for a build.
  • retention.ttlAfterFailed: The duration for which a failed build run can exist.
  • retention.ttlAfterSucceeded: The duration for which a successful build run can exist.
Note

If you change a limit, it is applied immediately. If you change a time to live (TTL), it only applies to new build runs.

The following example shows the usage of retention parameters in a Build CR: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: build-retention-ttl
spec:
  source:
    git:
      url: "https://github.com/shipwright-io/sample-go"
    contextDir: docker-build
  strategy:
    kind: ClusterBuildStrategy
    name: buildah
  output:
  # ...
  retention:
    ttlAfterFailed: 30m
    ttlAfterSucceeded: 1h
    failedLimit: 10
    succeededLimit: 20
  # ...
Copy to Clipboard Toggle word wrap
Note

When you change the value of the retention.failedLimit and retention.succeededLimit parameters, the new limit is applied immediately. However, when you change the value of the retention.ttlAfterFailed and retention.ttlAfterSucceeded parameters, the new retention duration is enforced only on the new build runs. Old build runs adhere to the old retention duration. If you have defined retention duration in both BuildRun and Build CRs, the BuildRun CR gets the priority.

1.8. Volumes definition for a build
Link kopieren

Define volumes in your Build custom resource (CR) to override the volumes specified in the BuildStrategy resource. The build run fails if a volume is not explicitly overridden.

The following example shows the usage of the volumes field in a Build CR: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: <build_name>
spec:
  source:
    git:
      url: https://github.com/example/url
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  paramValues:
  - name: dockerfile
    value: Dockerfile
  output:
    image: registry/namespace/image:latest
  volumes:
    - name: <volume_name>
      configMap:
        name: <configmap_name>
Copy to Clipboard Toggle word wrap

where:

<build_name>
Specifies the name of the build.
<volume_name>
Specifies the name of the volume.
<configmap_name>
Specifies the name of the ConfigMap.

1.9. Pod configuration
Link kopieren

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

Use the following optional Build 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 you define these fields in 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