OpenShift Internal Registry: Push, Pull, and Promote Images Without Rebuilding

The problem and the useful takeaway

Many OpenShift teams configure CI/CD pipelines to push images to Docker Hub, Quay.io, or a cloud registry, then pull them back into the cluster. That works, but it adds external credentials, network egress, and an extra build when promoting an image from staging to production.

OpenShift includes a built-in Docker-compatible image registry in the openshift-image-registry project. You can authenticate with your oc session or a service account token, push directly to an internal endpoint, and promote an image by moving a tag between image streams. The deployment pulls the same image digest without rebuilding the container.

Useful takeaway: treat the internal registry as your CI/CD image source. Push once, tag-promote across namespaces, and let image streams trigger rollouts.

How the internal registry works

The registry runs as an Operator-managed deployment in openshift-image-registry. It is reachable inside the cluster at image-registry.openshift-image-registry.svc:5000. OpenShift image streams are namespaced resources that track tags and point to image digests. When you tag myapp:staging to myapp:prod, OpenShift updates the reference; any deployment watching myapp:prod rolls out using the already-built image.

Worked configuration: push, tag, and promote

Run these commands from a workstation with the oc CLI logged into the cluster. Replace placeholders in angle brackets.

Permissions: You need edit or higher in the target project to push and create image streams. Cluster administrators can adjust quotas; project developers cannot change cluster-level resource quotas.

1. Confirm the registry is running

oc get pods -n openshift-image-registry

Expected result: at least one registry pod shows Running. If the pod is CrashLoopBackOff or Pending, storage or Operator configuration may need attention before pushing.

2. Authenticate to the registry

oc registry login

This command configures your local container client to use your OpenShift OAuth token. For CI/CD systems that cannot run oc registry login, use a service account bearer token:

oc whoami -t

Use that token as the password with any username when logging in to image-registry.openshift-image-registry.svc:5000.

3. Push an image

podman tag localhost/myapp:v1 image-registry.openshift-image-registry.svc:5000/<project>/myapp:v1
podman push image-registry.openshift-image-registry.svc:5000/<project>/myapp:v1

Risk: If the project quota or image size limit is exceeded, the push fails with a quota or size error. Do not use --insecure-registry; it disables TLS and exposes image traffic to interception.

4. Promote the tag with an image stream

oc tag <project>/myapp:staging <project>/myapp:prod

This does not rebuild the image. It creates a tag reference in the image stream pointing to the same digest. Deployments configured for myapp:prod will roll out using the promoted image.

5. Verify the pull

oc run verify-image --image=image-registry.openshift-image-registry.svc:5000/<project>/myapp:v1 --restart=Never

Expected check: the pod reaches Completed. Then inspect the image stream:

oc get imagestream -n <project>

You should see myapp with tags including staging and prod.

Storage and persistence

The registry pod must use a persistent volume claim (PVC). emptyDir storage loses images when the pod restarts. Supported production backends include NFS, Ceph RBD, and cloud block storage, attached through a PVC to the registry deployment. Because the Cluster Version Operator manages the registry, do not edit the registry pod directly or attempt manual upgrades; changes are applied with cluster upgrades.

Limits and common mistakes

• Push failures from quotas: Default image size and project quotas can reject pushes. Check with oc get clusterquota and oc describe imagestream -n <project>. Administrators can adjust quotas with oc edit resourcequota or oc edit clusterresourcequota.
• External CI cannot reach the registry: If the registry is not exposed through a route or service, external systems cannot pull images. Create a route or expose the service, and restrict access with network policies where appropriate.
• Insecure registry flag: Adding --insecure-registry disables TLS verification and exposes image traffic to interception. Avoid it.
• Assuming image streams are images: An image stream is a metadata pointer, not a storage repository. Tag promotion updates the pointer; the image blob remains in the registry storage.
• Manual pod edits are unsupported: The registry is managed by the Cluster Version Operator. Direct edits to the deployment or pod may be overwritten during upgrades.

How to verify the result

After completing the worked example:

1. oc get pods -n openshift-image-registry shows the registry pod Running.
2. oc get imagestream -n <project> lists myapp with the promoted tags.
3. oc run verify-image ... --restart=Never completes successfully.
4. oc describe imagestream myapp -n <project> shows the prod tag pointing to the same digest as staging.

If any check fails, inspect oc describe pod -n openshift-image-registry <registry-pod> for storage or certificate errors, and check project quotas for push rejections.