Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Builds and Pipelines

ImageStreams and Tags

Learn how ImageStreams track image tags by digest, how to import and tag images with oc, use the internal registry, and trigger rollouts when a tag changes.

An ImageStream is an OpenShift object that acts as a stable name and history for container images. It does not store image data itself. It stores references: for each tag, the list of image digests that tag has pointed to over time. Builds push into it, Deployments read from it, and triggers react when a tag moves.

Why not just use image names?

A plain image reference such as quay.io/example/web:1.0 has weaknesses:

  • Tags are mutable: the same tag can later point to different content.
  • The cluster only learns about a new image when somebody changes the Deployment.
  • Every project would pull from external registries separately.

An ImageStream gives you:

  • One name inside the cluster (web:latest) regardless of where the bytes live.
  • Digest tracking: you can see exactly which sha256:... each tag points to.
  • Triggers: update a tag and builds or deployments can start automatically.
  • Local caching of pulled content through the integrated registry (optional).

Looking at ImageStreams

Terminal
oc get imagestream
oc get is -n openshift
oc describe is web
oc get istag
oc get istag web:latest -o yaml

An ImageStream named web has tags such as web:latest and web:v1. Each ImageStreamTag is name:tag. The history shows several digests per tag, newest first.

A reference by digest looks like image-registry.openshift-image-registry.svc:5000/shop-dev/web@sha256:3f1c.... That host is the internal registry's service address, reachable from inside the cluster.

Creating and importing

Terminal
oc create imagestream web
oc import-image web:1.0 --from=quay.io/example/web:1.0 --confirm
oc import-image web:1.0 --from=quay.io/example/web:1.0 --confirm --scheduled=true
oc tag quay.io/example/web:1.1 web:1.1
oc tag web:1.1 web:stable
oc tag --alias web:1.1 web:current
oc tag -d web:old
  • oc import-image copies the metadata (the digest) of an external image into the stream. It does not, by default, copy the layers; pulls go to the original registry unless you ask for local mirroring with --reference-policy=local.
  • --scheduled=true re-checks the source on a schedule (about every 15 minutes by default) so a changed external tag updates the stream.
  • oc tag source dest creates or moves a tag. Promoting an image between stages is often just oc tag web:test web:prod.
  • Tagging an image from one project to another makes it available across projects when permissions allow, using oc policy add-role-to-user system:image-puller <user> -n <source-project>.

ImageStreams in YAML

YAML
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: web
spec:
  lookupPolicy:
    local: true
  tags:
    - name: "1.0"
      from:
        kind: DockerImage
        name: quay.io/example/web:1.0
      importPolicy:
        scheduled: true
      referencePolicy:
        type: Local

lookupPolicy.local: true lets a Deployment write image: web:1.0 and have OpenShift resolve it through the ImageStream in the same project. Without it, you reference the image with the full internal registry path, or use triggers.

Triggers: redeploy when a tag changes

Terminal
oc set triggers deployment/web --from-image=web:latest -c web
oc set triggers deployment/web
oc set triggers deployment/web --remove-all

This annotates the Deployment so that when web:latest points to a new digest, OpenShift updates the container image to that digest and rolls out. Combined with a build that pushes web:latest, you get commit to build to deploy with no extra tooling:

flowchart LR
  G["git push"] --> BC["BuildConfig"]
  BC --> IS["ImageStream web:latest"]
  IS -->|"image change trigger"| D["Deployment rolls out"]

Figure: a moved tag triggers a rollout.

Triggers are convenient in dev. For production, many teams prefer promoting a specific, tested digest through Git (GitOps) so each release is explicit.

The internal registry

OpenShift runs an image registry in openshift-image-registry. Builds push to it automatically. To push or pull from your laptop, an administrator may expose it with a route.

Terminal
oc whoami -t
oc get route default-route -n openshift-image-registry
podman login -u $(oc whoami) -p $(oc whoami -t) <registry-route-host>
podman push localimage:1.0 <registry-route-host>/shop-dev/web:1.0

Treat the token like a password. On some clusters the internal registry is not installed or not exposed; follow your administrator's guidance. Many organizations also use an external registry such as Quay and use ImageStreams only as pointers.

Pull secrets

Pulling from a private external registry needs a pull secret:

Terminal
oc create secret docker-registry regcred --docker-server=registry.example.com \
  --docker-username=me --docker-password='...'
oc secrets link default regcred --for=pull
oc secrets link builder regcred

--for=pull links the secret to the default service account so Pods in the project can pull. The cluster-wide pull secret in openshift-config covers Red Hat's own registries.

Image pruning

Registries grow. Administrators prune old, unreferenced images:

Terminal
oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m
oc adm prune builds --orphans

Both commands are dry runs until you add --confirm.

Stand-in: tags move, digests do not

This stand-in models an ImageStream tag history. It uses made-up digests, but the behaviour matches the real concept: a tag points to the newest digest and old ones stay recorded.

Python Stand-in: tag history and triggers

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.

The second push of identical content produces the same digest, so no rollout starts. A tag that does not move to new content triggers nothing.

Stand-in: promotion between tags

Python Stand-in: promote an image dev to test to prod

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 does an ImageStream store?

    An ImageStream stores metadata about images, not the image layers themselves.
  2. 2. Which command promotes an image from the test tag to the prod tag?

    oc tag copies the reference from one tag to another.
  3. 3. What does --scheduled=true on oc import-image do?

    Scheduled imports keep an ImageStream tag in sync with an external registry tag.
  4. 4. Why can image change triggers be risky in production?

    Teams often prefer to promote a specific digest through Git so each release is a deliberate change.

Summary

  • An ImageStream is a named set of tags that reference image digests; it stores no layers.
  • Import external images with oc import-image, move tags with oc tag, and keep them fresh with --scheduled.
  • lookupPolicy.local and triggers let Deployments follow a tag.
  • The internal registry holds build output; pull secrets give access to private registries.
  • Prune old images regularly (dry run first).

Next: OpenShift Pipelines (Tekton)