Adding catalog sources to a cluster

Adding catalog sources to your OpenShift cluster adds the IBM operators to the list of operators you can install.

This task must be performed by a cluster administrator. For more information, see Roles and permissions.

Before you begin: For air-gapped installations only, follow the guidance in Mirroring images for an air-gapped cluster first. You can skip to adding catalog sources only if your cluster is connected to the internet.

To add the catalog sources to your cluster, you use one of the following sources:

  • Specific catalog sources for each operator

  • The IBM Operator Catalog (online-only)

For most online and offline clusters, applying individual catalog sources is the most effective way to fully control software versioning on a cluster. This allows administrators to:

  • upgrade each Cloud Pak capability independently.

  • have a fully declarative set of artifacts to recreate exact installations.

  • easily control the upgrade and promotion through environments with a CI/CD pipeline.

  • remove the usage of manual approval settings on operators which should not be used. With catalog source control, the upgrade can only happen when the specific image digest for the specific catalog source is changed.

The only applicable use case for the IBM Operator Catalog is installations where you want upgrades of operators and the IBM Cloud Pak foundational services to always be automatic, and where deterministic installs are not needed. In other words, it is best used only for proof of concept environments, not for production environments.

Adding specific catalog sources for each operator

This procedure must be performed by using the CLI.

Preliminary step: If you have not already installed it, or if it needs updating, download the IBM Catalog Management plug-in (version 1.1.0 or later) from GitHub. This plug-in allows you to run oc ibm-pak commands against the cluster.

Run the following steps for each of the Cloud Pak operators that you need to install. A list of values to use for the placeholders CASE_NAME and CASE_VERSION can be found at the end of this section. Replace ARCHITECTURE with either amd64, s390x or ppc64le.

(Online-only) Generate the catalog source files:

This task is:

  • Intended for online clusters only. For clusters in air-gapped (restricted) environments, this was already handled as part of Mirroring images for an air-gapped cluster.

  • Also required for users (with online clusters) who are applying catalog sources fix packs prior to an upgrade.

  1. Log into your cluster using the oc login command and your user credentials:

    oc login <openshift_url> -u <username> -p <password> -n <namespace>
  2. Export the variables for the command line to use. The table at the end of this section provides the export commands for all operators:

    export CASE_NAME=<CASE_NAME>
    export CASE_VERSION=<CASE_VERSION>
    export ARCH=<ARCHITECTURE>

    For example:

    export CASE_NAME=ibm-integration-platform-navigator
    export CASE_VERSION=7.0.4
    export ARCH=amd64
  3. Download the files for the desired operator:

    oc ibm-pak get ${CASE_NAME} --version ${CASE_VERSION}
  4. Generate the catalog sources required for this operator:

    oc ibm-pak generate mirror-manifests ${CASE_NAME} icr.io --version ${CASE_VERSION}
  5. You can get the catalog sources generated and save them on another directory in case this install needs to be replicated in the future.
    Important: Some operators include new versions of the foundational services catalog source. If you do not want to upgrade foundational services, you must remove the opencloud-operators catalog source from the file.

    This command might not return anything if there are no multi-architecture catalog sources for the components being installed.

    To get the catalog sources, run:

    cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml

    Also run the following command to discover whether there are any architecture-specific catalog sources you need. This command might not return anything if there are no architecture-specific catalog sources for the components being installed. Even if this is the case, those components can still be installed in the supported architecture.

    cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources-linux-${ARCH}.yaml

    You can also navigate to the directory in your file browser (if needed) to copy these artifacts into files you want to keep for re-use or for pipelines.

Apply the catalog sources:

This task applies equally to clusters in online and air-gapped environments.

Prerequisites (if you are applying catalog sources fix packs prior to an upgrade):

  • Confirm that your operators are running properly.

  • If there are any pending operator updates that require manual approval, approve those before starting this procedure. For more information, see "Restricting automatic updates with an approval strategy" in Installing the operators by using the Red Hat OpenShift console.

  1. Apply the catalog sources for this operator to the cluster. This command might not return anything if there are no multi-architecture catalog sources for the components being installed:

    oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml

    Also run the following to confirm if there are any architecture-specific catalog sources to apply. If there are no architecture-specific catalog sources you can skip this.

    oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources-linux-${ARCH}.yaml
  2. Confirm that the catalog sources have been created in the openshift-marketplace project/namespace:

    oc get catalogsource -n openshift-marketplace
  3. Repeat the steps for each operator you want to install, replacing the CASE name and CASE version placeholders with the values in the following table.

Export commands for all operators

Copy and run the codeblock content in the Export commands column to set the environment variables for a given operator:

Operator Export commands
IBM Cloud Pak for Integration export CASE_NAME=ibm-integration-platform-navigator && export CASE_VERSION=7.0.4
IBM Automation foundation assets export CASE_NAME=ibm-integration-asset-repository && export CASE_VERSION=1.5.19
IBM Cloud Pak for Integration Operations Dashboard export CASE_NAME=ibm-integration-operations-dashboard && export CASE_VERSION=2.6.22
IBM API Connect export CASE_NAME=ibm-apiconnect && export CASE_VERSION=4.0.8
IBM App Connect export CASE_NAME=ibm-appconnect && export CASE_VERSION=8.1.0
IBM MQ export CASE_NAME=ibm-mq && export CASE_VERSION=2.3.3
IBM Event Streams export CASE_NAME=ibm-eventstreams && export CASE_VERSION=1.7.6
IBM DataPower Gateway export CASE_NAME=ibm-datapower-operator && export CASE_VERSION=1.6.14
IBM Aspera HSTS export CASE_NAME=ibm-aspera-hsts-operator && export CASE_VERSION=1.5.12
IBM Cloud Pak foundational services export CASE_NAME=ibm-cp-common-services && export CASE_VERSION=1.19.13

You must also use one of these values to set your architecture:

export ARCH=amd64
export ARCH=ppc64le
export ARCH=s390x

Adding catalog sources with the IBM Operator Catalog (online-only)

Important: Only use the IBM Operator Catalog for online installations where automatic upgrades of operators and foundational services are always going to be desired, and declarative installs are not needed. This is usually the case for proof of concept environments, only.

This procedure can be performed by using the CLI or by using the OpenShift web console.

Using the CLI

  1. Copy this resource definition for IBM operators into a local file on your computer:

    apiVersion: operators.coreos.com/v1alpha1
    kind: CatalogSource
    metadata:
      name: ibm-operator-catalog
      namespace: openshift-marketplace
      annotations:
        olm.catalogImageTemplate: "icr.io/cpopen/ibm-operator-catalog:v{kube_major_version}.{kube_minor_version}"
    spec:
      displayName: IBM Operator Catalog
      publisher: IBM
      sourceType: grpc
      image: icr.io/cpopen/ibm-operator-catalog:latest
      updateStrategy:
        registryPoll:
          interval: 45m
  2. Run the following command. Replace <filename.yaml> with the name of the file you created in the first step:

    oc apply -f <filename.yaml>

Using the OpenShift web console

  1. Log into the OpenShift web console with your OpenShift cluster administrator credentials.

  2. In the banner, click the plus ("+") icon to open the Import YAML dialog box.
    Note: You do not need to select a value for "Project". The YAML in the next step already includes correct value for metadata:namespace, which ensures the catalog source is installed in the correct project (namespace).
  3. Paste this resource definition into the dialog box:

    apiVersion: operators.coreos.com/v1alpha1
    kind: CatalogSource
    metadata:
      name: ibm-operator-catalog
      namespace: openshift-marketplace
      annotations:
         olm.catalogImageTemplate: "icr.io/cpopen/ibm-operator-catalog:v{kube_major_version}.{kube_minor_version}"
    spec:
      displayName: IBM Operator Catalog
      image: 'icr.io/cpopen/ibm-operator-catalog:latest'
      publisher: IBM
      sourceType: grpc
      updateStrategy:
        registryPoll:
          interval: 45m
  4. Click Create.

Next steps

If you are: