Configure

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:

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

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:

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

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

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

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

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.

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: buildah-configuration
  namespace: <your_namespace>
data:
  storage-driver: overlay

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:
  # ...

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

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

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.

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

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

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"

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:

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

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

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>

where:

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:

Define parameters in a BuildStrategy or ClusterBuildStrategy custom resource (CR). You can then set or modify these values in your Build or BuildRun CRs.

Consider the following points before defining parameters for your strategy:

Use system parameters to define the steps of a build strategy to access system information, or user-defined information in a Build or BuildRun custom resource (CR). You cannot configure or modify system parameters as they are defined at runtime by the build run controller.

You can define the following system parameters in your build strategy definition:

Define CPU, memory, and disk limits for each step in a build strategy. If a strategy has multiple steps, you can allocate different resource amounts to each.

As an administrator, you can provide different versions of the same strategy (for example, buildah-small and buildah-large) so users can choose the resource profile that fits their build requirements.

apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: buildah-small
spec:
  steps:
    - name: build-and-push
      image: quay.io/containers/buildah:v1.31.0
      workingDir: $(params.shp-source-root)
      securityContext:
        capabilities:
          add:
          - "SETFCAP"
      command:
        - /bin/bash
      args:
        - -c
        - |
          set -euo pipefail
          # Parse parameters
        # ...
        # That's the separator between the shell script and its args
        - --
        - --context
        - $(params.shp-source-context)
        - --dockerfile
        - $(build.dockerfile)
        - --image
        - $(params.shp-output-image)
        - --build-args
        - $(params.build-args[*])
        - --registries-block
        - $(params.registries-block[*])
        - --registries-insecure
        - $(params.registries-insecure[*])
        - --registries-search
        - $(params.registries-search[*])
      resources:
        limits:
          cpu: 250m
          memory: 65Mi
        requests:
          cpu: 250m
          memory: 65Mi
  parameters:
    - name: build-args
      description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE."
      type: array
      defaults: []
    # ...

apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: buildah-medium
spec:
  steps:
    - name: build-and-push
      image: quay.io/containers/buildah:v1.31.0
      workingDir: $(params.shp-source-root)
      securityContext:
        capabilities:
          add:
          - "SETFCAP"
      command:
        - /bin/bash
      args:
        - -c
        - |
          set -euo pipefail
          # Parse parameters
        # ...
        # That's the separator between the shell script and its args
        - --
        - --context
        - $(params.shp-source-context)
        - --dockerfile
        - $(build.dockerfile)
        - --image
        - $(params.shp-output-image)
        - --build-args
        - $(params.build-args[*])
        - --registries-block
        - $(params.registries-block[*])
        - --registries-insecure
        - $(params.registries-insecure[*])
        - --registries-search
        - $(params.registries-search[*])
      resources:
        limits:
          cpu: 500m
          memory: 1Gi
        requests:
          cpu: 500m
          memory: 1Gi
  parameters:
    - name: build-args
      description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE."
      type: array
      defaults: []
    # ...

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-medium
spec:
  source:
    git:
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy:
    name: buildah-medium
    kind: ClusterBuildStrategy
  # ...

Define annotations for a BuildStrategy or ClusterBuildStrategy in the same way as for any Kubernetes object. The build strategy passes these annotations to the TaskRun resource. Then, Tekton passes them to the pod.

You can use annotations for the following purposes:

The following example shows the usage of annotations in a build strategy:

apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: <cluster_build_strategy_name>
  annotations:
    container.apparmor.security.beta.kubernetes.io/step-build-and-push: unconfined
    container.seccomp.security.alpha.kubernetes.io/step-build-and-push: unconfined
spec:
  # ...

The following annotations are not passed to resources:

A strategy administrator can further restrict the usage of annotations by using policy engines.

Use the $(params.your-parameter-name) syntax to reference string parameters in your build strategy. When the build runs, the system replaces the variable with the actual strings.

To prevent command injection vulnerabilities when using inline scripts, use one of the following secure methods:

Store the image size and digest or content hash produced by the build strategy in a set of result files. Error details for debugging can also be recorded when a BuildRun resource fails.

The following result parameters can be defined in the BuildStrategy or ClusterBuildStrategy custom resource (CR):

The following example shows the size and digest or the content hash of the image in the .status.output field of the BuildRun CR:

apiVersion: shipwright.io/v1beta1
kind: BuildRun
# ...
status:
 # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  # ...

The following example shows the error reason and message in the .status.failureDetails field of the BuildRun CR:

apiVersion: shipwright.io/v1beta1
kind: 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

Build strategies use volumes and volume mounts to manage data during build steps. By default, you cannot override the volumes in a BuildStrategy. To allow a Build or BuildRun to use a custom volume, you must set overridable field to true in the strategy.

Volumes in build strategy use an overridable boolean flag, which is set to false by default. If a Build or BuildRun resource tries to override the volumes defined in a BuildStrategy resource, it will fail because the default value of the overridable flag is false.

The following example shows a BuildStrategy resource that defines the volumes and volumeMounts fields:

apiVersion: shipwright.io/v1beta1
kind: BuildStrategy
metadata:
  name: buildah
spec:
  steps:
    - name: build
      image: quay.io/containers/buildah:v1.23.3
      # ...
      volumeMounts:
        - name: varlibcontainers
          mountPath: /var/lib/containers
  volumes:
    - name: varlibcontainers
      overridable: true
      emptyDir: {}

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

The following table describes optional fields in your BuildRun custom resource (CR):

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

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>

where

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:
  # ...

where

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: <your_buildrun>
  namespace: <your_namespace>
spec:
  build:
    name: <your_build>
  paramValues:
  - name: cache
    value: registry

where

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

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:

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

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>

where:

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>"

where:

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

where:

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

where:

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.

$ oc get buildrun buildah-buildrun-mp99r

Example output:

NAME                    SUCCEEDED   REASON    STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  Unknown     Unknown      1s

$ oc get buildrun buildah-buildrun-mp99r

Example output:

NAME                   SUCCEEDED     REASON     STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  True        Succeeded      29m       20m

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.

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

# ...
status:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    git:
      commitAuthor: xxx xxxxxx
      commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde
      branchName: main

# ...
status:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    bundle:
      digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7

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.

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"

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:

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

Use the following fields to configure Builds pods: