OpenShift Image Mirroring Guide

This document explains how OpenShift container images are structured, how to generate a manifest of required images, and the APIs available for querying release information.

Overview

OpenShift releases are distributed as a collection of container images hosted on quay.io. The release structure uses a unique pattern where all component images are stored in a single repository, referenced by SHA256 digest.

Image Repository Structure

Repository	Purpose	Authentication
quay.io/openshift-release-dev/ocp-release	Release manifest images (the "umbrella" image)	Public
quay.io/openshift-release-dev/ocp-v4.0-art-dev	All component images (etcd, apiserver, cli, etc.)	Requires Red Hat pull secret

Understanding ocp-v4.0-art-dev

The ocp-v4.0-art-dev repository is a content-addressable store - a single repository holding all OpenShift component images. Each SHA256 digest points to a completely different container image:

quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:abc123...  → etcd
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:def456...  → apiserver
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:789ghi...  → cli

Important notes:

• The "dev" in the name refers to the OpenShift Release Development team, NOT development/unstable builds
• These are official production release images
• Component images have NO tags at the source - they are referenced only by digest
• Tags are created by mirroring tools at the destination registry

APIs for Querying Release Information

1. Cincinnati API (Version Graph)

The Cincinnati API provides information about available versions, upgrade paths, and release image references.

Get available versions in a channel:

curl -s "https://api.openshift.com/api/upgrades_info/v1/graph?channel=stable-4.20&arch=amd64" | jq '.nodes[].version'

Get release image digest for a specific version:

curl -s "https://api.openshift.com/api/upgrades_info/v1/graph?channel=stable-4.20&arch=amd64" | \
  jq -r '.nodes[] | select(.version == "4.20.8") | .payload'

Output:

quay.io/openshift-release-dev/ocp-release@sha256:91606a5f04331ed3293f71034d4f480e38645560534805fe5a821e6b64a3f203

Available channels:

• stable-4.x - Production-ready releases
• fast-4.x - Early access to stable releases
• candidate-4.x - Release candidates
• eus-4.x - Extended Update Support versions

Available architectures:

• amd64 (x86_64)
• arm64
• ppc64le
• s390x

2. oc adm release info

The oc client can extract detailed component information from a release image.

Basic release info:

oc adm release info quay.io/openshift-release-dev/ocp-release:4.20.8-x86_64

Get component images with full pull specs:

oc adm release info quay.io/openshift-release-dev/ocp-release:4.20.8-x86_64 --pullspecs

Get JSON output for programmatic access:

oc adm release info quay.io/openshift-release-dev/ocp-release:4.20.8-x86_64 -o json | jq '{
  version: .metadata.version,
  digest: .digest,
  component_count: (.references.spec.tags | length),
  components: [.references.spec.tags[] | {name: .name, image: .from.name}]
}'

Generating a Manifest with oc-mirror

Installation

Download from the OpenShift mirror:

curl -sL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/oc-mirror.tar.gz | tar -xz
chmod +x oc-mirror
./oc-mirror version

ImageSetConfiguration

Create an imageset-config.yaml file:

kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v2alpha1
mirror:
  # OpenShift Platform Release
  platform:
    channels:
    - name: stable-4.20
      minVersion: 4.20.0      # optional: specific version range
      maxVersion: 4.20.8      # optional: specific version range
      shortestPath: true      # optional: only versions needed for upgrade path
      full: false             # optional: mirror ALL versions in channel
    architectures:            # optional: default is just x86_64
    - amd64
    - arm64
    graph: true               # include Cincinnati upgrade graph data
    kubeVirtContainer: true   # include KubeVirt container image

  # Operators (from catalog)
  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.20
    packages:                 # optional: if omitted, mirrors ALL operators
    - name: elasticsearch-operator
    - name: cluster-logging
      channels:
      - name: stable-6.0     # optional: specific channel
    full: false              # false = heads only, true = all versions

  # Additional Images (any container image)
  additionalImages:
  - name: registry.redhat.io/ubi9/ubi:latest
  - name: quay.io/myorg/myapp@sha256:abc123...

  # Helm Charts
  helm:
    repositories:
    - name: bitnami
      url: https://charts.bitnami.com/bitnami
      charts:
      - name: nginx
        version: 15.0.0

  # Blocked Images (exclude from mirroring)
  blockedImages:
  - name: quay.io/some/unwanted-image:tag

Running a Dry-Run to Generate Manifest

oc-mirror --v2 --config imageset-config.yaml file:///path/to/output --dry-run

This generates:

• working-dir/dry-run/mapping.txt - All images in source=destination format
• working-dir/dry-run/missing.txt - Images not in local cache

Extracting a Clean Image List

cat working-dir/dry-run/mapping.txt | cut -d'=' -f1 | sed 's|^docker://||' | sort > manifest.txt

Manifest Format

Raw mapping.txt format (from oc-mirror)

docker://quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:abc123...=docker://localhost:55000/openshift/release:4.20.8-x86_64-etcd
docker://quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:def456...=docker://localhost:55000/openshift/release:4.20.8-x86_64-apiserver

Clean source image list

quay.io/openshift-release-dev/ocp-release:4.20.8-x86_64
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:0092c6ff139f8698c91349d507eb3182bc5d6c4ae040f672e347ff504accdea2
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:028f66041c7195838b54d95b97fc05b4a4d3a965b069eabeb63d0c41c8fa9c9b
...

With component names (from oc adm release info)

agent-installer-api-server     quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f38d9f25...
agent-installer-csr-approver   quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:c5b84202...
etcd                           quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:3223f3de...
...

Authentication

Red Hat Pull Secret

The ocp-v4.0-art-dev repository requires authentication. Obtain your pull secret from: https://console.redhat.com/openshift/install/pull-secret

Configure authentication:

# Default locations checked by tools:
# - $XDG_RUNTIME_DIR/containers/auth.json (podman)
# - ~/.docker/config.json (docker)

# Or specify explicitly:
oc-mirror --v2 --config imageset-config.yaml --authfile /path/to/pull-secret.json ...

Example: Complete Workflow

# 1. Download tools
curl -sL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/oc-mirror.tar.gz | tar -xz
curl -sL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/openshift-client-linux.tar.gz | tar -xz

# 2. Check available versions
curl -s "https://api.openshift.com/api/upgrades_info/v1/graph?channel=stable-4.20&arch=amd64" | \
  jq -r '.nodes[].version' | sort -V

# 3. Create configuration
cat > imageset-config.yaml << 'EOF'
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v2alpha1
mirror:
  platform:
    channels:
    - name: stable-4.20
    graph: false
EOF

# 4. Generate manifest (dry-run)
./oc-mirror --v2 --config imageset-config.yaml file:///tmp/mirror-output --dry-run

# 5. Extract clean image list
cat /tmp/mirror-output/working-dir/dry-run/mapping.txt | \
  cut -d'=' -f1 | sed 's|^docker://||' | sort > manifest.txt

# 6. View results
wc -l manifest.txt  # Count of images
cat manifest.txt    # Full list

Image Counts (Typical)

Content Type	Approximate Image Count
Single OCP release (x86_64)	~193 images
Single OCP release (multi-arch)	~770 images
Red Hat Operator Catalog (full)	~5000+ images
Red Hat Operator Catalog (heads-only)	~1000+ images

API-Only Manifest Generation (No Tools Required)

You can generate a manifest using only curl and jq by directly querying the OCI registry APIs. The release image contains a file called image-references that lists all component images.

How It Works

1. Query Cincinnati API to get the release image digest
2. Get an auth token from quay.io
3. Fetch the release manifest to find the layer containing metadata
4. Extract release-manifests/image-references from that layer

Script: get-ocp-manifest.sh

A complete script is provided at get-ocp-manifest.sh. Usage:

# Get manifest for specific version
./get-ocp-manifest.sh 4.20.8

# Get manifest for latest in channel
./get-ocp-manifest.sh "" stable-4.20

# Different output formats
OUTPUT_FORMAT=json ./get-ocp-manifest.sh 4.20.8
OUTPUT_FORMAT=images-only ./get-ocp-manifest.sh 4.20.8 > manifest.txt

# Different architecture
./get-ocp-manifest.sh 4.20.8 stable-4.20 arm64

Manual API Calls

# Step 1: Get release image from Cincinnati
VERSION="4.20.8"
CHANNEL="stable-4.20"
ARCH="amd64"

RELEASE_IMAGE=$(curl -s "https://api.openshift.com/api/upgrades_info/v1/graph?channel=${CHANNEL}&arch=${ARCH}" | \
  jq -r --arg v "$VERSION" '.nodes[] | select(.version == $v) | .payload')

echo "Release image: $RELEASE_IMAGE"
# Output: quay.io/openshift-release-dev/ocp-release@sha256:91606a5f04331ed3293f71034d4f480e38645560534805fe5a821e6b64a3f203

# Step 2: Get auth token
TOKEN=$(curl -s "https://quay.io/v2/auth?service=quay.io&scope=repository:openshift-release-dev/ocp-release:pull" | jq -r '.token')

# Step 3: Get the manifest to find the metadata layer
DIGEST="sha256:91606a5f04331ed3293f71034d4f480e38645560534805fe5a821e6b64a3f203"
MANIFEST=$(curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  "https://quay.io/v2/openshift-release-dev/ocp-release/manifests/$DIGEST")

# The smallest layer contains release-manifests/
LAYER_DIGEST=$(echo "$MANIFEST" | jq -r '.layers | sort_by(.size) | .[0].digest')

# Step 4: Extract image-references
curl -sL -H "Authorization: Bearer $TOKEN" \
  "https://quay.io/v2/openshift-release-dev/ocp-release/blobs/$LAYER_DIGEST" | \
  tar -xzf - -O release-manifests/image-references | \
  jq -r '.spec.tags[] | .from.name'

Output Formats

JSON (full metadata):

{
  "version": "4.20.8",
  "release_image": "quay.io/openshift-release-dev/ocp-release@sha256:...",
  "component_count": 192,
  "components": [
    {
      "name": "etcd",
      "image": "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...",
      "source_repo": "https://github.com/openshift/etcd"
    }
  ]
}

Images-only (one per line):

quay.io/openshift-release-dev/ocp-release@sha256:91606a5f04331ed3293f71034d4f480e38645560534805fe5a821e6b64a3f203
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f38d9f25606e8bc4ea36584051cc416b693822c224be952fe9db434a582946b4
quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:c5b84202ac20b958240d091e5bda026594ff781434ee8438de74477fa5e00d0e
...

References

• oc-mirror GitHub Repository
• Cincinnati Project
• OpenShift Documentation - Mirroring
• Red Hat Pull Secret
• Cincinnati API