If you're working in a secure environment where internet access is not allowed, installing IBM Cloud Pak for Business Automation (CP4BA) requires a special approach called an offline or air-gapped installation. In this setup, your OpenShift cluster can't download anything directly from the internet—so everything it needs must be prepared and copied ahead of time.
IBM makes this possible by letting you download all required files, container images, and metadata from a machine that has internet access. You then transfer them to a private registry inside your restricted environment. This way, your cluster can access everything it needs locally.
In this blog, we’ll walk through the full process in a simple and clear way—step by step—using tools like oc mirror and oc ibm-pak. Whether you’re new to CP4BA or just setting it up in an offline setup for the first time, this guide will help you get started with confidence.
What is offline installation?
An offline installation, also known as an air-gapped deployment, refers to installing software in an environment that does not have direct access to the internet. This setup is common in organizations that prioritize security, compliance, and control over their infrastructure.
In the context of IBM Cloud Pak for Business Automation (CP4BA), an offline installation means setting up the entire Cloud Pak—including its dependencies, container images, and operators—within a completely isolated OpenShift cluster, using pre-downloaded resources.
Benefits of Offline Installation
- Enhanced Security: Prevents direct exposure to the internet, reducing attack surfaces.
- Compliance and Governance: Meets strict regulatory requirements (e.g., financial, defence, healthcare sectors).
- Controlled Environment: Ensures stability by tightly managing all software versions and updates.
- Auditability: Easier tracking of what goes into production, since everything is vetted beforehand.
Prerequisites
Before diving into the installation steps, it's critical to prepare your environment thoroughly.
- Bastion host: A Linux-based system with internet access to prepare the mirror - RHEL 8.10 or later
- Cluster type : Red Hat OCP 4.15 or later
- Airgap registry: Internal container registry - eg. Artifactory,quay
- Valid IBM Entitlement Registry Key (for pulling images from IBM) - credentials for logging into cp.icr.io
Setting up the private registry
You need to set up a private image registry to store all the container images locally. Make sure the registry is set up correctly and can be reached by all the nodes in your OpenShift cluster. This is important so that the installation can run smoothly without needing internet access.
- Create a folder or path in your target registry where the images will be stored. For example: registry/2500
In my case, I'm using JFrog Artifactory, and the image path looks like docker-na-public.artifactory.swg-devops.com/hyc-cp4ba-team-kragon-airgap-docker-local/2500
- When you generate the mirror manifests and run the image mirroring process, make sure to use this exact path.
- Also, check that the generated ImageContentSourcePolicy (usually in image-content-source-policy.yaml) includes the correct registry path.
- Finally, mirror all the required images for the new version or interim fix. They will be stored under registry/2500 in your private registry.
Setting up the Bastion host
Login to the RHEL machine and complete the following steps:
-
oc mirror
-
Download the oc-mirror based on the OpenShift cluster version from here .
-
Extract the binary file by entering the following command.
tar -xf oc-mirror.tar.gz
-
Run the following commands to move the file to the /usr/local/bin directory.
mv oc-mirror /usr/local/bin/oc-mirror chmod 755 /usr/local/bin/oc-mirror
-
You can confirm that oc mirror is installed by running the following command.
Downloading the CASE files
Here I’m trying out the offline installation of CP4BA 25.0.0
- Login to the bastion host
- Create a workspace
mkdir /root/cp4ba2500
- Run the following command to set the environment variable $IBMPAK_HOME.
export IBMPAK_HOME=/root/cp4ba2500
- Set the following environment variables with the installer image name and the CASE version, which corresponds to the channel version in OpenShift.
export CASE_NAME=ibm-cp-automation
export CASE_VERSION=25.0.0
- Before running the oc ibm-pak get command to download a CASE file, you need to configure where it should download from. Use the following command to set up the IBM Cloud Pak CASE repository.
oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen –enable
- To use oc-mirror for copying container images, run the command below. It tells oc ibm-pak to use oc-mirror as the preferred tool:
oc ibm-pak config mirror-tools --enabled oc-mirror
Activates oc-mirror functionality within ibm-pak, required to mirror container images to an offline registry.
- Download the cert-kubernetes repo in the created folder
git clone --branch 25.0.0 https://github.com/icp4a/cert-kubernetes.git
cp4ba-case-to-be-mirrored-25.0.0.txt file in the cert-kubernetes/scripts/airgap folder is used for downloading the case
- Download the CASE using the following command
oc ibm-pak get -c file:///root/cp4ba2500/cert-kubernetes/scripts/airgap/cp4ba-case-to-be-mirrored-25.0.0.txt
Mirroring the Cloud Pak catalogs to a private registry
- Set the environment variable $TARGET_REGISTRY
- Now we can create manifests needed for mirroring images and catalogs.
oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY --version $CASE_VERSION 
- If you are using Podman, run the following command to configure credentials for all target registries that require authentication.
export REGISTRY_AUTH_FILE=~/.ibm-pak/auth.json
podman login cp.icr.io
podman login $TARGET_REGISTRY
- Execute the mirror command displayed in the next steps of generate mirror manifests.
oc mirror --config /root/cp4ba2500/.ibm-pak/data/mirror/ibm-cp-automation/25.0.0/image-set-config.yaml docker://docker-na-public.artifactory.swg-devops.com/hyc-cp4ba-team-kragon-airgap-docker-local/2500 --dest-skip-tls --max-per-registry=6
We can also use 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 cp4ba-2500.txt file.
nohup oc mirror \
--config /root/cp4ba2500/.ibm-pak/data/mirror/ibm-cp-automation/25.0.0/image-set-config.yaml \
docker://docker-na-public.artifactory.swg-devops.com/hyc-cp4ba-team-kragon-airgap-docker-local/2500 \
--dest-skip-tls \
--max-per-registry=6 > /root/cp4ba2500/cp4ba-25.0.0.txt 2>&1 &
once mirroring is completed you will find something like this
- The new ImageContentSourcePolicy will be created with the target registry credentials
Installing the operators
- Login to the target OCP cluster and create the project
oc login -u <username> https://<api-server-url>:<port> -p <password> --insecure-skip-tls-verify
export NAMESPACE=cp2500
oc new-project $NAMESPACE
oc project $NAMESPACE
- Update the global image pull secret (pull secret in the “openshift-config” namespace) with the authentication credentials in place to pull images from your $TARGET_REGISTRY as specified in the image-content-source-policy.yaml file
- Run the following command to create ImageContentSourcePolicy.
oc apply -f $IBMPAK_HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
- Go to the cert-kubernetes/scripts/ folder and execute the cp4a-clusteradmin-setup.sh to install the operators by choosing option 2) Offline/Airgap
Once the operators are installed, follow the instructions here https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=deployment-preparing-your-chosen-capabilities to download different CP4BA capabilities.
Conclusion
This blog covered:
- Setting up the air-gapped mirroring environment
- Downloading CASE files
- Mirroring the required images
- Preparing OpenShift for offline CP4BA installation
Reference:
https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=icmppd-option-2-preparing-your-cluster-air-gapped-offline-deployment