Configuring Builds | Configure | builds for Red Hat OpenShift 1.0

Configurable fields in build
Source definition
Strategy definition
Parameter values definition for a build
- Example configuration for defining parameter values
Builder or docker file definition
Output definition
Retention parameters definition for a build
Volumes definition for a build

In a Build custom resource (CR), you can define the source, build strategy, parameter values, output, retention parameters, and volumes to configure a build. A Build resource is available for use within a namespace.

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

Configurable fields in build

You can use the following fields in your Build custom resource (CR):

Table 1. Fields in the `Build` CR
Field	Presence	Description
`apiVersion`	Required	Specifies the API version of the resource, for example, `shipwright.io/v1beta1`.
`kind`	Required	Specifies the type of the resource, for example, `Build`.
`metadata`	Required	Denotes the metadata that identifies the custom resource definition instance, for example, the name of the `Build` resource.
`spec.source`	Required	Denotes the location of the source code, for example, a Git repository or source bundle image.
`spec.strategy`	Required	Denotes the name and type of the strategy used for the `Build` resource.
`spec.output`	Required	Denotes the location where the generated image will be pushed.
`spec.output.pushSecret`	Required	Denotes an existing secret to get access to the container registry.
`spec.paramValues`	Optional	Denotes a name-value list to specify values for parameters defined in the build strategy.
`spec.timeout`	Optional	Defines a custom timeout. The default value is ten minutes. You can overwrite this field value in your `BuildRun` resource.
`spec.output.annotations`	Optional	Denotes a list of key-value pair that you can use to annotate the output image.
`spec.output.labels`	Optional	Denotes a list of key-value pair that you can use to label the output image.
`spec.env`	Optional	Defines additional environment variables that you can pass to the build container. The available variables depend on the tool that is used by your build strategy.
`spec.retention.ttlAfterFailed`	Optional	Specifies the duration for which a failed build run can exist.
`spec.retention.ttlAfterSucceeded`	Optional	Specifies the duration for which a successful build run can exist.
`spec.retention.failedLimit`	Optional	Specifies the number of failed build runs that can exist.
`spec.retention.succeededLimit`	Optional	Specifies the number of successful build runs that can exist.

Source definition

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

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

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

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

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

Strategy definition

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

Parameter values definition for a build

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.

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.

Example configuration for defining parameter values

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

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

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

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

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

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

1	The value references a secret.

Builder or docker file definition

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

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

Output definition

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.

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

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"

Retention parameters definition for a build

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

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.

Volumes definition for a build

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>