Chapter 1. Configuring Builds
Chapter 1. Configuring Builds 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. 1.1. Configurable fields in build You can use the following fields in your Build custom resource (CR): Table 1.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. 1.2. 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>" 1.3. 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 1.4. 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. 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 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. 1.5. 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 1.6. 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. 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 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" 1.7. 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 # ... 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 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>
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 apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-build spec: source: git: url: https://github.com/sclorg/nodejs-ex cloneSecret: source-repository-credentials 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 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 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>" apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-build spec: strategy: name: buildah kind: ClusterBuildStrategy 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: 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: # 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: # 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: # 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: # 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 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 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 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 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" 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 # 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>