Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

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

Chapter 1. Configuring Builds

In a Build custom resource (CR), you can configure a build by defining the source, build strategy, parameter values, output, retention parameters, and volumes. You can also configure build pods by using a Build CR.

A Build resource is available for use within a namespace.

To configure a build, create a Build resource YAML file and apply it to the OpenShift Container Platform cluster.

1.1. Configurable fields in build
Copier lien

You can use the following required and optional fields in your Build custom resource (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

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

spec.source

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

spec.strategy

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

spec.output

Denotes the location where the generated image will be pushed.

spec.output.pushSecret

Denotes an existing secret to get access to the container registry.

Expand
Table 1.2. Optional fields in the Build CR
FieldDescription

spec.paramValues

Denotes a name-value list to specify 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

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

spec.output.labels

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

You can configure the source details for a build in the Build custom resource (CR) by setting the value of the following fields:

  • source.git.url: Defines the source location of the image available in a Git repository.
  • source.git.cloneSecret: References a secret in the namespace that contains the SSH private key for a private Git repository.
  • source.git.revision: Defines a specific revision to select from the source Git repository. For example, a commit, tag, or branch name. This field defaults to the Git repository default branch.
  • source.contextDir: Specifies the context path for the repositories where the source code is not present at the root folder.

The build controller does not automatically validate that the Git repository you specified for pulling an image exists. If you need to validate, set the value of the build.shipwright.io/verify.repository annotation to true, 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 examples show how you can configure a build with different set of source inputs.

Example: Configuring a build with credentials

You can configure a build with a source by specifying your 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

Example: Configuring a build with a context path

You can configure a build with a source that specifies a context path in the Git repository, 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

Example: Configuring a build with a tag

You can configure a build with a source that specifies the tag v.0.1.0 for the Git repository, 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

Example: Configuring a build with environment variables

You can also configure a build that specifies environment variables, 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
Copier lien

You can configure the strategy for a build in the Build CR. The following build strategies are available for use:

  • buildah
  • source-to-image

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

You can specify values for the build strategy parameters in your Build CR. By specifying parameter values, you can control how the steps of the build strategy work. You can also overwrite the values in the BuildRun resource.

For all parameters, you must specify values either directly or by using reference keys from config maps or secrets.

Note

The usage of the parameter in the build strategy steps limits the usage of config maps and secrets. You can only use config maps and secrets if the parameter is used in the command, argument, or environment variable.

When using the paramValues field in your Build CR, avoid the following scenarios:

  • Specifying a spec.paramValues name that does not match one of the spec.parameters defined in the BuildStrategy CR.
  • Specifying a spec.paramValues name that collides with the Shipwright reserved parameters. These parameters include BUILDER_IMAGE, CONTEXT_DIR, and any name starting with shp-.

Also, ensure that you understand the content of your strategy before defining the paramValues field in the Build CR.

1.4.1. Example configuration for defining parameter values
Copier lien

The following examples show how to define parameters in a build strategy and assign values to those parameters by using a Build CR. You can also assign a value to a parameter of the type array in your Build CR.

Example: Defining parameters in a ClusterBuildStrategy CR

The following example shows a ClusterBuildStrategy CR that defines 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

Example: Assigning values to parameters in a Build CR

The above ClusterBuildStrategy CR defines a storage-driver parameter and you can specify the value of the storage-driver parameter 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
    value: "overlay"
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
  # ...
Copy to Clipboard Toggle word wrap

Example: Creating a ConfigMap CR to control a parameter centrally

If you want to use the storage-driver parameter for multiple builds and control its usage centrally, then you can create a ConfigMap CR, as shown in the following example: 

apiVersion: v1
kind: ConfigMap
metadata:
  name: buildah-configuration
  namespace: <your_namespace>
data:
  storage-driver: overlay
Copy to Clipboard Toggle word wrap

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

Example: Assigning value to a parameter of the type array in a Build CR

You can assign value to a parameter of the type array. If you use the buildah strategy, you can define a registries-search parameter to search images in specific registries. The following example shows how you can assign a value to the registries-search array parameter: 

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

Example: Referencing a secret in a Build CR

You can reference a secret for a registries-block array parameter, 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-block
    values:
    - secretValue:
1 

        name: registry-configuration
        key: reg-blocked
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
  # ...
Copy to Clipboard Toggle word wrap
1
The value references a secret.

1.5. Builder or docker file definition
Copier lien

In your Build CR, you can use the spec.paramValues field to specify the image that contains the tools to build the 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
Copier lien

In your Build CR, you can specify an output location to push the image. When using an external private registry as your output location, you must specify a secret to access the image. You can also specify the annotations and labels for the output image.

Note

When you specify annotations or labels, the output image is pushed twice. The first push comes from the build strategy and the second push changes the image configuration to add 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
Copier lien

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

Retention parameters provide a way to clean your BuildRun instances or resources automatically. You can set the value of the following retention parameters in your Build CR:

  • retention.succeededLimit: Defines the number of succeeded build runs that can exist for a build.
  • retention.failedLimit: Defines the number of failed build runs that can exist for a build.
  • 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 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 enforced as soon as those changes are applied on your build. 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 retention duration defined in the BuildRun CR gets the priority.

1.8. Volumes definition for a build
Copier lien

You can define volumes in your Build CR. The defined volumes override the volumes specified in the BuildStrategy resource. If a volume is not overridden, then the build run fails.

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: <your_volume_name>
      configMap:
        name: <your_configmap_name>
Copy to Clipboard Toggle word wrap

1.9. Pod configuration
Copier lien

You can 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 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