Mirroring images to your private container registry

The process of mirroring images takes the image from the internet to your host, then effectively copies that image to your private container registry. After you mirror your images, you can configure your cluster and complete air-gapped installation.

Generating mirror manifests

If you want to install subsequent updates to your air-gapped environment, you must do a CASE get to get the image list when performing those updates. A registry namespace suffix can optionally be specified on the target registry to group-mirrored images.

  1. Set the preferred tool parameter in the .yaml file to oc-mirror:
oc ibm-pak config mirror-tools --enabled oc-mirror
  1. Authenticate the registries. You must store authentication credentials for all your source Docker registries.

    Your product might require one or more authenticated registries. The following registries require authentication:

    • cp.icr.io
    • registry.redhat.io
    • registry.access.redhat.com

    a. Set the environment variable XDG_RUNTIME_DIR by running the following commands:

    export XDG_RUNTIME_DIR=/run/user/${UID}
    export REGISTRY_AUTH_FILE=$XDG_RUNTIME_DIR/containers/auth.json
    

    ${UID} is the user id of the current user. Make sure that the directory /run/user/${UID} exists and the current user must have write permission.

    b. Run the following commands separately for each registry to configure credentials for all target registries that require authentication:

    • For Podman:
    export REGISTRY_AUTH_FILE=<path to the file which will store the auth credentials generated on podman login> //The `export REGISTRY_AUTH_FILE` command only needs to run once.
    podman login cp.icr.io
    podman login $TARGET_REGISTRY
    

    For more information, see Podman login example.

    • For Docker:
    export REGISTRY_AUTH_FILE=<path to the file that has the auth credentials generated on docker login>
    docker login cp.icr.io
    docker login $TARGET_REGISTRY
    

    When you log in to cp.icr.io, you must specify the user as cp and the password, which is your Entitlement key from the IBM Cloud Container Registry. You can add --tls-verify=false to the command, if you see "cert error" messages.

  2. Generate mirror manifests:

    a. Run the following commands to generate mirror manifests to be used when mirroring from a bastion host (connected mirroring):

    oc ibm-pak generate mirror-manifests \
       $CASE_NAME \
       $TARGET_REGISTRY \
       --version $CASE_VERSION
    

    A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. This directory holds the image-content-source-policy.yaml, images-mapping-to-filesystem.txt, images-mapping-from-filesystem.txt, and catalog-sources.yaml files.

    For more information, see Using ~/.ibm-pak directory structure for connected mirroring and Generating mirror manifests by using the --filter argument.

    b. Run the following commands to generate mirror manifests to be used when mirroring from a file system (disconnected mirroring):

    oc ibm-pak generate mirror-manifests \
       $CASE_NAME \
       file://local \
       --final-registry $TARGET_REGISTRY
    

    For more information, see Using ~/.ibm-pak directory structure for disconnected mirroring.

    c. You can also generate manifests to mirror images to an intermediate registry server, then to a final registry server. To do that, pass the final registry server as an argument to --final-registry:

    oc ibm-pak generate mirror-manifests \
       $CASE_NAME \
       $INTERMEDIATE_REGISTRY \
       --version $CASE_VERSION \
       --final-registry $FINAL_REGISTRY
    

    The following two mapping files are created in place of a single mapping file (image-set-config.yaml):

    • images-mapping-to-registry.txt
    • images-mapping-from-registry.txt
  3. Optional: If you are using a Red Hat® Quay.io registry and need to mirror images to a specific organization in the registry, you can target that organization by using the following command:

export ORGANIZATION=<your-organization>
oc ibm-pak generate mirror-manifests
$CASE_NAME
$TARGET_REGISTRY/$ORGANIZATION
--version $CASE_VERSION

What to do next