About Builds

builds for Red Hat OpenShift 1.7

Introduction to Builds

Red Hat OpenShift Documentation Team

Abstract

This document provides an overview of Builds features. It also includes release notes and details about how to get support.

Chapter 1. Overview of Builds

Builds is a Shipwright-based framework for building container images on OpenShift Container Platform. It is designed for developers seeking automated image creation and administrators managing secure, reusable build strategies at scale.

1.1. Builds capabilities and resources

Builds provides Kubernetes-native APIs to build container images from source code and Dockerfiles. It supports S2I and Buildah strategies, allows custom strategies, offers a CLI for managing builds, and integrates with developer perspective of the OpenShift Container Platform console.

Builds consists of the following custom resources (CRs):

  • Build
  • BuildStrategy and ClusterBuildStrategy
  • BuildRun

1.1.1. Build resource

The Build resource defines the source code of your application and the location where your application images are pushed. A Build resource specifies the Git source, build strategy, and output image registry. 

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.

1.1.2. BuildStrategy and ClusterBuildStrategy resources

The BuildStrategy and ClusterBuildStrategy resources define the steps needed to build an application.

A BuildStrategy is namespace-scoped and can be created, managed, and used only within a specific namespace and not shared across the cluster.

A ClusterBuildStrategy is cluster-scoped and can be shared across namespaces.

Both resources include a steps section. The following example shows a ClusterBuildStrategy named buildah. 

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
       # ...
# ...

1.1.3. BuildRun resource

A BuildRun resource invokes a build on the cluster similar to a Tekton task run. It represents a workload that instantiates a build for execution with specific parameters. Each BuildRun defines a unique name for monitoring, references a Build instance, and specifies a service account within a namespace.

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.

1.1.4. Build controller

The build controller validates Build resources by checking strategy existence, parameter definitions, secret references, and Git repository accessibility before execution.

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.

1.1.5. Build validations

The build controller validates BuildRun resources in advance to prevent failures from wrong or missing dependencies and configuration settings. Validations check for strategy existence, secret references, parameter definitions, Git repository accessibility, and environment variable completeness.

Table 1.1. Validation of builds by the build controller

status.reason fieldDescription

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.

1.2. Additional resources

Chapter 2. Build strategies

You can use a curated set of build strategies or cluster build strategies on the OpenShift Container Platform cluster. The Builds for Red Hat OpenShift Operator automatically installs these strategies for use. This automated installation of strategies helps you to quickly get started with Builds.

Builds supports the following cluster build strategies:

  • buildah: Supported on all platforms
  • source-to-image: Supported on the linux/amd64 platform
  • buildpacks: Supported on all platforms
  • buildpacks-extender: Supported on all platforms

2.1. Buildah

The buildah cluster build strategy uses a Dockerfile to build a container image and pushes it to the target registry. You must specify the Dockerfile in the spec.paramValues field of the Build CR.

You can share the buildah strategy across different namespaces within your cluster because the Builds for Red Hat OpenShift Operator installs the buildah strategy at cluster level.

You can configure the following parameters for the buildah strategy:

Table 2.1. Configuration parameters for buildah

NameTypeDescriptionDefault

build-args

array

Key-value pair of the arguments required by the Dockerfile that is used during the build

[]

registries-block

array

List of registries that must be blocked

[]

registries-insecure

array

List of insecure registries with their fully qualified domain name (FQDN)

[]

registries-search

array

List of registries to search short name images

["registry.redhat.io", "quay.io"]

dockerfile

string

Path of the Dockerfile that is used during the build

"Dockerfile"

storage-driver

string

Storage drivers that are used by buildah, such as overlay or vfs

"vfs"

target

string

Sets the target stage to be built

""

Note

For more information, see Configuring build strategies.

2.2. Source-to-image

This build strategy is composed of source-to-image and buildah. You can use this strategy to generate a container file and prepare the application to build with a builder image. You must specify the builder image in the spec.paramValues field of the Build CR.

You can share the source-to-image strategy across different namespaces within your cluster because the Builds for Red Hat OpenShift Operator installs the source-to-image strategy at cluster level.

You can configure the following parameters for the source-to-image strategy:

Table 2.2. Configuration parameters for source-to-image

NameTypeDescriptionDefault

registries-block

array

List of registries that must be blocked

[]

registries-insecure

array

List of insecure registries with their FQDN

[]

registries-search

array

List of registries to search short name images

["registry.redhat.io", "quay.io"]

builder-image

string

Location of the builder image that is used during the build

NA

storage-driver

string

Storage drivers that are used by source-to-image, such as overlay or vfs

"vfs"

2.3. Buildpacks

The buildpacks cluster build strategy uses Cloud Native Buildpacks (CNB) to build and push a container image from source code, without requiring a Dockerfile. The configuration details are provided through parameters in the Build resource.

The buildpacks-extender cluster build strategy supports the image extension feature of CNB, in addition to all the capabilities offered by the buildpacks strategy. The buildpacks-extender allows you to modify the builder or run image using a Dockerfile. This is useful for installing system dependencies or applying security configurations that standard Buildpacks cannot handle. The Dockerfile is provided by a Buildpack that supports extensions. To use the extender, set the cnb-extender-kind parameter in the Build resource.

Note

The buildpacks cluster build strategy supports Quarkus and Go-based applications, while the buildpacks-extender cluster build strategy supports Node.js and Python-based applications.

You can configure the following parameters for the buildpacks strategy:

Table 2.3. Configuration parameters for buildpacks

NameTypeDescriptionDefault

cnb-platform-api

string

Supported Platform API Version

"0.12"

cnb-builder-image

string

Builder image containing the buildpacks

""

cnb-lifecycle-image

string

Image to use while executing Lifecycle phases

"buildpacksio/lifecycle:0.20.8"

cnb-log-level

string

Logging levels

"debug"]

run-image

string

Reference to a run image to use

""

cache-image

string

Name of the persistent app cache image

""

source-subpath

string

Subpath within the source input where the source to build is located

""

env-vars

array

Environment variables to set during build-time

[]

platform-dir

string

Name of the platform directory

"empty-dir"

user-id

string

User ID of the builder image user

"1001"

group-id

string

Group ID of the builder image user

"1001"

user-home

string

Absolute path to the user’s home directory

"/tekton/home"

cache-pvc-name

string

Name of the Persistent Volume Claim for cache

"ws-pvc"

cnb-extender-kind

string

The kind of image to extend (build or run) "build"

""

cnb-extended-dir-exporter

string

Directory of extended layers, passed as -extended flag to the exporter

"/layers/extended"

2.4. Additional resources

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.