Questo contenuto non è disponibile nella lingua selezionata.
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):
Field | Presence | Description |
---|---|---|
| Required |
Specifies the API version of the resource, for example, |
| Required |
Specifies the type of the resource, for example, |
| Required |
Denotes the metadata that identifies the custom resource definition instance, for example, the name of the |
| Required | Denotes the location of the source code, for example, a Git repository or source bundle image. |
| Required |
Denotes the name and type of the strategy used for the |
| Required | Denotes the location where the generated image will be pushed. |
| Required | Denotes an existing secret to get access to the container registry. |
| Optional | Denotes a name-value list to specify values for parameters defined in the build strategy. |
| Optional |
Defines a custom timeout. The default value is ten minutes. You can overwrite this field value in your |
| Optional | Denotes a list of key-value pair that you can use to annotate the output image. |
| Optional | Denotes a list of key-value pair that you can use to label the output image. |
| 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. |
| Optional | Specifies the duration for which a failed build run can exist. |
| Optional | Specifies the duration for which a successful build run can exist. |
| Optional | Specifies the number of failed build runs that can exist. |
| 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 assource.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.
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 thespec.parameters
defined in theBuildStrategy
CR. -
Specifying a
spec.paramValues
name that collides with the Shipwright reserved parameters. These parameters includeBUILDER_IMAGE
,CONTEXT_DIR
, and any name starting withshp-
.
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.
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 # ...
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>