Option 2: Mirroring catalogs to a private registry with a portable compute or a storage device

If your cluster is not connected to the internet, you can install Business Automation Insights on your 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

Set the environment variables and authenticate the registries.
1. Set the environment variable $TARGET_REGISTRY by running the following command.
```
export TARGET_REGISTRY=<target-registry>
```
  The <target-registry> refers to the registry (fully qualified hostname and port) where the images are mirrored to and accessed by the OCP cluster. For example: localhost.localdomain:5000 or 172.16.0.10:5000.
2. Set the following environment variables with the installer image name and the version.
```
export CASE_NAME=ibm-ba-insights
export CASE_VERSION=25.0.0
```
3. Run the following command to set the preferred tool parameter in the YAML file to oc-mirror.
```
oc ibm-pak config mirror-tools --enabled oc-mirror
```
4. Authenticate the registries.
  You must store authentication credentials for all the IBM® Business Automation Insights source Docker registries. The following registries require authentication:
  - cp.icr.io
  - registry.redhat.io
  - registry.access.redhat.com
  If you plan to run Podman as the non-root user, see Basic Setup and Use of Podman in a Rootless environment .
  Set the environment variable XDG_RUNTIME_DIR by running the following commands:
```
export XDG_RUNTIME_DIR=/run/user/${UID}
export REGISTRY_AUTH_FILE=$XDG_RUNTIME_DIR/containers/auth.json
```
  where ${UID} is the user id of the current user. Make sure that the directory /run/user/${UID} exists and the current user must have write permission.
  Note: Run the following command as the non-root user if you do not want to use sudo podman:
  mkdir -p /run/user/<ID of non-root> && chown <non-root-user>:<non-root-group> /run/user/<ID of non-root>
  If you are using Podman, 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>
```
  If you are using docker, 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 docker login>
docker login cp.icr.io
docker 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
```
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 file://bai \
   --version $CASE_VERSION \
   --final-registry $TARGET_REGISTRY/bai2400
```
Where file://bai indicates to the plug-in that the images are first mirrored to a local file system (to the bai directory) on the machine that runs the oc mirror command. The final-registry $TARGET_REGISTRY/bai argument generates a mapping file that is used by the oc mirror commands. The final URL in your target registry includes the new bai namespace in the mirrored namespace path. The namespace path can be multi-level if your target registry supports it.
Important: The generate mirror-manifests command provides an output that lists the commands for:
- Write to disk.
- Write from disk to a target registry.
Save the commands for later use in steps 3 and 4.
The following is a sample output.
```
oc ibm-pak generate mirror-manifests ibm-ba-insights --version 25.0.0 $TARGET_REGISTRY/bai-2500
ibm-bts-bundle done
ibm-licensing done
ibm-zen  done
ibm-cs-iam done
ibm-cs-install done
ibm-elasticsearch-operator done
ibm-events-operator done
ibm-ba-insights done
ibm-cert-manager done
ibm-cs-flink done
ibm-cloud-native-postgresql done
Generating mirror manifests of CASE: ibm-ba-insights, version: 25.0.0 is complete
Next steps
- To mirror the non curated catalog:
oc mirror --config /root/.ibm-pak/data/mirror/ibm-ba-insights/25.0.0/image-set-config.yaml docker://local_registry/bai2500 --dest-skip-tls --max-per-registry=6
Note: oc mirror arguments are recommendations and may not be valid on all versions of the oc-mirror plug-in.
```
The generate mirror-manifests command generates the following files in ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION:
- catalog-sources.yaml
- image-content-source-policy.yaml
- image-set-config.yaml
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
```
If you do not know the value of the final registry where the images are to be mirrored, you can provide a placeholder value of TARGET_REGISTRY. For example:
```
oc ibm-pak generate mirror-manifests $CASE_NAME file://bai \
   --version $CASE_VERSION \
   --final-registry TARGET_REGISTRY
```
Note: TARGET_REGISTRY used without any environment variable expansion is just a plain string that must be replaced later with the actual image registry URL when it is known to you.

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

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
│   │   └── $CASE_NAME
│   │       └── $CASE_VERSION
│   │           ├── XXXXX
│   │           ├── XXXXX
│   └── mirror
│       └── $CASE_NAME
│   │       └── $CASE_VERSION
│               ├── catalog-sources.yaml
│               ├── image-content-source-policy.yaml
|               ├── image-digest-mirror-set.yaml
│               └── image-set-config.yaml
└── logs
    └── oc-ibm_pak.log
```
Run the first command generated in step 2 to write the data to disk.

You must run the commands on the host that is connected to both the local Docker registry and the OpenShift® Container Platform cluster.

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 1 to 9.
The following command can be used to see all the available options.
```
oc mirror --help
```
Based on the number and size of the images to mirror, the oc mirror command can take a considerable amount of time. If you are running the command on a remote system, 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 bai-2500-.txt file.
```
nohup oc mirror --config /root/.ibm-pak/data/mirror/ibm-ba-insights/25.0.0/image-set-config.yaml docker://$TARGET_REGISTRY/bai2401 --dest-skip-tls --max-per-registry=6 > /opt/bai-2500.txt 2>&1 &
```
The command generates the mirror_seq1_000000.tar file in /root/bai/mirror_seq1_000000.tar.

Run the second command generated in step 2 to write data from the local disk to the target registry.

The following is an example command.

oc mirror --dest-skip-tls --from=sequence_file.tar docker://$TARGET_REGISTRY/bai2500

Replace sequence_file.tar with generated output from step 3. For example, /root/bai/mirror_seq1_000000.tar.

The following is a sample output.


info: Mirroring completed in 8m1.74s (0B/s)
Rendering catalog image "target_registry/bai2500/root/ibm-bai-catalog:84a2dd" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-cert-manager-operator-catalog:41084f" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-cs-install-catalog:687382" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-events-operator-catalog:4cd92e" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-iam-operator-catalog:022616" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-licensing-catalog:7435ce" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-opencontent-flink-operator-catalog:880fdd" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/opencontent-elasticsearch-operator-catalog:755b51" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-bts-operator-catalog:866f02" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-cpd-cloud-native-postgresql-operator-catalog:0b46a3" with file-based catalog
Rendering catalog image "target_registry/bai2500/cpopen/ibm-zen-operator-catalog:690874" with file-based catalog
Writing image mapping to oc-mirror-workspace/results-1718146867/mapping.txt
Writing CatalogSource manifests to oc-mirror-workspace/results-1718146867
Writing ICSP manifests to oc-mirror-workspace/results-1718146867

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

Run the following command to create ImageContentsourcePolicy.

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

Verify that the ImageContentsourcePolicy resource is created.
```
kubectl get imageContentSourcePolicy
```
Verify your cluster node status.
```
kubectl 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.
Create a project for the CASE commands (bai is an example) by running the following commands. Before you run the command in this step, you must be logged in to your OpenShift cluster.
```
export NAMESPACE=bai
kubectl new-project $NAMESPACE
```

Optional: If you use an insecure registry, you must add the target registry to the cluster insecureRegistries list.

kubectl 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 Business Automation Insights operator. For more information, see Option 2: Installing the IBM Business Automation Insights catalog and operator instances by using ibm-pak.