Examples of installing IBM Process Mining by mirroring Cloud Pak images to a private container registry

Starting from v1.4.0, the plug-in creates a component-set-config.yaml file in the ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION directory to download the CASEs with oc ibm-pak get. This file captures all the CASEs that were downloaded, pinning down their exact versions during this particular download. You can use this file to download the same CASEs with same versions in another environment. You can check this file to your source code repository and re-create the same environment each time you use this to download the CASEs.

Run the following command:

oc ibm-pak get ibm-process-mining --insecure --skip-verify --version $CASE_VERSION

You can also edit this file by defining the CASEs with pinned down versions that should include your product. The following are the contents of an example file, my-csc.yaml:

name: "example-product"                         # <required> defines the name for the "product"; this is NOT a CASE name, but follows IBM CASE name rules. For more information, see https://ibm.biz/case-yaml
version: "1.0.0"                                # <required> defines a version for the "product"
description: "an example product targeting OCP 4.9" # <optional, but recommended> defines a human readable description for this listing of components
cases:                                          # list of CASEs. First item in the list is assumed to be the "top-level" CASE, and all others are dependencies
- name: ibm-mas
 version: 5.5.2
 launch: true                                  # Exactly one CASE should have this field set to true. The launch scripts of that CASE are used as an entry point while executing 'ibm-pak launch' with a ComponentSetConfig
- name: ibm-cp-common-services
 version: 1.15.2

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 for connected mirroring:

tree ~/.ibm-pak
/root/.ibm-pak
├── config
│   └── config.yaml
├── data
│   ├── cases
│   │   └── YOUR-CASE-NAME
│   │       └── YOUR-CASE-VERSION
│   │           ├── XXXXX
│   │           ├── XXXXX
│   └── mirror
│       └── YOUR-CASE-NAME
│           └── YOUR-CASE-VERSION
│               ├── catalog-sources-linux-amd64.yaml
│               ├── catalog-sources.yaml
│               └── image-content-source-policy.yaml
|               └── image-digest-mirror-set.yaml
|               └── image-set-config.yaml
|
└── logs
   └── oc-ibm_pak.log

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, image-set-config.yaml, and catalog-sources.yaml files.

The following tree shows an example of the ~/.ibm-pak directory structure for disconnected mirroring:

tree ~/.ibm-pak
/root/.ibm-pak
├── config
│   └── config.yaml
├── data
│   ├── cases
│   │   └── ibm-cp-common-services
│   │       └── 1.9.0
│   │           ├── XXXX
│   │           ├── XXXX
│   └── mirror
│       └── ibm-cp-common-services
│           └── 1.9.0
│               ├── catalog-sources.yaml
│               ├── image-content-source-policy.yaml
│               ├── images-mapping-to-filesystem.txt
│               └── images-mapping-from-filesystem.txt
└── logs
   └── oc-ibm_pak.log

Some products support the ability to generate mirror manifests only for a subset of images by using the --filter argument and image grouping. The --filter argument provides the ability to customize which images are mirrored during an air-gapped installation. As an example for this function, ibm-cloud-native-postgresql CASE can be used, which contains groups that allow mirroring-specific variants of ibm-cloud-native-postgresql (Standard or Enterprise). Use the --filter argument to target a variant of ibm-cloud-native-postgresql to mirror rather than the entire library. The filtering can be applied for groups and architectures. Consider the following command:

oc ibm-pak generate mirror-manifests \
   ibm-cloud-native-postgresql \
   file://local \
   --final-registry $TARGET_REGISTRY \
   --filter $GROUPS

The command was updated with a --filter argument. For example, for $GROUPS equal to ibmEdbStandard the mirror manifests will be generated only for the images associated with ibm-cloud-native-postgresql in its Standard variant. The resulting image group consists of images in the ibm-cloud-native-postgresql image group in addition to any images that are not associated with any groups. This allows products to include common images and the ability to reduce the number of images that you need to mirror.

You can use the following command to list all the images that will be mirrored and the publicly accessible registries from where those images will be pulled from:

oc ibm-pak describe $CASE_NAME --version $CASE_VERSION --list-mirror-images

The output of the preceding command will have two sections:

1. Mirroring Details from Source to Target Registry
2. Mirroring Details from Target to Final Registry.

Note down the Registries found sub sections in the preceding command output. You need to authenticate against those registries so that the images can be pulled and mirrored to your local registry. The Top level namespaces found section shows the list of namespaces under which the images will be mirrored. These namespaces should be created manually in your registry (which appears in the Destination column in the command output) root path if your registry does not allow automatic creation of namespaces.

For example:

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

For example, if you export REGISTRY_AUTH_FILE=~/.ibm-pak/auth.json, then after performing podman login, you can see that the file is populated with registry credentials.

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

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