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.

  Ensure that you have sufficient registry space for all the operator packages that you intend to export. For more information, see "Sizing for operator packages" in Mirroring images for an air-gapped OpenShift cluster.

• The following sites and ports must be accessible:

  • icr.io:443 for open images

  • cp.icr.io:443 for entitled registry images

  • dd0.icr.io CDN for image content delivery

  • dd2.icr.io CDN for image content delivery

  • github.com for operator packages and tools

  • redhat.com for Red Hat OpenShift Container Platform upgrades

• Storage is available and configured on your OpenShift cluster.

• If you need to mirror the OpenShift operators, complete the Prerequisites for mirroring images for a disconnected installation using the oc-mirror plugin as described in the Red Hat OpenShift documentation.

  For more information about why you might need these operators, see 3.8. Mirror Red Hat operators.

Tip

With ibm-pak plug-in version 1.2.0, you can eliminate the port for github.com to retrieve operator packages by configuring the plug-in to download CASEs as OCI artifacts from IBM Cloud Container Registry (ICCR). Run this command:

oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable

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:

Use a local Docker registry to store your images in your network-restricted environment. If you already have one or more centralized, corporate registry servers that store production container images, you can use those for this purpose. If a registry is not already available, install and configure a production-grade registry.

User access: To access your registries during the mirroring process, you need user credentials that can write to the target local registry and create repositories. To access your registries during runtime, you need user credentials that can read all repositories from the target local registry (these credentials are used by the OpenShift Container Platform cluster).

The local registry must meet the following requirements:

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

• Open Container Initiative (OCI) compliant.

• Is accessible from the OpenShift Container Platform cluster nodes.

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.

These prerequisites apply only if you are applying fix packs prior to an upgrade:

• Confirm that your operators are running properly.

• If there are any pending operator updates that require manual approval, approve those before starting this procedure. Manual approval should not be configured for operator installs, because users cannot control what upgrades to apply; this strategy forces all possible upgrades to be done at the same time and can block upgrades.

1. For each component of Cloud Pak for Integration that you intend to use, create environment variables with the installer image name and the image inventory on your host. Copy and run the applicable command in Export commands for operators.

   For example:

   export OPERATOR_PACKAGE_NAME=ibm-integration-platform-navigator && export OPERATOR_VERSION=7.3.22

   You need to separately mirror each component of Cloud Pak for Integration that you intend to use. Operator package files can be found in the IBM cloud-pak repository.

2. Connect your host to the internet. It does not need to be connected to the network restricted environment at this time.

3. Download the operator package to your host. If you do not specify the operator version, it downloads the latest version.

   oc ibm-pak get $OPERATOR_PACKAGE_NAME --version $OPERATOR_VERSION --skip-dependencies --install-method OLM

   Repeat this step for each operator package you are mirroring.

Your host is now configured and you can mirror the images.

Copy and run the applicable commands to set the environment variables for each operator that you need. For entries with an asterisk ("*"), make sure to review the "Notes" section at the end of the list.

• IBM Cloud Pak for Integration

  export OPERATOR_PACKAGE_NAME=ibm-integration-platform-navigator && export OPERATOR_VERSION=7.3.22

• IBM Automation foundation assets

  export OPERATOR_PACKAGE_NAME=ibm-integration-asset-repository && export OPERATOR_VERSION=1.7.18

• IBM API Connect *

  export OPERATOR_PACKAGE_NAME=ibm-apiconnect && export OPERATOR_VERSION=5.9.0

• IBM App Connect

  export OPERATOR_PACKAGE_NAME=ibm-appconnect && export OPERATOR_VERSION=12.0.21

• IBM MQ

  export OPERATOR_PACKAGE_NAME=ibm-mq && export OPERATOR_VERSION=3.2.22

• IBM Event Streams

  export OPERATOR_PACKAGE_NAME=ibm-eventstreams && export OPERATOR_VERSION=12.2.2

• IBM Event Endpoint Management

  export OPERATOR_PACKAGE_NAME=ibm-eventendpointmanagement && export OPERATOR_VERSION=11.7.2

• IBM Event Processing

  export OPERATOR_PACKAGE_NAME=ibm-eventprocessing && export OPERATOR_VERSION=1.5.0

• IBM Operator for Apache Flink

  export OPERATOR_PACKAGE_NAME=ibm-eventautomation-flink && export OPERATOR_VERSION=1.5.0

• IBM DataPower Gateway **

  export OPERATOR_PACKAGE_NAME=ibm-datapower-operator && export OPERATOR_VERSION=1.11.9

• IBM Aspera HSTS

  export OPERATOR_PACKAGE_NAME=ibm-aspera-hsts-operator && export OPERATOR_VERSION=1.5.19

• IBM Cloud Pak foundational services

  export OPERATOR_PACKAGE_NAME=ibm-cp-common-services && export OPERATOR_VERSION=4.6.20

• EDB Postgres for Kubernetes

  export OPERATOR_PACKAGE_NAME=ibm-cloud-native-postgresql && export OPERATOR_VERSION=6.2.0

Notes

• * If you are planning to deploy the API Manager instance type, you need to mirror the EDB Postgres for Kubernetes operator package as well as the IBM API Connect operator.

• ** The IBM DataPower Gateway operator package contains multiple image groups. To mirror images for Cloud Pak for Integration, use the ibmdpCp4i image group.

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 OpenShift Container Platform 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 $OPERATOR_PACKAGE_NAME file://integration --version $OPERATOR_VERSION --final-registry $TARGET_REGISTRY --install-method OLM

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

   • If your registry (for example, GitLab) restricts the number of path separators in the image name, you need to add a parameter and argument to this command. For more information, see Troubleshooting issues when mirroring images for an air-gapped OpenShift cluster.

   The command generates the following files at ~/.ibm-pak/data/mirror/$OPERATOR_PACKAGE_NAME/$OPERATOR_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 operator package 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.

   The username is cp and the password is the IBM entitlement key. To get your entitlement key, go to the Container software library and click Copy for any key in the list.

   For example:

   podman login cp.icr.io
   Username: cp
   Password: <ibm_entitlement_key>
   
   Login Succeeded!

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/$OPERATOR_PACKAGE_NAME/$OPERATOR_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 operator package you are mirroring. Use the same image path for each operator package 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 OPERATOR_PACKAGE_NAME, OPERATOR_VERSION, REGISTRY_AUTH_FILE, and IMAGE_PATH.

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

Login to the local registry with podman or docker. Use an account that can write images to the local registry.

podman login $TARGET_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/$OPERATOR_PACKAGE_NAME/$OPERATOR_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 operator package 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 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/$OPERATOR_PACKAGE_NAME/$OPERATOR_VERSION/image-content-source-policy.yaml

   Verify that the ImageContentSourcePolicy resource is created:

   oc get imageContentSourcePolicy

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

   oc get MachineConfigPool -w

Mirror the following Red Hat OpenShift operators, which are part of the redhat-operators catalog source, as applicable:

• RedHat Build of Keycloak, if you want to use Cloud Pak foundational services identity and access management. The catalog source must contain one of these operator channels: stable-v22, stable-v24, or stable-v26.

• cert-manager Operator for Red Hat OpenShift, if you are planning to deploy API Connect cluster, Event Manager, or Event Processing instances.

To mirror these operator images and apply the catalog source, first review Prerequisites for mirroring images for a disconnected installation using the oc-mirror plugin, then follow the essential steps as described in the Red Hat OpenShift documentation:

1. Configuring credentials that allow images to be mirrored

2. Creating the image set configuration

3. Mirroring an image set in a fully disconnected environment

4. Mirroring images for a disconnected installation using the oc-mirror plugin

For more information, see Mirroring images for a disconnected installation using the oc-mirror plugin.