Preparing to install online

Before you can install products in IBM Z and Cloud Modernization Stack, you must set up the environment in Red Hat® OpenShift® Container Platform. For help with installing Red Hat® OpenShift® Container Platform, see Installing Red Hat software External link icon in the IBM Cloud Pak® documentation.

This topic includes the following information:

Before you start

  • Review the information in Planning.
  • Log in to your Red Hat® OpenShift® cluster with oc login for any steps that use the Red Hat® OpenShift® Container Platform command-line interface (CLI).
  • Log in to Red Hat® OpenShift® Container Platform with your cluster-admin user role. If you are another role, you need to ask a cluster-admin role user to grant you the access or add you to an existing group that has cluster-admin privileges.

Procedure overview

When these steps are complete, you can proceed to install the products in IBM Z and Cloud Modernization Stack.

1. Install Red Hat® OpenShift® Container Platform

You must have administrative access to your OpenShift® cluster.

For information on supported versions of OpenShift®, see Supported versions of Red Hat OpenShift Container Platform.

Follow the instructions in Installing Red Hat OpenShift Container Platform External link icon in the Red Hat documentation.

2. Install Red Hat® OpenShift® Container Platform CLI

Install the Red Hat® OpenShift® Container Platform command line interface (oc) on your cluster's boot node and run oc login, using the instructions in Getting started with the OpenShift CLI External link icon in the Red Hat® documentation.

3. Configure persistent storage

Red Hat® OpenShift® Container Platform uses the Kubernetes persistent volume (PV) framework. PVs are storage resources in the cluster. Persistent volume claims (PVCs) are storage requests that are made on those PVs by IBM Z and Cloud Modernization Stack. For information, see Understanding persistent storage External link icon in the Red Hat® documentation.

Persistent storage requirements vary by product in IBM Z and Cloud Modernization Stack. See System requirements for sizes, access modes, and storage type. You also need to set the storage class.

The persistent storage that you choose must support the ReadWriteMany (RWX) or ReadWriteOnce (RWO) access modes. For information, see Access modes External link icon in the Red Hat documentation.

The storage type must be either Filesystem or Block. For information, see Block volume support External link icon in the Red Hat documentation.

For production environments, storage classes must have allowVolumeExpansion enabled. This allows persistent volumes to be expanded if necessary, to avoid storage from filling up and causing unrecoverable failures. This is also highly recommended for trial and starter deployments, since without it you are limited to the default capacity that might not be sufficient for your needs.

To enable allowVolumeExpansion:

  1. Edit the storage class to enable expansion. Follow the instructions in Enabling volume expansion support External link icon in the Red Hat documentation.

  2. Modify the individual PVCs to increase capacity. Follow the instructions in Expanding persistent volume claims (PVCs) with a file system External link icon in the Red Hat® documentation.

4. Create a project (namespace)

In Red Hat® OpenShift® Container Platform, a project is a Kubernetes namespace with additional annotations. You must create a project for any of the products in IBM Z and Cloud Modernization Stack that use a Security Context Constraint (SCC) because SCCs cannot be assigned to pods that are created in one of the default Red Hat® OpenShift® projects (namespaces).

You can create a project (namespace) with either of the following methods:

  • Option 1: Create a project with the OpenShift® console.

    1. From your OpenShift console, click Home > Projects.
    2. Select Create Project, specify the Name of the project that you want to create and click Create.

  • Option 2: Create a project with the OpenShift® CLI.

    1. Run oc create namespace <namespace> where <namespace> is the name of the project (namespace) that you want to create.

5. Create an image pull secret

After you purchase IBM Z and Cloud Modernization Stack from Passport Advantage®, go to Entitlement key and click Add New Key to generate an entitlement key.

You need to supply your entitlement key as a Kubernetes image pull secret key to a namespace, which then enables the entitled images to be retrieved from IBM Entitled Registry.

Configuring global Secret for non-ROKS (Red Hat OpenShift Kubernetes Service aka Openshift on IBM Cloud) users

A cluster-admin can update the pull-secret in the openshift-config project which allows the Entitlement Key to be used globally across the cluster.

Complete these steps to update the pull-secret details.

  1. Log in to the Red Hat OpenShift web console.

  2. In the Administrator mode, go to Workloads and then click Secrets. Make sure that you select openshift-config from the Project list.
    An image showing openshift-config project selected on the secrets page.

  3. In the Secrets section, search for pull-secret.

  4. Click pull-secret from the results.
    An image showing pull-secret on the secrets page.

  5. From the Actions drop-down list, select Edit Secret.
    An image showing edit options for pull-secret on the secrets page.

  6. Update this secret with the following info, using the Entitlement Key as the password:

    • Registry server address: cp.icr.io
    • Username: cp
    • Password: <ibm-entitlement-key>

    An image showing edit options for pull-secret on the secrets page.

  7. Click Save.

Configuring global Secret for Red Hat OpenShift Kubernetes Service users

Complete these steps to update the pull-secret details.

  1. Log in to IBM Cloud by running ibmcloud login -a https://cloud.ibm.com.
  2. Run ibmcloud oc cluster ls to retrieve the Cluster Name or ID of the IBM Cloud Cluster.
  3. Note the ID of the worker nodes in your cluster.
    ibmcloud oc worker ls -c <cluster_name_or_ID>
  4. Reload each worker node.
    a. For classic clusters:
    ibmcloud oc worker reload -c <cluster_name_or_ID> -w <workerID_1> -w <workerID_2>
    b. For vpc-gen2 clusters:
    ibmcloud oc worker replace -c <cluster_name_or_ID> -w <workerID_1> -w <workerID_2>

Configuring namespace scoped Secret

Run the following command to generate a namspace scoped image pull secret.

oc create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password=<entitlement-key> --docker-server=cp.icr.io

6. Create the catalog source

You must add the catalog source for products in IBM Z and Cloud Modernization Stack to your Red Hat OpenShift cluster. You can create the catalog source either with the Red Hat® OpenShift® web console or with the CLI. Helm chart enablement is also possible and offers some advantage in managing the CatalogSource resource. If there are changes to it, they are applied when the chart is upgraded to the latest version. When you use a CLI enablement, you must watch for changes to the catalog source definition as published in the Red Hat® documentation.

On Red Hat® OpenShift® Container Platform clusters that run Red Hat® OpenShift® Container Platform 4.9 and later, the olm.catalogImageTemplate annotation is used to switch the catalog tag from latest to a different tag based on the Kubernetes version used by the cluster. Setting the annotation causes the catalog to automatically switch to a catalog that is compatible with the cluster whenever the cluster is updated to a new Kubernetes version. For example for Red Hat® OpenShift® Container Platform 4.9, the tag updates to v1.22 instead of latest.

  • To create the catalog source with the Red Hat OpenShift web console:

    1. Log in to your OpenShift® cluster's console.
    2. Add the IBM Operator Catalog CatalogSource. Click the plus icon in the upper right corner to open the Import YAML dialog box, paste in the following content and click Create.
    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 Content
sourceType: grpc
image: icr.io/cpopen/ibm-operator-catalog:latest
updateStrategy:
  registryPoll:
  interval: 45m
    1. Go to Administration > Cluster Settings. Under Global Configuration > OperatorHub > Sources, verify that the ibm-operator-catalog CatalogSource object is present.

  • To create the catalog source with the OpenShift® CLI:

    1. Add the IBM Operators CatalogSource by running the following command:
    cat << EOF | oc apply -f -
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 Content
sourceType: grpc
image: icr.io/cpopen/ibm-operator-catalog:latest
EOF
    1. Verify that the ibm-operator-catalog CatalogSource object is present, and is returned by the following command:
    oc get CatalogSources ibm-operator-catalog -n openshift-marketplace

Example output:

oc get CatalogSources ibm-operator-catalog -n openshift-marketplace
NAME                   DISPLAY                 TYPE   PUBLISHER   AGE
ibm-operator-catalog   IBM Operator Catalog    grpc   IBM         4h13m
  • To install the IBM Operator Catalog by using a Helm Chart that is provided in the Red Hat® OpenShift® Container Platform Developer catalog, complete the following steps:
  • To install the IBM Operator Catalog by using a Helm Chart that is provided in the Red Hat® OpenShift® Container Platform Developer catalog, complete the following steps:
    1. Log in to your OpenShift® Container Platform UI instance.
    2. Select the Developer view.
    3. Go to the +Add section of the Developer view and select From Catalog.
    4. Select the project (namespace) for the Helm release to be installed.
    5. Select Type of Helm Charts and enter search criteria of operator.
    6. Click the IBM Operator Catalog tile.
    7. Click Install Helm Chart.
    8. Enter true to accept the license.
    9. Click Install.

7. Pre-install IBM Cloud Pak foundational services

From the Red Hat® OpenShift® Container Platform UI, navigate to Operators > OperatorHub and search for IBM Cloud Pak foundational services. Click IBM Cloud Pak foundational services and install the operator into (All Namespaces). Upon successful installation, the operator is listed on the Installed Operators page.

IBM Cloud Pak foundational services is automatically installed for licensing purpose during the installation of an operator. However by pre-installing IBM Cloud Pak foundational services, any 'Namespace' related issues can be prevented during installation process of other operators.

Where next?

Where next?

The Red Hat® OpenShift® Container Platform setup is complete. Go to Installing products for the actions to take next.