Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Builds and Pipelines

BuildConfigs and Build Strategies

Build container images inside OpenShift with BuildConfig: source, strategy and output, oc start-build, triggers, webhooks and the Docker, Source and binary build types.

OpenShift can turn source code into a container image inside the cluster. This is done by builds. A BuildConfig describes how to build (the recipe), and each run of it is a Build (a record and a Pod that does the work). The finished image is pushed to the registry and, typically, tagged in an ImageStream.

The anatomy of a BuildConfig

YAML
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: web
spec:
  source:
    type: Git
    git:
      uri: https://github.com/example/web-app.git
      ref: main
    contextDir: /
  strategy:
    type: Docker
    dockerStrategy:
      dockerfilePath: Dockerfile
  output:
    to:
      kind: ImageStreamTag
      name: web:latest
  triggers:
    - type: ConfigChange
    - type: ImageChange
    - type: GitHub
      github:
        secretReference:
          name: web-webhook-secret
  resources:
    limits:
      memory: 1Gi

Three blocks answer three questions:

  1. source: where is the code? (Git repository and branch, a Dockerfile text, uploaded binary content, or inline files)
  2. strategy: how is it built?
  3. output: where does the image go? (an ImageStreamTag, or a DockerImage in an external registry with a push secret)

Build strategies

Strategy You provide Result
Source (S2I) Application source A builder image combines it with your code; no Dockerfile needed. See Source-to-Image.
Docker A Dockerfile in the repository The image is built from the Dockerfile with a rootless builder.
Pipeline A Jenkins pipeline Legacy. Use OpenShift Pipelines (Tekton) instead.
Custom A builder image of your own Advanced; runs privileged work. Rarely needed.

Builds in OpenShift 4 run as Pods in your project and do not need Docker on any node. Docker builds run with the project's builder service account and obey the cluster's security policy.

Starting and following builds

Terminal
oc new-build https://github.com/example/web-app.git --name=web --strategy=docker
oc start-build web --follow
oc get builds
oc logs build/web-1
oc cancel-build web-1
oc describe bc/web
  • oc new-build creates the BuildConfig (and ImageStream) without a deployment.
  • oc start-build web --follow starts a run and streams logs.
  • Build names are <bc-name>-<number>; the number increases with each run.

Typical build phases: New, Pending, Running, then Complete, Failed, Error or Cancelled. Pull problems, a missing Dockerfile, or a build Pod killed for memory are the usual causes of failure.

Triggers: when does a build start?

  • ConfigChange: automatically start the first build after the BuildConfig is created.
  • ImageChange: rebuild when the base image tag changes. A security patch to the base image can rebuild every app on it.
  • Webhook (GitHub, GitLab, Bitbucket, Generic): a push to the repository calls a URL on the cluster API and starts a build. Webhook URLs contain a secret; keep them private.
Terminal
oc describe bc/web | grep -i webhook
oc set triggers bc/web --from-github
oc set triggers bc/web --from-image=ubi9/nodejs-20:latest
oc set triggers bc/web --remove-all

Binary and inline builds

Sometimes you want to build from your working directory, with no Git push, for quick experiments:

Terminal
oc new-build --name=web --binary --strategy=docker
oc start-build web --from-dir=. --follow
oc start-build web --from-file=target/app.jar

--from-dir uploads a directory; --from-file uploads one file such as a compiled JAR; --from-archive uploads a tarball. This is good for development, but production builds should come from Git or a pipeline so they are repeatable.

Private repositories and secrets

For private Git sources, create a source secret and link it:

Terminal
oc create secret generic git-auth --from-literal=username=me --from-literal=password=<token> --type=kubernetes.io/basic-auth
oc set build-secret --source bc/web git-auth

For pushing to an external registry, add a push secret under output.pushSecret. For pulling private base images, link a pull secret to the builder service account: oc secrets link builder regcred.

Build environments and chaining

You can pass environment variables to a build (spec.strategy.sourceStrategy.env or dockerStrategy.env), set build args for Dockerfiles, limit resources and chain builds: one build produces an artifact image, another copies that artifact into a slim runtime image.

The future of builds

Red Hat has described Builds for Red Hat OpenShift (based on the Shipwright project) as the next-generation build mechanism, with Build and BuildRun objects, alongside OpenShift Pipelines. The classic BuildConfig API is still widely used, so learning it is worthwhile. Check current product documentation for the supported choice in your version.

Stand-in: a build state machine

This stand-in models the phases of a build and the effect of failures. It is a teaching model of the lifecycle, not the build controller.

Python Stand-in: build phases

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: which triggers fire?

Python Stand-in: trigger evaluation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What are the three main blocks of a BuildConfig spec?

    A BuildConfig says where the code comes from (source), how to build it (strategy) and where the image goes (output).
  2. 2. Which command starts a build and streams its logs?

    oc start-build creates a new Build; --follow streams the build log.
  3. 3. What does an ImageChange trigger on a BuildConfig watch?

    When the base image tag is updated, the BuildConfig can rebuild so apps pick up patches.
  4. 4. When is oc start-build --from-dir most appropriate?

    Binary builds skip Git for fast development. Production builds should be repeatable from source control or a pipeline.

Summary

  • A BuildConfig defines source, strategy and output; each run is a Build executed in a Pod.
  • Strategies: Source (S2I), Docker, Custom (and a legacy Jenkins pipeline strategy).
  • Triggers include ConfigChange, ImageChange and webhooks from Git hosts.
  • Binary builds upload local files for experiments; use Git or pipelines for production.
  • Use secrets for private Git sources and registries.

Next: Source-to-Image (S2I)