Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 2. Configuring build strategies

As a platform engineer, you can define consistent build strategies by specifying parameters, system settings, resource requirements, annotations, and volumes in BuildStrategy or ClusterBuildStrategy custom resources (CR). These strategies enable controlled and reusable build execution across the cluster.

2.1. Strategy parameters definition
Link kopieren

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:

  • Define a list of parameters in the spec.parameters field of your build strategy CR. Each item includes a name, description, type, and optionally a default value (or values for array types). If no default value is set, you must define a value in the Build or BuildRun CR.
  • Define parameters of string or array type in the spec.steps field of your build strategy.

  • Specify a parameter of string type by using the $(params.your-parameter-name) syntax. You can set a value for the your-parameter-name parameter in your Build or BuildRun CR that references your strategy. You can define the following string parameters based on your needs:

    Expand
    Table 2.1. String parameters
    ParameterDescription

    image

    Use this parameter to define a custom tag, such as golang:$(params.go-version)

    args

    Use this parameter to pass data into your builder commands

    env

    Use this parameter to provide a value for an environment variable

  • Specify a parameter of array type by using the $(params.your-array-parameter-name[*]) syntax. After specifying the array, you can use it in an argument or a command. For each item in the array, an argument will be set. The following example uses an array parameter in the spec.steps field of the build strategy: 

    apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: <cluster_build_strategy_name>
  # ...
spec:
  parameters:
    - name: tool-args
      description: Parameters for the tool
      type: array
  steps:
    - name: a-step
      command:
        - some-tool
      args:
        - --tool-args
        - $(params.tool-args[*])
    Copy to Clipboard Toggle word wrap
  • Provide parameter values as simple strings or as references to keys in config maps or secrets. For a parameter, you can use a config map or secret value only if it is defined in the command, args, or env section of the spec.steps field.

2.2. System parameters definition
Link kopieren

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:

Expand
Table 2.2. System parameters
ParameterDescription

$(params.shp-source-root)

Specifies the absolute path to the directory that contains the source code.

$(params.shp-source-context)

Specifies the absolute path to the context directory of the source code. If you do not specify any value for spec.source.contextDir in the Build CR, this parameter uses the value of the $(params.shp-source-root) system parameter.

$(params.shp-output-image)

Specifies the URL of the image to push as defined in the spec.output.image field of your Build or BuildRun CR.

2.3. Step resources definition
Link kopieren

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.

2.3.1. Strategies with different resources
Link kopieren

Define multiple variants of the same strategy to apply different resource limits for different build requirements.

The following examples use the same buildah strategy with small and medium limits defined for the resources.These examples provide a strategy administrator more control over the step resources definition.

You can define the spec.steps[].resources field with a small resource limit for the buildah strategy, as shown in the following example: 

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: []
    # ...
Copy to Clipboard Toggle word wrap

You can define the spec.steps[].resources field with a medium resource limit for the buildah strategy, as shown in the following example: 

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: []
    # ...
Copy to Clipboard Toggle word wrap

After configuring the resource definition for a strategy, you must reference the strategy in your Build custom resource (CR), as shown in the following example: 

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
  # ...
Copy to Clipboard Toggle word wrap

2.3.2. Resource management in Tekton pipelines
Link kopieren

The build controller works with the Tekton pipeline controller to schedule pods that run strategy steps. At runtime, the build controller creates a Tekton TaskRun, which executes a Task and records status and results. The TaskRun creates a pod in the target namespace that runs all steps sequentially.

2.4. Annotations definition
Link kopieren

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:

  • Network bandwidth: Use kubernetes.io/ingress-bandwidth or kubernetes.io/egress-bandwidth to limit the network bandwidth.
  • Security profiles: Use container.apparmor.security.beta.kubernetes.io/<container_name> to define AppArmor profiles of a container.

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:
  # ...
Copy to Clipboard Toggle word wrap

The following annotations are not passed to resources:

  • kubectl.kubernetes.io/last-applied-configuration
  • clusterbuildstrategy.shipwright.io/*
  • buildstrategy.shipwright.io/*
  • build.shipwright.io/*
  • buildrun.shipwright.io/*

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

2.5. Secure referencing of string parameters
Link kopieren

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.

Note

You can use the $(params.your-parameter-name) syntax for system and strategy parameters.

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

  • Use environment variables

  • Use arguments

    Reference a string parameter into an environment variable

    Pass the parameter into an environment variable. Then, use quotes around that variable in your script. The following example uses an environment variable inside the script to reference a string parameter: 

    apiVersion: shipwright.io/v1beta1
kind: BuildStrategy
metadata:
  name: sample-strategy
spec:
  parameters:
    - name: sample-parameter
      description: A sample parameter
      type: string
  steps:
    - name: sample-step
      env:
        - name: PARAM_SAMPLE_PARAMETER
          value: $(params.sample-parameter)
      command:
        - /bin/bash
      args:
        - -c
        - |
          set -euo pipefail

          some-tool --sample-argument "${PARAM_SAMPLE_PARAMETER}"
    Copy to Clipboard Toggle word wrap
    Reference a string parameter into an argument

    Pass the parameter as an argument to the script. Then, use a shell variable to read it. The following example uses an argument defined within your script to reference a string parameter: 

    apiVersion: shipwright.io/v1beta1
kind: BuildStrategy
metadata:
  name: sample-strategy
spec:
  parameters:
    - name: sample-parameter
      description: A sample parameter
      type: string
  steps:
    - name: sample-step
      command:
        - /bin/bash
      args:
        - -c
        - |
          set -euo pipefail

          SAMPLE_PARAMETER="$1"

          some-tool --sample-argument "${SAMPLE_PARAMETER}"
        - --
        - $(params.sample-parameter)
    Copy to Clipboard Toggle word wrap

2.6. System results definition
Link kopieren

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

Expand
Table 2.3. Result parameters
ParameterDescription

$(results.shp-image-digest.path)

Specifies the path to the file that stores the digest or the content hash of the image.

$(results.shp-image-size.path)

Specifies the path to the file that stores the compressed size of the image.

$(results.shp-error-reason.path)

Specifies the path to the file that stores the error reason.

$(results.shp-error-message.path)

Specifies the path to the file that stores the error message.

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
  # ...
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

2.7. Volumes and volume mounts definition
Link kopieren

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.

Note

The volume mount defined in build steps allows you to access volumes defined in a BuildStrategy, Build or BuildRun resource.

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: {}
Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red HatNach oben