Configure ImageTagMirrorSet for Red Hat Edge Manager images

Configure Red Hat OpenShift Container Platform to pull Red Hat Edge Manager container images from your private registry instead of upstream registries. Apply this configuration before you install or upgrade the Helm release in a disconnected cluster.

Before you begin

  • Cluster administrator permissions
  • Images mirrored per Preparing offline container images and the Helm chart
  • artifact-manifest-<variant>.yaml from the mirror step, or an equivalent list of upstream prefixes you mirrored
  • Red Hat OpenShift Container Platform 4.19 or later

Procedure

  1. Create a manifest that maps each source registry prefix to your internal registry. Use the following example as a starting point and adjust entries to match artifact-manifest-<variant>.yaml from your mirror step: 
    apiVersion: config.openshift.io/v1
kind: ImageTagMirrorSet
metadata:
  name: flightctl-airgap
spec:
  imageTagMirrors:
  - source: registry.redhat.io
    mirrorSourcePolicy: NeverContactSource
    mirrors:
    - mirror: <local-registry>/<path>
  - source: registry.access.redhat.com
    mirrorSourcePolicy: NeverContactSource
    mirrors:
    - mirror: <local-registry>/<path>

    Set mirrorSourcePolicy on each imageTagMirrors entry:

    • NeverContactSource — pull only from mirrors; fail if no mirror works. Use in fully disconnected sites where upstream registries are unreachable.
    • AllowContactingSource — try mirrors first, then fall back to the upstream registry. Use only on restricted networks where the upstream registry is reachable but slow or rate-limited.

    In a fully air-gapped environment, use NeverContactSource so nodes never contact public registries at pull time. Adjust mirror paths to match how you organized images during preparation. Add one imageTagMirrors entry for each upstream prefix listed in your artifact manifest.

  2. Apply the manifest: 
    oc apply -f flightctl-itms.yaml
  3. Verify the resource: 
    oc get imagetagmirrorset flightctl-airgap -o yaml
  4. Wait for the MachineConfig rollout to complete: 
    oc wait nodes --all --for=condition=Ready --timeout=30m
oc get mcp

    All MachineConfigPool objects should report UPDATED=True and DEGRADED=False before you install Red Hat Edge Manager.

  5. Confirm that CRI-O picked up the mirror rules on a node: 
    oc debug node/<node-name>

    Inside the debug shell:

    chroot /host
ls /etc/containers/registries.conf.d/

    The directory should contain a file that references your mirror registry.

Results

  • oc get imagetagmirrorset flightctl-airgap reports the resource without errors.
  • All nodes report Ready and all machine config pools are updated.
  • Pods in the target namespace pull images using only <local-registry> hostnames during Helm install (no ImagePullBackOff errors referencing a source registry from your artifact manifest).
  • Image pull still fails after ITMS is applied: Verify the MachineConfig rollout is complete (oc get mcp). Confirm the image exists in your mirror registry. Verify the ITMS source prefix matches the registry in the image reference. ITMS matches on prefix; a source of registry.example.com applies to every image under registry.example.com/*.
  • Digest mismatch (manifest unknown or digest did not match): The mirrored image digest must match the tag the chart references. Compare digests on the prep machine: 
    skopeo inspect docker://<local-registry>/<path>/<image>:<tag> | grep Digest
skopeo inspect docker://<source-registry>/<path>/<image>:<tag> | grep Digest

    Re-mirror the image if the digests differ.

    NeverContactSource failures on a partially connected cluster
    Edit the full ITMS manifest and set mirrorSourcePolicy: AllowContactingSource on the affected source while you populate the mirror. Restore NeverContactSource when mirroring is complete. Do not use a partial oc patch that replaces the entire imageTagMirrors array.