此内容没有您所选择的语言版本。
Chapter 1. Configuring Builds
As a platform engineer, you can define the source, strategy, parameters, outputs, retention rules, and volumes in a Build custom resource (CR) to configure builds. A Build CR enables consistent build pod configuration and provides a namespace-scoped method for managing build execution on the cluster.
1.1. Configurable fields in build 复制链接链接已复制到粘贴板!
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:
| Field | Description |
|---|---|
|
|
Specifies the API version of the resource, for example, |
|
|
Specifies the type of the resource, for example, |
|
|
Specifies the metadata that identifies the custom resource definition instance, for example, the name of the |
|
| Specifies the location of the source code, for example, a Git repository or source bundle image. |
|
|
Specifies the name and type of the strategy used for the |
|
| Specifies the location where the system pushes the generated image. |
|
| Specifies an existing secret to gain access to the container registry. |
The following table describes the optional fields in your Build CR:
| Field | Description |
|---|---|
|
| Specifies a name-value list to set values for parameters defined in the build strategy. |
|
|
Defines a custom timeout. The default value is ten minutes. You can overwrite this field value in your |
|
| Specifies a list of key-value pairs that you can use to annotate the output image. |
|
| Specifies a list of key-value pairs that you can use to label the output image. |
|
| Defines additional environment variables that you can pass to the build container. The available variables depend on the tool used by your build strategy. |
|
| Specifies the duration for which a failed build run can exist. |
|
| Specifies the duration for which a successful build run can exist. |
|
| Specifies the number of failed build runs that can exist. |
|
| Specifies the number of successful build runs that can exist. |
|
| Specifies which nodes Builds should run on. |
|
| Specifies the tolerations for the Builds pod. |
|
| Specifies the scheduler for the Builds pod |
1.2. Source definition 复制链接链接已复制到粘贴板!
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:
-
source.git.url: The Git repository location. -
source.git.cloneSecret: The secret containing SSH keys for private repositories. -
source.git.revision: The specific commit, tag, or branch (defaults to the default branch). -
source.contextDir: The subdirectory containing the source code.
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:
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 configurations show how you can configure a build with different set of source inputs.
- Configure a build with credentials
Configure a build to access a private Git repository by referencing a secret that contains the repository credentials, as shown in the following example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Configure a build with a context path
Configure a build to use a specific context directory within the Git repository when the source code is not located at the repository root, as shown in the following example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Configure a build with a tag
Configure a build to use a specific Git tag, such as v0.1.0, as the source revision, as shown in the following example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Configure a build with environment variables
Configure a build to pass environment variables to the build container during build execution, as shown in the following example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. Strategy definition 复制链接链接已复制到粘贴板!
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:
1.4. Parameter values definition for a build 复制链接链接已复制到粘贴板!
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.
You can only use ConfigMaps or Secrets if the parameter appears in a command, argument, or environment variable in the build strategy.
The following are the requirements of using parameters values definition for a build:
-
Mapping: Every
spec.paramValuesname must match a parameter defined in theBuildStrategyCR. -
Reserved names: Do not use reserved names like
BUILDER_IMAGE,CONTEXT_DIR, or any name starting withshp-. -
Resources: You can only use
ConfigMapsorSecretsif the parameter is used in a command, argument, or environment variable.
The following examples show how to set parameters in a build strategy. You can use a Build custom resource (CR) to give these parameters specific values. You can also assign values to array parameters.
- Define parameters in a ClusterBuildStrategy CR
The following example shows a
ClusterBuildStrategyCR with several parameters:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Assign values to parameters in a Build CR
As shown in the previous example, the
ClusterBuildStrategyCR defines astorage-driverparameter. You can change its value in your Build CR like this:Copy to Clipboard Copied! Toggle word wrap Toggle overflow where:
<your_build>-
Specifies the name of the
buildCR. <your_namespace>-
Specifies the namespace of the
buildCR.
- Creating a ConfigMap CR to control a parameter centrally
-
To use the same value for a parameter for multiple builds, use a
ConfigMap. This allows you to change the value in one place and control its usage centrally. See the following example configuration:
+
where:
<your_namespace>-
Specifies the namespace of the
ConfigMapCR.
+ You can use the created ConfigMap CR as a parameter value in your Build CR, as shown in the following example:
+
+
where:
metadata-
Specifies the metadata for your
buildCR.
- Assign value to a parameter of the array type in a Build CR
You can also assign values to parameters of the type
array. For example, useregistries-searchto tell the build where to look for images, as shown in the following example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow where:
metadata-
Specifies the metadata for your
buildCR.
- Reference a secret in a Build CR
You can reference to a
Secretto a parameter. The following example shows how to block specific registries using aSecret:Copy to Clipboard Copied! Toggle word wrap Toggle overflow where:
metadata-
Specifies the metadata for your
buildCR. values.secretValue-
Specifies the value that references a
secret.
1.5. Builder or docker file definition 复制链接链接已复制到粘贴板!
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:
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:
1.6. Output definition 复制链接链接已复制到粘贴板!
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.
If you add annotations or labels, the system pushes the image twice. The first push comes from build strategy. The second push changes the image configuration and adds the annotations and labels.
The following example defines a public registry where the image is pushed:
The following example defines a private registry where the image is pushed:
The following example defines annotations and labels for the image:
1.7. Retention parameters definition for a build 复制链接链接已复制到粘贴板!
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:
- 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
You can set the value of the following retention parameters in your Build custom resource (CR):
-
retention.succeededLimit: The number of successful build runs that can exist for a build. -
retention.failedLimit: The number of failed build runs that can exist for a build. -
retention.ttlAfterFailed: The duration for which a failed build run can exist. -
retention.ttlAfterSucceeded: The duration for which a successful build run can exist.
If you change a limit, it is applied immediately. If you change a time to live (TTL), it only applies to new build runs.
The following example shows the usage of retention parameters in a Build CR:
When you change the value of the retention.failedLimit and retention.succeededLimit parameters, the new limit is applied immediately. 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 BuildRun CR gets the priority.
1.8. Volumes definition for a build 复制链接链接已复制到粘贴板!
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:
where:
<build_name>-
Specifies the name of the
build. <volume_name>- Specifies the name of the volume.
<configmap_name>-
Specifies the name of the
ConfigMap.
1.9. Pod configuration 复制链接链接已复制到粘贴板!
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:
The
spec.tolerationsfield specifies the tolerations for the Builds pod with the following limitation:-
Only the
NoScheduletaint effect is supported.
-
Only the
-
The
spec.nodeSelectorfield specifies which nodes the Builds pod should run on. -
The
spec.schedulerNamefield specifies the scheduler for the Builds pod.
If you define these fields in the Build and BuildRun CRs, the BuildRun values take priority.