1. Documentation
    2. history bug_report picture_as_pdf
×

Overview of Builds

Builds is an extensible build framework based on the Shipwright project, which you can use to build container images on an OpenShift Container Platform cluster. You can build container images from source code and Dockerfiles by using image build tools, such as Source-to-Image (S2I) and Buildah. You can create and apply build resources, view logs of build runs, and manage builds in your OpenShift Container Platform namespaces.

Builds includes the following capabilities:

  • Standard Kubernetes-native API for building container images from source code and Dockerfiles

  • Support for Source-to-Image (S2I) and Buildah build strategies

  • Extensibility with your own custom build strategies

  • Execution of builds from source code in a local directory

  • Shipwright CLI for creating and viewing logs, and managing builds on the cluster

  • Integrated user experience with the Developer perspective of the OpenShift Container Platform web console

Builds consists of the following custom resources (CRs):

  • Build

  • BuildStrategy and ClusterBuildStrategy

  • BuildRun

Build resource

The Build resource defines the source code of your application and the location where your application images will be pushed. The following example shows a simple build that consists of a Git source, a build strategy, and an output image:

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: https://github.com/username/taxi
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  output:
    image: registry.mycompany.com/my-org/taxi-app:latest

You can also extend a Build resource to push your images to a private registry or use a Dockerfile.

BuildStrategy and ClusterBuildStrategy resources

The BuildStrategy and ClusterBuildStrategy resources define a series of steps to assemble an application. You can use the BuildStrategy resources within a namespace and the ClusterBuildStrategy resources within a cluster.

The specification of a BuildStrategy or ClusterBuildStrategy resource consists of a steps object. The following example shows the specification of the buildah cluster build strategy:

apiVersion: shipwright.io/v1beta1
kind: ClusterBuildStrategy
metadata:
  name: buildah
spec:
  steps:
    - name: build-and-push
      image: quay.io/containers/buildah:v1.31.0
      workingDir: $(params.shp-source-root)
      command:
        - /bin/bash
       # ...
# ...

BuildRun resource

A BuildRun resource invokes a build on your cluster, similar to any cluster job or Tekton task run. The BuildRun resource represents a workload on your cluster, which results in a running pod. A BuildRun is the running instance of a build. It instantiates a build for execution with specific parameters on a cluster.

A BuildRun resource helps you to define the following elements:

  • A unique BuildRun name to monitor the status of the build

  • A referenced Build instance to use during the build

  • A service account to host all secrets for the build

Each BuildRun resource is available within a namespace.

Build controller

The build controller monitors any updates in the Build resource and performs the following tasks:

  • Validates if the referenced Strategy object exists in the Build resource.

  • Validates if the specified parameters in the Build CR exist in the referenced build strategy. It also validates if the parameter names collide with any reserved names.

  • Validates if the container registry output secret exists in the Build resource.

  • Validates if the referenced spec.source.git.url endpoint URL exists in the Build resource.

The build run controller monitors any updates in the Build or TaskRun resource and performs the following tasks:

  • Searches for any existing TaskRun resource and updates its parent BuildRun resource status.

  • Retrieves the specified service account and sets it along with the output secret in the Build resource.

  • If a TaskRun resource does not exist, the controller generates a new Tekton TaskRun resource and sets a reference to the TaskRun resource.

  • For any subsequent updates in the TaskRun resource, the controller updates the parent BuildRun resource.

Build validations

To avoid triggering BuildRun resources that will fail because of incorrect or missing dependencies or configuration settings, the build controller validates them in advance. If all validations are successful, you view a status.reason field named Succeeded. However, if any validations fail, you must check the status.reason and status.message fields to understand the root cause.

Table 1. Validation of builds by the build controller
status.reason field Description

BuildStrategyNotFound

The referenced strategy at namespace level does not exist.

ClusterBuildStrategyNotFound

The referenced strategy at cluster level does not exist.

SetOwnerReferenceFailed

Setting owner references between a Build and a BuildRun resources failed. This status is triggered when you set the spec.retention.atBuildDeletion field to true in a build.

SpecSourceSecretRefNotFound

The secret used to authenticate to Git does not exist.

SpecOutputSecretRefNotFound

The secret used to authenticate to the container registry does not exist.

SpecBuilderSecretRefNotFound

The secret used to authenticate to the container registry does not exist.

MultipleSecretRefNotFound

Multiple secrets used for authentication are missing.

RestrictedParametersInUse

One or many defined params are colliding with any reserved parameters.

UndefinedParameter

The parameters are not defined in the referenced strategy. You must define those parameters in the spec.parameters specification in your strategy.

RemoteRepositoryUnreachable

The defined spec.source.git.url specification was not found. This validation only takes place for HTTP and HTTPS protocols.

BuildNameInvalid

The build name in the metadata.name field is invalid. You must use a valid label value for the build name.

SpecEnvNameCanNotBeBlank

Indicates that the name for a user-provided environment variable is blank.

SpecEnvValueCanNotBeBlank

Indicates that the value for a user-provided environment variable is blank.

Additional resources