OpenShift BuildConfig Tutorial

✅ What is OpenShift BuildConfig?

BuildConfig in OpenShift is a Kubernetes-native custom resource provided by OpenShift that defines how to build a container image from source code. It automates the end-to-end image build process — from fetching source code to producing and storing container images — using build strategies like Source-to-Image (S2I), Docker, or custom workflows.

📘 BuildConfig Definition

A BuildConfig is a declarative configuration object in OpenShift that defines the strategy, source, triggers, and output for building container images automatically or on-demand.

It’s like a recipe for converting application source code into a deployable container image.

⭐ Key Features of BuildConfig

Feature	Description
🎯 Multiple Build Strategies	Supports S2I, Dockerfile, and Custom strategies.
🔗 Git Integration	Pulls source code directly from public/private Git repositories.
🔁 Automatic Triggers	Rebuilds can be triggered by Git changes, image changes, or config changes.
🛠 Custom Build Environment	Supports environment variables, secrets, and configmaps during builds.
🏷️ ImageStream Integration	Built images can be pushed to internal ImageStreams or external registries.
👥 Webhooks	Allows GitHub/GitLab to trigger builds via webhooks.
🔍 Build Logs & History	Easily view build logs, status, and retry failed builds.
🔐 Secure Build Contexts	Supports source credentials, secrets, and isolated build pods.

🔧 Example Use Cases

Scenario	How BuildConfig Helps
CI/CD automation	Auto-rebuild on Git push or base image update
DevOps in hybrid cloud	Works with internal and external image registries
Compliance & traceability	Full build history and image tracking
S2I app deployment (Node.js, Python, etc.)	Uses language-specific builder images

📦 BuildConfig vs Dockerfile vs Pipelines

Tool/Concept	Role
BuildConfig	Defines how to build an image from source
Dockerfile	Manual build instructions (used in Docker strategy)
Pipelines	Orchestrates multiple stages/jobs (Tekton-based)

🚀 BuildConfig Lifecycle

Developer pushes code to Git
OpenShift triggers a build (via webhook or manually)
Code is fetched and built using specified strategy
Final image is stored (ImageStream or registry)
App is deployed or updated automatically

✅ Works on OpenShift 4.13+ (including Azure Red Hat OpenShift)

🎯 Goal

Build a Node.js application using:

✅ Git source
✅ External Red Hat base image (ubi8/nodejs-16)
✅ OpenShift S2I strategy (using DockerImage)
✅ No need for preloaded ImageStreams

🧱 Prerequisites

Requirement	Details
OpenShift cluster	Access to 4.13+ (Azure, local, etc.)
Project created	Use `oc new-project` or create via Web UI
GitHub repo with app code	e.g., `sclorg/nodejs-ex`
OpenShift CLI (optional)	`oc` logged in

🧾 Option 1: YAML Method (CLI or Web Console YAML Editor)

✅ Step-by-Step (Using YAML)

Create/Open a project oc new-project nodejs-s2i-demo
Apply this working BuildConfig YAML:

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: nodejs-sample-build
  labels:
    app: nodejs-sample
spec:
  source:
    type: Git
    git:
      uri: https://github.com/sclorg/nodejs-ex.git
      ref: main
    contextDir: .
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: registry.access.redhat.com/ubi8/nodejs-16
      forcePull: true
  output:
    to:
      kind: ImageStreamTag
      name: nodejs-sample:latest
  triggers:
    - type: ConfigChange
    - type: ImageChange
  runPolicy: Serial
Code language: JavaScript (javascript)

Start the build manually: oc start-build nodejs-sample-build --follow
Deploy the built image: oc new-app nodejs-sample oc expose svc/nodejs-sample
Access the app: oc get route

🖱️ Option 2: Using the OpenShift Developer Console UI

Based on your screenshots — modern and guided flow

✅ Step-by-Step (Using Developer Web Console)

Go to Developer → +Add → From Git
Fill Git Repository info:
- Git Repo URL: https://github.com/sclorg/nodejs-ex.git
- Git Reference: main (or leave blank)
- Context Dir: .
Builder Image Selection (Build from):
- Select “Docker Image” from the build option dropdown
- Input Docker Image: registry.access.redhat.com/ubi8/nodejs-16
Deployment Settings:
- App Name: nodejs-sample
- Resources: Deployment (leave default)
- Create Route: ✅ (enabled)
Click “Create”

OpenShift will:

Create BuildConfig, ImageStream, Deployment, and Route
Trigger an initial build
Watch progress from Builds or Topology

🧪 How to Monitor

Build logs:
Developer → Builds → nodejs-sample-build → View Logs
Application route:
Developer → Topology → Click route link
BuildConfig YAML:
Admin → Builds → nodejs-sample-build → YAML

🔁 Updating Code

Just push code to GitHub and trigger a build manually:

oc start-build nodejs-sample-build

Or setup GitHub webhook using:

oc describe bc nodejs-sample-build

✅ Summary

Step	UI Path	YAML Equivalent
Git source	From Git	`source.git.uri`
Docker image	Select “Docker Image”	`strategy.sourceStrategy.from.kind: DockerImage`
Deployment	Auto-created via +Add	Use `oc new-app` after build manually
Route	Enabled in UI	`oc expose svc/nodejs-sample`

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs