Mirroring images with a portable compute or storage device (file system)

• A Docker V2 registry that is available and accessible from the OpenShift Container Platform cluster nodes.

• The following sites and ports must be accessible:

  • icr.io:443 for entitled registry

  • quay.io:443 for Cloud Pak for Integration

  • github.com for CASEs and tools

  • redhat.com for Red Hat OpenShift Container Platform upgrades

• Storage is available and configured on your cluster.

You must be able to connect your file system to the internet and to the restricted network environment (with access to the OpenShift Container Platform cluster and the local registry). Your host must be on a Linux® x86_64 or Mac platform with any operating system that the OpenShift Container Platform CLI supports.

Your file system must have sufficient storage to hold all the software that is to be transferred to the local registry.

The following table provides the software requirements for installing Cloud Pak for Integration in an air-gapped environment:

Software requirements and purpose

Complete the following steps on your host:

1. Install Docker or Podman.

   • To install Docker (for example, on Red Hat® Enterprise Linux®), run the following commands:

   yum check-update
   yum install docker

   • To install Podman, see Podman installation instructions.

2. Install the oc OpenShift Container Platform CLI tool.

   Follow the procedure for Getting started with the OpenShift CLI.

3. Download the IBM Catalog Management plug-in version 1.1.0 or later from GitHub. This plug-in allows you to run oc ibm-pak commands against the cluster.

   To confirm that ibm-pak is installed, run the following command:

   oc ibm-pak --help

   This should return the oc ibm-pak usage.

You must use a local Docker registry to store your images in your network-restricted environment. You may have one or more centralized, corporate registry servers to store production container images. If a local registry is not already available, a production-grade registry will need to be installed and configured.

To access your registries during an air-gapped installation, use an account that can write to the target local registry. To access your registries during runtime, use an account that can read from the target local registry. The registry must meet the following requirements:

• Supports multi-architecture images through Docker Manifest V2, Schema 2. For details, see Docker Manifest V2, Schema 2.

• Is accessible from the OpenShift Container Platform cluster nodes.

• Allows path separators in the image name.

After you create the local registry, you must configure the registry, verify that the registry meets the following requirements:

• Supports auto-repository creation.

• Has credentials of a user who can write and create repositories. The mirroring process uses these credentials.

• Has credentials of a user who can read all repositories. The OpenShift Container Platform cluster uses these credentials.

• Has sufficient storage to hold all the software that is to be transferred to the local registry.

1. Define the environment variable $TARGET_REGISTRY by running the following command:

   export TARGET_REGISTRY=<target-registry>

   The <target-registry> refers to the registry (hostname and port) where your images will be mirrored to and accessed by the oc cluster. For example: 172.16.0.10:5000.

   If you want the images to use a specific namespace in the target registry, you can specify it here, for example: registry.private/cp4i.

2. Generate mirror manifests by running the following command:

   oc ibm-pak generate mirror-manifests $CASE_NAME file://integration --version $CASE_VERSION --final-registry $TARGET_REGISTRY

   If you need to filter for a specific image group, add the parameter --filter <image_group> to this command.

This generates the following files at ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION:

• catalog-sources.yaml

• catalog-sources-linux-<arch>.yaml (if there are arch specific catalog sources)

• image-content-source-policy.yaml

• images-mapping-to-filesystem.txt

• images-mapping-from-filesystem.txt

Repeat the process for each CASE you are mirroring.

You must authenticate to the entitled registry to mirror the required images.

1. Export the path to the file which stores the auth credentials that are generated from podman login or docker login. The authentication file is typically located at $HOME/.docker/config.json on Linux or %USERPROFILE%/.docker/config.json on Windows:

   export REGISTRY_AUTH_FILE=$HOME/.docker/config.json

2. Login to the cp.icr.io registry with podman or docker:

   podman login cp.icr.io

   See Finding and applying your entitlement key (online installation) for how to obtain your entitlement key.

Complete these steps to mirror the images from the internet to your file system:

1. Define the environment variable $IMAGE_PATH by running the following command:

   export IMAGE_PATH=<image-path>

   The <image-path> refers to the local path to store the images. For example, integration uses the integration directory in the current working directory.

2. Mirror images to the file system:

   oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
     --filter-by-os '.*' \
     -a $REGISTRY_AUTH_FILE \
     --skip-multiple-scopes \
     --max-per-registry=1 \
     --dir "$IMAGE_PATH"

The oc image mirror command starts by planning what images and layers need to be transferred. It can take a couple of minutes before you start seeing output.

Repeat the process for each CASE you are mirroring. Use the same image path for each CASE so that common images are only stored once.

If you are using a portable device, you can disconnect the device from the internet and connect it to the restricted network environment. The same environment variables can be used.

If you are using portable storage, transfer the files to a device in the restricted network environment. The files that need to be transferred are:

• The ~/.ibm-pak directory.

• The image path you specified in the previous step.

If you are using a different device in the restricted network environment, you need to set the same environment variables as the original device. These include CASE_NAME, CASE_VERSION, REGISTRY_AUTH_FILE and IMAGE_PATH.

You must authenticate to the local registry to mirror the required images.

1. Login to the local registry with podman or docker:

   podman login $TARGET_REGISTRY

   Use an account that can write images to the local registry.

Run the following command to copy the images to the local registry. Your device must be connected to the restricted network environment that contains the local registry.

oc image mirror \
  -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt \
  -a $REGISTRY_AUTH_FILE \
  --filter-by-os '.*' \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --from-dir "$IMAGE_PATH"

The oc image mirror command starts by planning what images and layers need to be transferred. It can take a couple of minutes before you start seeing output.

If the local registry is not secured by TLS, or the certificate presented by the local registry is not trusted by your device, add the --insecure option to the command.

Repeat the process for each CASE you are mirroring.

1. Log in to your Red Hat OpenShift Container Platform using the oc CLI.

2. Update the global image pull secret for your Red Hat OpenShift cluster.

   Follow the procedure in Updating the global cluster pull secret. These steps enable your cluster to have proper authentication credentials in place so that it can pull images from your TARGET_REGISTRY (as specified in the image-content-source-policy.yaml).

3. Create ImageContentSourcePolicy:

   oc apply -f  ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml

   Verify that the ImageContentSourcePolicy resource is created:

   oc get imageContentSourcePolicy

   Verify your cluster node status and wait for all nodes to be updated before proceeding:

   oc get MachineConfigPool -w