Registry mapping

Edit online

Registry mapping enables workloads to reference placeholder public registries on the host while pulling workload images from private registries inside the confidential guest environment.

IBM Confidential Computing Containers for Red Hat OpenShift Container Platform (CCCO) supports registry mapping so that you can decouple the image reference that is visible on the host from the image source that is pulled inside the guest. This feature helps you use private registries without exposing private registry credentials to the host.

Registry mapping is useful when the host runtime must reference an image from a public or placeholder registry, but the actual image pull must occur from a private registry inside the confidential guest environment.

Configuring registry mapping

To configure registry mapping, add the registryMapping field to the config section of the confidential-containers workload in the contract.

type: workload
confidential-containers:
  config:
    registryMapping:
      <host_image>: <guest_image>

The registryMapping field supports the following mapping types:

  • Registry-level (prefix) mapping: Maps all images from one registry or namespace to another registry or namespace. For example, "docker.io": "icr.io" transforms docker.io/namespace/image:tag to icr.io/namespace/image:tag.
  • Full image path mapping: Maps a specific image to a different image, including tags and digests. For example, "quay.io/prometheus/busybox": "icr.io/hpcr/nginx-linuxone:latest" transforms quay.io/prometheus/busybox to icr.io/hpcr/nginx-linuxone:latest.

Mapping precedence and tag handling

When multiple mappings are possible, exact image matches take priority over prefix-based matches. If multiple prefix-based mappings match, the longest matching prefix is used.

Registry mapping preserves image tags and digests unless the mapping value explicitly provides its own tag or digest.

  • If the mapping key matches an image path without a tag or digest, and the mapping value also omits a tag or digest, the source tag or digest is preserved.
  • If the mapping value includes a tag or digest, that value takes precedence over the source tag or digest.

Example mappings

  • Prefix-based mapping
    type: workload
auths:
  icr.io:
    username: iamapikey
    password: ${encrypted_password}
confidential-containers:
  regoValidator:
    policy: ${encoded_policy}
  config:
    registryMapping:
      docker.io/public: icr.io/private
      quay.io: private-registry.company.com

    This configuration applies the following transformations:

    • docker.io/public/nginx:latest becomes icr.io/private/nginx:latest.
    • quay.io/prometheus/busybox:v1.0 becomes private-registry.company.com/prometheus/busybox:v1.0.
  • Exact image mapping
    type: workload
auths:
  icr.io:
    username: iamapikey
    password: ${encrypted_password}
confidential-containers:
  regoValidator:
    policy: ${encoded_policy}
  config:
    registryMapping:
      quay.io/prometheus/busybox: icr.io/hpcr/nginx-linuxone:latest
      quay.io/prometheus/busybox1@sha256:5d1e942a2a5dc4d146d29ea1074b6355f8f7a466e1dd37cbfdd57a6f88039f88: icr.io/hpcr/nginx-linuxone:latest@sha256:5d1e942a2a5dc4d146d29ea1074b6355f8f7a466e1dd37cbfdd57a6f88039f88

    This configuration applies the following transformations:

    • quay.io/prometheus/busybox becomes icr.io/hpcr/nginx-linuxone:latest.
    • quay.io/prometheus/busybox1@sha256:5d1e942a2a5dc4d146d29ea1074b6355f8f7a466e1dd37cbfdd57a6f88039f88 becomes icr.io/hpcr/nginx-linuxone:latest@sha256:5d1e942a2a5dc4d146d29ea1074b6355f8f7a466e1dd37cbfdd57a6f88039f88.
Note: If you do not specify registryMapping, no image transformation occurs. If no mapping matches an image reference, the original image reference is used.
Note: If the registry mapping file is missing, the instance starts successfully and behaves as though no mappings are configured. If the registry mapping file is malformed, the system logs a warning and container creation fails.
Note: Registry mapping changes only the image source. It does not change the container name. Registry mapping requires guest-side network access to the target registry. For information about defining registry credentials in the contract, see The workload - auths subsection.