Mirroring images with a bastion host

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

  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 from the bastion host:

  • 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 following 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 bastion host to the internet and to the restricted network environment (with access to the OpenShift Container Platform cluster and the local registry) at the same time. Your host must be on a Linux® x86_64 or Mac platform with any operating system that the OpenShift Container Platform CLI supports.

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 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.

• Has sufficient storage to hold all the software

• Is accessible from the OpenShift Container Platform cluster nodes

• Supports auto-repository creation

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=8.0.7

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 the process for each operator package you are mirroring.

Your host is now configured and you are ready to mirror your 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=8.0.7

• IBM Automation foundation assets

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

• IBM API Connect *

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

• IBM App Connect

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

• IBM MQ

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

• IBM Event Streams

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

• IBM Event Endpoint Management

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

• IBM Event Processing

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

• IBM Operator for Apache Flink

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

• IBM DataPower Gateway **

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

• IBM Aspera HSTS

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

• IBM Cloud Pak foundational services

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

• EDB Postgres for Kubernetes

  export OPERATOR_PACKAGE_NAME=ibm-cloud-native-postgresql && export OPERATOR_VERSION=5.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.

A mirror manifest is a YAML file that directs the ibm-pak tool what images to mirror, and where to mirror them.

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 are 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 $OPERATOR_PACKAGE_NAME --version $OPERATOR_VERSION $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.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!

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 both the internet and the restricted network environment that contains the local registry.

oc image mirror \
  -f ~/.ibm-pak/data/mirror/$OPERATOR_PACKAGE_NAME/$OPERATOR_VERSION/images-mapping.txt \
  -a $REGISTRY_AUTH_FILE \
  --filter-by-os '.*' \
  --skip-multiple-scopes \
  --max-per-registry=1

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 by using the oc CLI.

2. Update the global image pull secret for your 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 the ImageContentSourcePolicy resource:

   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.