Setting up the cluster and use a local image registry

You can store everything that you need to install Cloud Pak for Business Automation in a local registry and use this server for your deployment.

Before you begin

The following prerequisites are needed before you start your installation.

  • An OpenShift Container Platform (OCP) cluster must be installed. For more information, see Option 1: Preparing your cluster for an online deployment.
  • An image registry is used to store all images in your local registry, and must be available and accessible from the OCP cluster nodes.

    Make sure that the registry meets the following requirements:

    • Supports Docker Manifest V2, Schema 2.
    • Supports multi-architecture images.
      Note: You must mirror all architecture images because image registries do not support sparse manifests (manifests that reference image digests outside of the package).
      Restriction: Do not use the OpenShift image registry as your local registry. The OpenShift registry does not support multi-architecture images.
    • Is accessible from both the host and your OpenShift Container Platform cluster nodes.
    • Has the username and password of a user who can write to the target registry from the host.
    • Has the username and password of a user who can read from the target registry that is on the OpenShift cluster nodes.
    • Allows path separators in the image name.

    Create the following namespaces to store the Cloud Pak images.

    • The cp namespace is for the images in the IBM Entitled Registry (cp.icr.io/cp) that need an entitlement key and credentials to pull. The namespace must have a user who can write and create repositories, and read all repositories.
    • The cpopen namespace is for all images from the icr.io/cpopen repository. The cpopen namespace is for publicly available images that are hosted by IBM that do not require credentials to pull.

    Verify that each namespace meets the following requirements:

    • Supports auto-repository creation.
    • Has credentials of a user who can write and create repositories. The host uses these credentials.
    • Has credentials of a user who can read all repositories. The OpenShift Container Platform cluster uses these credentials.
  • The host of the image registry must be able to access the OCP cluster, an internal image registry, and the internet. The host must be on a Linux® x86_64 platform with any operating system that the IBM Cloud Pak® CLI and the OCP CLI support.
    1. Install the oc OCP CLI tool. For more information, see OCP CLI tools.
    2. Install Podman on an RHEL machine. For more information, see Podman installation instructions.
    3. Download and install the most recent version of the IBM Catalog Management Plug-in.
      1. Download the file based on the host operating system from IBM/ibm-pak-plugin/releases.
      2. Extract the binary file by entering the following command:

        tar -xf oc-ibm_pak-linux-amd64.tar.gz
      3. Run the following command to move the file to the /usr/local/bin directory:
        mv oc-ibm_pak-linux-amd64 /usr/local/bin/oc-ibm_pak
        Note: If you are installing as a non-root user, you must use sudo.
      4. You can confirm that oc ibm-pak -h is installed by running the following command:
        oc ibm-pak --help

        The plug-in usage is displayed.

    4. Make sure that the following network ports are available on the host.
Note: To find the relevant instructions for the latest interim fix, see the interim fix readme file.

About this task

Your Cloud Pak deployment also includes Cloud Pak foundational services. Make sure that your cluster has capacity to install foundational services, see Preparing to install foundational services.

The following diagram shows what you need to configure to use a private image registry. The actions that you need to take to set up the environment are shown in 3 steps in the diagram.

  1. Save or fetch the case archive.
  2. Configure the credentials for the source and target registries, and then mirror the images.
  3. Configure an OCP cluster by installing the operator catalog and an instance of the Cloud Pak operator in a chosen namespace.
Local registry high-level architecture

Procedure

  1. Make sure that the following network ports are available on the host.
    Tip: If the local host is unable to retrieve the source images from the public registries, you might need to allow specific access to these sites. A HTTP 403 response is an indication of such a parsing error. Docker and quay image registries might use proxies or mirror sites, so if you see images blocked check whether it is related to one of these image registries. If one of the registries is blocked, you must add that URL to the website allowlist. The following websites can be added to the allowlist to prevent pulling image errors.
    cp.icr.io/cp
    *.quay.io/opencloudio
    *.icr.io/cpopen
  2. Download the Cloud Pak for Business Automation images to your host.
    1. View the current config of the IBM Catalog Management Plug-in (ibm-pak) by running the following command:

      oc ibm-pak config

      The output lists all the configured repositories. The default repository from where the CASE files are downloaded has an asterisk mark (*) against the Name field.

    2. You can then run the following command to configure a repository that downloads the CASE files from the cp.icr.io registry (an OCI-compliant registry) before you run the oc ibm-pak get command.

      oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable

      The command sets 'IBM Cloud-Pak OCI registry' as the default repository.

    3. You can list all the available CASE files to download by running the following command:

      oc ibm-pak list

      To get more help about the list command, run the following command:

      oc ibm-pak list --help
    4. Get the cp4ba-case-to-be-mirrored-24.0.0.txt file from the Git cert-kubernetes repository.

      A CASE package is no longer delivered in 24.0.0. All the installation and upgrade artifacts are contained in the cert-kubernetes repository. It is recommended to use the latest interim fix of the release, but if you do need a previous version then you can find them all in the Cloud Pak for Business Automation download document.

      Tip: Use the move right arrow Move right arrow below the 24.0.0 release to find all the available interim fixes.

      To download the cert-kubernetes repository.

      1. Open the Cloud Pak for Business Automation download document, find the card for the latest 24.0.0 interim fix, click Cert Kubernetes, and then select and copy the displayed command.
      2. Run the copied git clone command to download the files.
      Note: The cert-kubernetes/scripts/airgap/cp4ba-case-to-be-mirrored-24.0.0.txt file contains all the dependent case files that are required to install Cloud Pak for Business Automation.
    5. Create the workspace.
      mkdir /root/2400
    6. Run the following command to set the environment variable $IBMPAK_HOME.
      export IBMPAK_HOME=/root/2400
    7. Set the following environment variables with the installer image name and the version.
      export CASE_NAME=ibm-cp-automation
      export CASE_VERSION=24.0.0
    8. When you are ready to start the download of the CASE files, run the following command:

      oc ibm-pak get -c file://<absolute path to file>/cp4ba-case-to-be-mirrored-24.0.0.yaml

      The <absolute path to file> needs to be a path that starts from "/". For example, "/opt".

      By default, the root directory that is used by the ibm-pak plug-in is ~/.ibm-pak. Therefore, by default, the Cloud Pak for Business Automation CASE is downloaded to ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION.

      Tip: You can configure the root directory by setting the IBMPAK_HOME environment variable.
    9. To list the versions of all the downloaded CASE files, you can run the following command:

      oc ibm-pak list --downloaded

      If IBMPAK_HOME is set, the downloaded CASE is located in $IBMPAK_HOME/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION. The logs files can be found in $IBMPAK_HOME/.ibm-pak/logs/oc-ibm_pak.log.

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

      A new directory $IBMPAK_HOME/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. The mirror directory stores the catalog-sources.yaml, image-content-source-policy.yaml, and image-set-config.yaml files.

      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. By selecting any specified filter all the dependency foundational services images are also 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.
    Business Automation Insights standalone ibmcp4baProd,ibmcp4baBAIImages,ibmEdbStandard
    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 $IBMPAK_HOME/.ibm-pak directory structure is built over time as you save CASEs and mirror. The following tree shows an example of the $IBMPAK_HOME/.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
  5. Run the oc mirror command to mirror the catalogs.
    Note: By default, the oc mirror command mirrors all the images from all channels in the CP4BA multi-pattern catalog and CP4BA FNCM catalog. You can edit the $IBMPAK_HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-set-config.yaml file to remove the OLM channels and keep only the v24.0 channel. This is only applicable for new installations.

    The following is a sample of image-set-config.yaml:

    - name: ibm-cp4a-operator
          channels:
          - name: v21.3
          - name: v22.1
          - name: v22.2
          - name: v23.1
          - name: v23.2
          - name: v24.0

    Run the oc mirror --config command which is generated from the previous step.

    oc mirror --config /root/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-set-config.yaml \
    docker://$TARGET_REGISTRY/cp4ba2400 \
    --dest-skip-tls \
    --max-per-registry=6

    You must run the command 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

    Use the configuration of the non-curated catalog to mirror the images. 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 cp4ba-2400.txt file.

    nohup oc mirror --config /root/cp4ba/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-set-config.yaml \
    docker://$TARGET_REGISTRY/cp4ba2400 \
    --dest-skip-tls \
    --max-per-registry=6 > /opt/cp4ba-2400.txt 2>&1 &
  6. Update the global image pull secret for your Red Hat 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.
  7. Run the following command to create ImageContentsourcePolicy.
    Note: If there is an existing ImageContentsourcePolicy named ibm-cp-automation on the cluster, then on running the command, it overwrites the existing mirroring configuration due to which all deployments on the cluster are affected. To keep the existing mirroring configuration of the ImageContentsourcePolicy unchanged, you must update the existing ImageContentsourcePolicy manually with the mirroring configuration that is created in the file that is located at $IBMPAK_HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml.
    oc apply -f $IBMPAK_HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
  8. Verify that the ImageContentsourcePolicy resource is created.
    oc get imageContentSourcePolicy
  9. 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.

  10. Create a project for the CASE commands (cp4ba 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=cp4ba
    oc new-project $NAMESPACE
  11. 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}'"]}}}' 
  12. You can now go and install the Cloud Pak operators. For more information, see Installing the Cloud Pak catalog and operator instances.
    Note: When executing the script cp4a-clusteradmin-setup.sh to install choose "offline" to install operators.

What to do next

Continue to prepare everything that you need for each capability that you want to install in Preparing your chosen capabilities.