Option 1: Mirroring images to a private registry with a bastion server

When you mirror the images, you must run the steps on the host that is connected to both the private registry and the Red Hat OpenShift Container Platform (OCP) cluster.

Before you begin

Verify that you completed the prerequisites, prepared a host, set the environment variables, and created registry namespaces if the registry does not allow automatic creation of top-level namespaces.

Procedure

  1. Generate the required mirror manifests.
    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 the images are mirrored to and accessed by the OCP cluster. For example: 172.16.0.10:5000.

    2. Create the following environment variables with the installer image name and the version. 
      export CASE_NAME=ibm-cp-automation
export CASE_VERSION=4.1.0
      Note: Releases with interim fixes are packaged in archives with a new minor version. The version numbers follow the release.major.minor standard. For example, the first interim fix for 22.0.2 is packaged in the archive ibm-cp-automation-4.1.1.tgz.
    3. Run the following command to generate mirror manifests to be used when mirroring the image to the target registry. The $TARGET_REGISTRY refers to the registry where the images are mirrored to and accessed by the OCP cluster.
      oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY \
  --version $CASE_VERSION
      Note: After an upgrade, you can remove images from the previous version from the local registry by including an alternative namespace to copy the images to instead of the default path. For example, the following CASE command copies the images to a locationX namespace.
      oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY/locationX \
  --version $CASE_VERSION

      The command generates the files images-mapping.txt and image-content-source-policy.yaml in ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION.

      Tip: If you are using a Red Hat® Quay.io registry and need to mirror the images to a specific organization in the registry, you can set the target to that organization. Specify the organization name in the generate mirror-manifests command:
      export ORGANIZATION=<your-organization> \
oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY/$ORGANIZATION \
   --version $CASE_VERSION
    Restriction: Currently, you cannot select the images to mirror by their target architecture because image registries do not support sparse manifests (manifests that reference image digests outside of the package).

    However, you can use image groups for the mirror-images action to mirror a subset of the images. You can use the --filter option to limit what images are mirrored.

    The following table provides the image groups for each capability.

    Table 1. Groups for mirroring a subset of images
    Target capabilities Image groups, including operator-related images
    Automation Decision Services ibmcp4baProd,ibmcp4baADSImages,ibmcp4baBANImages,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard
    Automation Document Processing ibmcp4baProd,ibmcp4baADPImages,ibmcp4baFNCMImages,ibmcp4baBANImages,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard
    Automation Workstream Services ibmcp4baProd,ibmcp4baBAWImages,ibmcp4baFNCMImages,ibmcp4baBANImages,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard
    Business Automation Application ibmcp4baProd,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard
    Business Automation Workflow ibmcp4baProd,ibmcp4baBAWImages,ibmcp4baFNCMImages,ibmcp4baBANImages,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard,ibmcp4baUMSImages
    FileNet Content Manager ibmcp4baProd,ibmcp4baFNCMImages,ibmcp4baBANImages,ibmcp4baAAEImages,ibmEdbStandard
    Operational Decision Manager ibmcp4baProd,ibmcp4baODMImages,ibmcp4baBASImages,ibmcp4baAAEImages,ibmEdbStandard
    Workflow Process Service ibmcp4baProd,ibmcp4baBASImages,ibmcp4baWFPSImages,ibmEdbStandard
    Note: To install Process Federation Server with Workflow Process Service Runtime, add ibmcp4baBAWImages to the list of groups.
    Note: If Business Automation Insights (BAI) is needed for FileNet Content Manager, Operational Decision Manager, Automation Decision Services, Business Automation Workflow, or Workflow Process Service, then add ibmcp4baBAIImages and ibmEdbStandard to the list of groups.

    All the images in the groups are pulled irrespective of architecture.

    For example, to download FNCM images from CP4BA, and all the dependent product images run the following command.

    oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY \
  --version $CASE_VERSION \
  --filter ibmcp4baProd,ibmcp4baFNCMImages,ibmcp4baBANImages,ibmcp4baAAEImages,ibmEdbStandard

    The ~/.ibm-pak directory structure is built over time as you save CASEs and mirror. The following tree shows an example of the ~/.ibm-pak directory structure:

    tree ~/.ibm-pak
/root/.ibm-pak
├── config
│   └── config.yaml
├── data
│   ├── cases
│   │   └── ibm-cp-automation
│   │       └── 4.1.x
│   │           ├── XXXXX
│   │           ├── XXXXX
│   └── mirror
│       └── ibm-cp-automation
│           └── 4.1.x
│               ├── image-content-source-policy.yaml
│               └── images-mapping.txt
└── logs
    └── oc-ibm_pak.log

    A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. The mirror directory stores the image-content-source-policy.yaml and images-mapping.txt files.

    You can use the following command to list all the images in your mirror manifest and the publicly accessible registries from where the images are pulled from.

    oc ibm-pak describe $CASE_NAME \
  --version $CASE_VERSION \
  --list-mirror-images
    Tip: Make a note of the registries section at the end of output, so you can check that you can log in to the registries. You need to be able to log in to these registries to pull and mirror the images to your local target registry.
  2. Authenticate the registries.

    You must store authentication credentials for all the Cloud Pak for Business Automation source Docker registries. The following registries require authentication:

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

    Run the following command to configure credentials for all target registries that require authentication. You must run the command separately for each registry.

    export REGISTRY_AUTH_FILE=<path to the file that has the auth credentials generated on podman login>
podman login cp.icr.io
podman login <TARGET_REGISTRY>
    Important: When you log in to cp.icr.io, you must specify the user as cp and the IBM entitlement key as the password. For example:
    podman login cp.icr.io
Username: cp
Password: xxxxxxxxxxxxxxxxxxxxx
Login Succeeded!

    The password can be copied from the IBM container library. You can add --tls-verify=false to the command, if you see "cert error" messages.

    If you export REGISTRY_AUTH_FILE=~/.ibm-pak/auth.json, and then run the podman login command, you can see that the file is populated with registry credentials.

    If you use docker login, the authentication file is typically located in $HOME/.docker/config.json on Linux or %USERPROFILE%/.docker/config.json on Windows. After you run the docker login command, you can export REGISTRY_AUTH_FILE to point to that location. For example, on Linux you can run the following command:

    export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
  3. Mirror the images to the target registry.

    The following steps must be completed on the host that is connected to both the local Docker registry and the OpenShift Container Platform cluster.

    1. Mirror the images by running the following command:
      oc image mirror -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
  --filter-by-os '.*' -a $REGISTRY_AUTH_FILE \
  --insecure \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --continue-on-error=true

      The command does not produce any console logs for about 6 - 8 minutes as it prepares the list from the CASE package. If you want, you can add verbose (-v) to the command with possible values of 3, 9, 99, and so on.

      The following command can be used to see all the available options. 

      oc image mirror --help

      Based on the number and size of the images to mirror, the oc image mirror command can take a considerable amount of time. If you are running the command on a remote machine, run the command in the background with the nohup POSIX command so that it does not stop if the user logs out. The following command starts the mirroring process in the background and writes the log to a my-mirror-progress.txt file. 

      nohup oc image mirror -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
  --filter-by-os '.*' -a $REGISTRY_AUTH_FILE \
  --insecure \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --continue-on-error=true > my-mirror-progress.txt 2>&1 &

      You can view the progress of the mirror command by running the following command on the remote machine: 

      tail -f my-mirror-progress.txt
    2. Update the global image pull secret for your OpenShift cluster to have authentication credentials in place to pull images from your $TARGET_REGISTRY as specified in the image-content-source-policy.yaml file. For more information, see Updating the global cluster pull secret.
    3. Create the ImageContentsourcePolicy.
      Note: Before you run the command in this step, you must be logged in to your OpenShift cluster. You do not need to be a cluster administrator to run the mirroring commands. Using the oc login command, log in to the Red Hat OpenShift Container Platform cluster where you plan to pull the mirrored images. You can identify your specific oc login by clicking the user drop-down menu in the Red Hat OpenShift Container Platform console, then clicking Copy Login Command.

      Run the following command to create ImageContentsourcePolicy.

      oc apply -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
    4. Verify that the ImageContentsourcePolicy resource is created.
      oc get imageContentSourcePolicy
    5. Verify your cluster node status.
      oc get MachineConfigPool -w

      After the ImageContentsourcePolicy and global image pull secret are applied, the configuration of your nodes is updated sequentially. Wait until all the MachineConfigPools are updated before you move on to the next step.

    6. Create a project for the CASE commands (cp4ba is an example) by running the following commands:
      Note: Before you run the command in this step, you must be logged in to your OpenShift cluster. 
      export NAMESPACE=cp4ba
oc new-project $NAMESPACE
    7. Optional: If you use an insecure registry, you must add the target registry to the cluster insecureRegistries list.
      oc patch image.config.openshift.io/cluster \
  --type=merge -p '{"spec":{"registrySources":{"insecureRegistries":["'${TARGET_REGISTRY}'"]}}}'

What to do next

You can now go ahead and install the Cloud Pak operator. For more information, see Installing the Cloud Pak catalog and an operator instance.