IDMS ITMS ICSP Disconnected OpenShift

💡 Quick Answer: IDMS (ImageDigestMirrorSet) and ITMS (ImageTagMirrorSet) are the OCP 4.14+ replacements for ICSP (ImageContentSourcePolicy). They redirect container image pulls from source registries to your mirror registry by modifying /etc/containers/registries.conf on every node. IDMS handles digest-based pulls, ITMS handles tag-based pulls. oc-mirror v2 generates both automatically.

The Problem

When OpenShift components and workloads request images from quay.io, registry.redhat.io, or other public registries, a disconnected cluster can’t reach them. You need a transparent redirect mechanism that:

• Intercepts image pull requests for external registries
• Redirects them to your internal mirror registry
• Works for both digest-based pulls (release images) and tag-based pulls (Operator catalogs)
• Applies cluster-wide without modifying individual Pod specs
• Triggers node MCO rollout to update CRI-O configuration

The Solution

ICSP vs IDMS/ITMS

ImageDigestMirrorSet (IDMS)

For images pulled by digest (SHA256) — most release and Operator images:

apiVersion: config.openshift.io/v1
kind: ImageDigestMirrorSet
metadata:
  name: ocp-release-mirror
spec:
  imageDigestMirrors:
  # OpenShift release images
  - mirrors:
    - registry.example.com:8443/openshift-release-dev
    source: quay.io/openshift-release-dev
    mirrorSourcePolicy: NeverContactSource
  
  # Red Hat Operator images
  - mirrors:
    - registry.example.com:8443/redhat
    source: registry.redhat.io/redhat
    mirrorSourcePolicy: NeverContactSource
  
  # Certified Operator images
  - mirrors:
    - registry.example.com:8443/certified
    source: registry.connect.redhat.com
    mirrorSourcePolicy: NeverContactSource

ImageTagMirrorSet (ITMS)

For images pulled by tag — catalog index images, additional images:

apiVersion: config.openshift.io/v1
kind: ImageTagMirrorSet
metadata:
  name: ocp-tag-mirror
spec:
  imageTagMirrors:
  - mirrors:
    - registry.example.com:8443/redhat/redhat-operator-index
    source: registry.redhat.io/redhat/redhat-operator-index
    mirrorSourcePolicy: NeverContactSource

Mirror Source Policy Options

Use NeverContactSource for air-gapped environments — prevents any external pull attempts.

Legacy: ImageContentSourcePolicy (ICSP)

For OCP ≤4.13 or when using oc-mirror v1:

apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
  name: mirror-ocp
spec:
  repositoryDigestMirrors:
  - mirrors:
    - registry.example.com:8443/ocp/release
    source: quay.io/openshift-release-dev/ocp-release
  - mirrors:
    - registry.example.com:8443/ocp/release
    source: quay.io/openshift-release-dev/ocp-v4.0-art-dev

Applying and Verifying

# Apply IDMS (generated by oc-mirror v2)
oc apply -f working-dir/cluster-resources/idms-oc-mirror.yaml

# Apply ITMS
oc apply -f working-dir/cluster-resources/itms-oc-mirror.yaml

# Watch MachineConfigPool rollout (nodes restart)
oc get mcp -w
# NAME     CONFIG   UPDATED   UPDATING   DEGRADED   MACHINECOUNT
# master   ...      False     True       False      3
# worker   ...      False     True       False      6

# Wait for all nodes to be UPDATED=True

# Verify on a node
oc debug node/<node-name> -- chroot /host cat /etc/containers/registries.conf

Expected registries.conf:

unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]

[[registry]]
  prefix = ""
  location = "quay.io/openshift-release-dev"
  mirror-by-digest-only = true
  
  [[registry.mirror]]
    location = "registry.example.com:8443/openshift-release-dev"

[[registry]]
  prefix = ""
  location = "registry.redhat.io/redhat"
  mirror-by-digest-only = true
  
  [[registry.mirror]]
    location = "registry.example.com:8443/redhat"

Migrating ICSP to IDMS

# List existing ICSPs
oc get imagecontentsourcepolicy

# OCP 4.14+ automatically converts ICSPs to IDMS on upgrade
# But you can manually migrate:

# 1. Export ICSP
oc get icsp mirror-ocp -o yaml > icsp-export.yaml

# 2. Convert to IDMS
sed -i 's|operator.openshift.io/v1alpha1|config.openshift.io/v1|' icsp-export.yaml
sed -i 's|ImageContentSourcePolicy|ImageDigestMirrorSet|' icsp-export.yaml
sed -i 's|repositoryDigestMirrors|imageDigestMirrors|' icsp-export.yaml

# 3. Apply IDMS and delete ICSP
oc apply -f icsp-export.yaml
oc delete icsp mirror-ocp

Reconnecting a Cluster

To restore internet connectivity and stop using the mirror:

# Delete all mirror redirects
oc delete imagedigestmirrorset --all
oc delete imagetagmirrorset --all
oc delete imagecontentsourcepolicy --all  # if any remain

# Wait for MCP rollout
oc get mcp -w

# Verify registries.conf is clean
oc debug node/<node-name> -- chroot /host cat /etc/containers/registries.conf
# Should only show: unqualified-search-registries = [...]

Common Issues

Nodes stuck in UPDATING after IDMS apply

IDMS/ITMS changes trigger MachineConfig updates. Each node must reboot. If a node is stuck, check oc describe mcp worker and oc get nodes for NotReady nodes. PDB-blocked drains are the usual cause.

Image pull still fails after IDMS

Check that the exact source path matches. quay.io/openshift-release-dev is different from quay.io/openshift-release-dev/ocp-release. Verify with skopeo inspect against your mirror.

CRI-O log shows “Trying to access” original registry

This is informational — check if the next log line shows the mirror. CRI-O logs the original source name first, then tries mirrors in order.

Best Practices

• Use IDMS/ITMS on OCP 4.14+ — ICSP is deprecated
• Set NeverContactSource for true air-gap — prevents any external pull attempts
• Let oc-mirror generate IDMS/ITMS — manual creation is error-prone
• Plan for MCP rollout time — IDMS/ITMS changes reboot every node
• Don’t mix ICSP and IDMS — migrate all ICSPs to IDMS after OCP 4.14 upgrade

Key Takeaways

• IDMS redirects digest-based pulls, ITMS redirects tag-based pulls to your mirror
• Both modify /etc/containers/registries.conf cluster-wide via MachineConfig
• oc-mirror v2 generates IDMS/ITMS covering the full image set (not incremental like v1 ICSP)
• NeverContactSource is required for true air-gap security
• ICSP is deprecated — migrate to IDMS/ITMS on OCP 4.14+
• Applying IDMS/ITMS triggers node reboots — plan a maintenance window