OpenShift ImageStreams

Learn how OpenShift ImageStreams manage container images, enable automatic deployments, simplify image versioning, and integrate with BuildConfig for Spring Boot applications.

Introduction

Container images are the foundation of every OpenShift deployment. Whenever you deploy a Spring Boot application, OpenShift runs a container image inside one or more Pods.

Instead of directly referencing Docker or OCI images, OpenShift introduces a powerful abstraction called an ImageStream.

An ImageStream tracks image versions, enables automatic deployments, and integrates seamlessly with BuildConfigs and DeploymentConfigs.

In this article, you'll learn how ImageStreams work, why they are important, and how enterprises use them to manage application deployments.

Learning Objectives

By the end of this article, you will understand:

What is an ImageStream?
Why ImageStreams exist
ImageStream architecture
Image tags
Internal vs External registries
Image Change Triggers
BuildConfig integration
Deployment integration
Enterprise use cases
Best practices

What is an ImageStream?

An ImageStream is an OpenShift resource that tracks one or more versions of a container image.

Instead of pointing directly to:

quay.io/company/payment-api:1.0

Applications reference:

payment-api:latest

The ImageStream internally maps this tag to the actual container image.

Why Do We Need ImageStreams?

Without ImageStreams:

Applications must reference image registry URLs directly.
Updating image versions requires modifying Deployment YAML files.
Rollbacks become more difficult.
Build automation is limited.

ImageStreams simplify image management.

ImageStream Architecture

flowchart LR
    GIT["Git Repository"]
    BC["BuildConfig"]
    BUILD["Build Pod"]
    IS["ImageStream"]
    DEPLOY["Deployment"]
    PODS["Pods"]

    GIT --> BC
    BC --> BUILD
    BUILD --> IS
    IS --> DEPLOY
    DEPLOY --> PODS

The ImageStream acts as the bridge between image creation and deployment.

Image Build Flow

flowchart TD

Developer
    --> Git

Git
    --> BuildConfig

BuildConfig
    --> Build

Build
    --> ImageStream

ImageStream
    --> Deployment

Deployment
    --> Pod

Every successful build updates the ImageStream.

ImageStream Components

An ImageStream contains:

Image Name
Tags
Image Metadata
Registry Location
Image History

Example:

payment-api

├── latest
├── v1.0
├── v1.1
├── v2.0

Image Tags

Image tags identify different versions.

Example:

Tag	Description
latest	Current image
v1.0	First release
v1.1	Bug fixes
v2.0	New features

Applications usually reference a tag instead of a specific image digest.

ImageStream Tags

flowchart TD

ImageStream

--> latest

ImageStream

--> v1.0

ImageStream

--> v1.1

ImageStream

--> v2.0

This allows multiple versions of the same application to coexist.

Internal Image Registry

OpenShift includes an internal image registry.

flowchart LR
    BUILD["Build"]
    REGISTRY["Internal Registry"]
    IS["ImageStream"]
    DEPLOY["Deployment"]

    BUILD --> REGISTRY
    REGISTRY --> IS
    IS --> DEPLOY

Advantages:

Faster deployments
Secure image storage
Internal networking
No external registry dependency

External Registry

ImageStreams can also track images stored externally.

Examples:

Docker Hub
Quay.io
Amazon ECR
Azure Container Registry
Google Artifact Registry

flowchart LR

DockerHub

--> ImageStream

Quay

--> ImageStream

ECR

--> ImageStream

ImageStream

--> Deployment

Image Change Trigger

One of the most powerful ImageStream features is automatic deployment.

Whenever an image changes:

flowchart LR
    IMG["New Container Image"]
    IS["ImageStream"]
    DC["DeploymentConfig / Deployment Trigger"]
    RS["ReplicaSet"]
    PODS["New Pods"]

    IMG --> IS
    IS --> DC
    DC --> RS
    RS --> PODS

No manual deployment is required.

Spring Boot Build Example

Developer pushes code.

sequenceDiagram

participant Developer

participant Git

participant BuildConfig

participant ImageStream

participant Deployment

Developer->>Git: Push Code

Git->>BuildConfig: Start Build

BuildConfig->>ImageStream: Push Image

ImageStream->>Deployment: Trigger Deployment

Deployment->>Deployment: Rolling Update

Image Promotion

Enterprises promote images through environments.

flowchart LR

Development

--> QA

QA

--> UAT

UAT

--> Production

The same tested image is promoted instead of rebuilding.

Banking Example

Suppose a Payment API releases Version 2.0.

flowchart LR
    DEV["Developer"]
    GIT["Git Repository"]
    BC["BuildConfig"]
    IMG["payment-api:v2.0"]
    IS["ImageStream"]
    DEPLOY["Payment Deployment"]
    USERS["Customers"]

    DEV --> GIT
    GIT --> BC
    BC --> IMG
    IMG --> IS
    IS --> DEPLOY
    DEPLOY --> USERS

Once the ImageStream updates, Deployment automatically performs a rolling update.

Creating an ImageStream

apiVersion: image.openshift.io/v1
kind: ImageStream

metadata:
  name: payment-api

Create it:

oc apply -f imagestream.yaml

List ImageStreams

oc get imagestreams

Example:

NAME            TAGS

payment-api     latest,v1.0,v2.0

Describe ImageStream

oc describe is payment-api

Shows:

Tags
Registry
Image history
Image metadata

Import Image

Import an external image.

oc import-image payment-api \
--from=quay.io/company/payment-api:1.0 \
--confirm

The image is now managed by the ImageStream.

Image Versioning

flowchart LR

v1.0

--> v1.1

--> v2.0

--> v2.1

--> latest

ImageStreams maintain image history, making rollback easier.

Rollback Example

Suppose Version 2.0 has a bug.

flowchart LR

v1.0

--> v2.0

v2.0

--> Rollback

Rollback

--> v1.0

Rollback becomes much simpler because older image versions are already tracked.

ImageStream vs Docker Image

Docker Image	ImageStream
Physical image	Logical image reference
Stored in Registry	Managed inside OpenShift
Manual updates	Automatic tracking
Registry specific	Registry independent
No deployment triggers	Supports automatic deployment

Enterprise Deployment Flow

flowchart LR

Developer

--> Git

Git

--> BuildConfig

BuildConfig

--> ImageStream

ImageStream

--> Deployment

Deployment

--> Service

Service

--> Route

Route

--> Users

ImageStreams act as the central image management layer.

Best Practices

Use ImageStreams for all OpenShift deployments.
Avoid referencing external images directly in Deployments.
Use versioned image tags.
Promote tested images between environments.
Keep ImageStreams under version control.
Enable automatic image change triggers.
Clean up unused image tags regularly.

Common Mistakes

❌ Using latest for production deployments.

❌ Rebuilding images for every environment.

❌ Deploying directly from Docker Hub.

❌ Deleting ImageStreams accidentally.

❌ Ignoring image history.

Advantages

Image version management
Automatic deployments
Simplified rollbacks
Registry abstraction
Better CI/CD integration
Faster deployments
Enterprise image lifecycle management

Summary

ImageStreams are one of OpenShift's key enterprise features.

Key takeaways:

ImageStreams track and manage container images.
They provide a stable abstraction over container registries.
BuildConfigs push images into ImageStreams.
Deployments consume images from ImageStreams.
Image Change Triggers automate application deployments.
ImageStreams simplify versioning, rollback, and environment promotion.

Understanding ImageStreams is essential for building production-ready Java applications on OpenShift.

Interview Questions

What is an ImageStream?
Why does OpenShift use ImageStreams instead of Docker images directly?
What is an Image Change Trigger?
How do BuildConfigs interact with ImageStreams?
How do Deployments consume ImageStreams?
What is the difference between an ImageStream and a container registry?
How do you import an external image?
Why are ImageStreams useful for CI/CD?
How do ImageStreams support rollback?
What are the best practices for managing ImageStreams?