Installing IBM Cloud Paks

The following tasks represent the typical task flow for performing your IBM Cloud Pak® installation:

Install Red Hat OpenShift Container Platform
(Optional) Mirroring IBM Cloud Pak images to a private container registry using the IBM Catalog Management Plug-in for IBM Cloud Paks (ibm-pak plugin)
Add the IBM operator catalog and prepare your cluster
Install IBM operator
Attach entitlement key
Create your IBM Cloud Pak instance

Note: While the overall steps in this process apply to the IBM Cloud Paks, you should still consult your IBM Cloud Pak Installation documentation for additional steps that might be required.

Important: Some steps require you to have cluster admin access.

1. Install Red Hat OpenShift Container Platform

Review the Planning section.

Most IBM Cloud Paks require OpenShift to be installed and running. For detailed steps about how to install OpenShift, see Installing Red Hat OpenShift Container Platform.

Note: Ensure that you have a supported version of OpenShift installed. For more information about OpenShift compatibility, see IBM Cloud Pak and Red Hat OpenShift Container Platform compatibility.

For any steps that use the Red Hat® OpenShift® Container Platform command line interface (CLI), you must be logged in to your OpenShift cluster with oc login.

After you install OpenShift, you can verify and gain access to your container software by using your IBM entitlement key that you create in Create the entitlement keys.

Important: Having access to an entitlement key implies that you have access to Passport Advantage®, where the software was purchased from.

You can have one central account (a functional ID) that can be associated with the entitlement key that you want to use for your installation. You also need to create an IBM ID to associate with your functional ID to use the Passport Advantage “Manage Access” tools so that you can grant your functional id download access to your Passport Advantage site. However, note that a primary contact, administrative contact or site technical contact cannot be a functional ID since they are accepting legal terms of responsibility for managing the site. For more information about how entitlement works, see Managing entitlements.

2. (Optional) Mirroring IBM Cloud Pak images to a private container registry using the IBM Catalog Management Plug-in for IBM Cloud Paks (ibm-pak plugin)

The IBM Catalog Management Plug-in for IBM Cloud Paks simplifies the process for discovering required IBM product images and and uses standard Red Hat tooling for registry and cluster access. The metadata is packaged within 1-n CASEs (Container Application Software for Enterprise) which specify the composition of the product (for example, OLM packages, channels, and so on) and ultimately images that must be copied into an air-gapped environment.

Additionally, the ibm-pak plug-in extends the OpenShift CLI (oc command) capability to streamline the process of delivering installation images to the IBM Cloud Pak in an air-gapped environment.

Note: The IBM Catalog Management Plug-in for IBM Cloud Paks will be referred to in the documentation as ibm-pak plug-in.

For more information about installing an IBM Cloud Pak by using a private container registry, see Installing your IBM Cloud Pak by mirroring Cloud Pak images to a private container registry (with ibm-pak plug-in). For more information about available CASE names and versions, see IBM: Product CASE to Application Version.

Red Hat OpenShift Container Platform requires you to have cluster admin access to run the install-operator command.

3. Add the IBM operator catalog and prepare your cluster

Add the IBM operator catalog

The IBM operator catalog is an index of operators available to automate deployment and maintenance of IBM Software products into Red Hat® OpenShift® Container Platform clusters. Operators within this catalog are built following Kubernetes best practices and IBM standards to provide a consistent, integrated set of capabilities. The catalog can be added to any Red Hat OpenShift Container Platform 4.6 and newer cluster by application of the CatalogSource resource.

On Red Hat OpenShift Container Platform clusters that run Red Hat OpenShift Container Platform 4.8 and earlier, the catalog tag in the CatalogSource is set to latest to obtain the most recent version of the catalog. On Red Hat OpenShift Container Platform clusters that run Red Hat OpenShift Container Platform 4.9 or 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. On Red Hat OpenShift Container Platform clusters that run Red Hat OpenShift Container Platform 4.9 and earlier, the olm.catalogImageTemplate annotation has no effect.

Notes:

In February, 2023, the IBM Operator Catalog will be changing from the deprecated SQLITE format to the file-based Catalog format. This change is largely transparent and will not affect CatalogSources installed on OpenShift Container Platform. Customers using the opm command-line utility with deprecated subcommands and flags that require the SQLITE format will fail, such as opm index prune. For more information about working with custom, file-based catalogs, see the Red Hat OpenShift Container Platform version 4.11 documentation.
If you deploy your catalog to the openshift-marketplace namespace, you must have cluster admin access. If you deploy the catalog to another IBM Cloud Pak-specific namespace, only namespace admin access is required.

Creating CatalogSource with OpenShift

Log in to your Red Hat OpenShift Container Platform cluster.
Click Home > Search > Resources, then select CatalogSource.
Click Create CatalogSource.
In the CatalogSource name field, enter ibm-operator-catalog.
In the Publisher name field, enter IBM.
In the Image (URL of container image) field, enter icr.io/cpopen/ibm-operator-catalog:latest.
Under Availability, select the Cluster-wide CatalogSource option.

You can verify successful CatalogSource creation by going into the OperatorHub where the IBM Operator Catalog now exists as a source value. You are also provided with a confirmation after the CatalogSource value is completed in Red Hat OpenShift Container Platform. It can sometimes take approximately 5 minutes for the CatalogSource to appear in OperatorHub after successful completion.

CLI enablement

The catalog can be added by applying the following YAML file to the Red Hat OpenShift Container Platform cluster. Create this file and name it catalog_source.yaml.

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

Apply the YAML file by using the command:

oc apply -f catalog_source.yaml -n openshift-marketplace

Verify the CLI installation

oc get CatalogSources ibm-operator-catalog -n openshift-marketplace

You receive this output on error:

Error from server (NotFound): catalogsources.operators.coreos.com "ibm-operator-catalog" not found

You receive this output on success:

NAME                   DISPLAY                 TYPE   PUBLISHER      AGE
ibm-operator-catalog   IBM operator Catalog    grpc   IBM            28s

4. Install the operator

You can install your operator by using the OpenShift console or the OpenShift CLI. Operators span all of your clusters. As such, cluster admin access is required to deploy operators.

Note: A project is a Kubernetes namespace.

Option 1: Install the operator with the OpenShift console

Log in to your OpenShift cluster's console.
Click Operators > OperatorHub. The OperatorHub page is displayed.
In the All Items field, enter the full name of your IBM Cloud Pak. The operator is displayed.
Click the tile that has the full name of your IBM Cloud Pak. The window with the name of your IBM Cloud Pak is displayed.
Click Install. The Install Operator page is displayed.
Enter the following values:
- Set Update Channel to the latest version available for your IBM Cloud Pak.
- Set the Installation mode to A specific namespace on the cluster.
- Set the Namespace to the project (namespace) value that you want to install the operator into.
  
  Note: When using the console to install the operator, you can either use an existing namespace, the default namespace that is provided by the operator, or create a new namespace. If you want to create a new namespace, you can create it from this form. If you want to create a namespace before installing, from the Project list, select Create Project, specify the Name of the project that you want to create, and click Create.
- Set Approval Strategy to Automatic.
Click Install and wait for the your operator to install.

OpenShift informs you that the installation is complete. You can verify that installation by navigating to Operators > Installed Operators, and selecting your project from the Projects dropdown. The operator that you have just installed and all of its dependent operators in the project are listed with a status of Succeeded.

Option 2: Install the operator with the OpenShift CLI

Determine whether you want to create a new, or reuse an existing namespace to install your operator into. To create a new namespace in the CLI, run the following command:
```
oc create namespace <namespace>
```
Where <namespace> is the name of the namespace that you want to create.
Create Operator Group.

You must create an operator group in your custom project (namespace), or your operator will not install. There might be an operator group for managing a namespace for given APIs. If there is an Operator group for the namespace, do not create a second one.

Create the Operator group by running the following command:
```
cat << EOF | oc apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: <your-operator-group>
  namespace: <namespace>
spec:
  targetNamespaces:
    - <namespace>
EOF
```

Install your operator with the following command:

cat << EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: <your-operator-group>
  namespace: <namespace>
spec:
  channel: <latest-version-of-your-cloud-pak>
  installPlanApproval: Automatic
  name: <your-operator-group>
  source: ibm-operator-catalog
  sourceNamespace: openshift-marketplace
EOF

After a few minutes, the operator is installed. Run the following command to verify that all of the components are in the Succeeded state:
```
oc get csv -n <namespace> | grep <your-operator-group>
```
Where <namespace> is openshift-operators if you are using the AllNamespaces installation mode, or the project (namespace) if you are using the OwnNamespace installation mode.

5. Create the entitlement key secret

Complete the following steps to create a docker-registry secret to enable your deployment to pull operand images from the IBM® Entitled Registry.

If you create your entitlement key at the namespace level, namespace admin access is required. If you add the key to the global pull secret, cluster admin access is required.

Important: Having access to an entitlement key implies that you have access to Passport Advantage®, where the software was purchased from.

Option 1: Create the entitlement key secret with the OpenShift console

Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library with the IBMid and password details that are associated with the entitled software.
In the OpenShift console, ensure that you are in the Project (for example, paks) that you installed the operator into.
Click Workloads > Secrets > Create, then select Image pull secret.
In the Secret name field, enter ibm-entitlement-key.
In the Registry server address field, enter cp.icr.io.
In the Username field, enter cp.
In the Password field, enter the credential that you received from entitlement.
(Optional) In the Email field, enter a contact email address.

Option 2: Create the entitlement key secret with the CLI

Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library with the IBMid and password details that are associated with the entitled software.
In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.

From the Red Hat OpenShift CLI, run the following command to create an image pull secret called ibm-entitlement-key.

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

Where:

- `<entitlement-key>` is the entitlement key that you copied in step 2.
- `<namespace>` is the namespace that you installed your IBM Cloud Pak operator in.

6. Create your IBM Cloud Pak instance

Log in to theRed Hat OpenShift Container Platform web console with your Red Hat OpenShift Container Platform cluster admin credentials.
Change Project to the namespace where you installed the operator in. Select the namespace from the Project drop-down list.
In the navigation panel, click Operators > Installed Operators.
In the list on the Installed Operators panel, find and click your IBM Cloud Pak.
Click the tab corresponding to your IBM Cloud Pak.
Click Create , where <instance of your IBM Cloud Pak name> is the name of the instance type of that operator. For example, in IBM Cloud Pak for Watson AIOps, you can create an instance of AIManager. The instance creation panel opens, and offers two methods for configuring the resource; the Form view and the YAML view. The Form view is selected by default

Configuring in the Form view

The Form view opens a form that you can view or modify the resource configuration.

Note: Some fields might not be represented in the default form view.

In the Name field, enter a name for the new instance or leave the default.
Next to License, click the arrow to expand the license acceptance section.
Set License Accept to true if you accept the license agreement of your Cloud Pak.
For License LI, click the arrow to open the drop-down list, and select a license. For details about specific licenses, check the documentation on licensing for your particular Cloud Pak.
Specify the Storage class. Click the arrow to expand the Storage pane, then click the arrow for Select Storage Class and select a file storage class a file storage class that supports ReadWriteMany (RWX) volumes and allows read and write access to nonroot users. Supported storage providers include ibmc-file-gold-gid, Red Hat OpenShift Data Foundation (formerly Red Hat OpenShift Container Storage), Spectrum, and Portworx. For additional details about storage support and configuration, check the documentation on storage for your particular Cloud Pak.

Note: If you do not see any options in the Storage Class list, you need to create one or more storage options. See the Requirements section for more information.
Set any other configuration values as appropriate.
Click Create. The creation process can take a longer amount of time depending on your environment.

Your instance of the Cloud Pak is added to the list of instances in the current project (namespace).

Configuring in the YAML view

The YAML view opens an editor containing an example YAML file for a resource. Update the values in the file per the following steps:

Change metadata.namespace to your project (namespace) name.
Change spec.license.accept to true if you accept the license agreement for your Cloud Pak.
Change the value of spec.license.license to the license string that matches your version of Cloud Pak. Check the documentation on licensing for your particular Cloud Pak for more information.
For spec.storage.class, specify a file storage class a file storage class that supports ReadWriteMany (RWX) volumes and allows read and write access to non-root users. Supported storage providers include ibmc-file-gold-gid, OpenShift Data Foundation (formerly OpenShift Container Storage), Spectrum, and Portworx. For more details about storage support and configuration, check the documentation on storage for your particular Cloud Pak.
Click Create. The creation process can take a longer amount of time depending on your environment.

Your instance of Cloud Pak is added to the list of instances in the current project (namespace).

Verifying instance creation

You can verify that you've created an instance of your operator by completing the following steps:

Ensure that you're in the namespace that you created your operator in.
From the Home screen, click Operators > Installed Operators, then select the installed operator that you created the instance for.
Click All instances. An instance of the operator that you created is listed with a positive status message, like Succeeded or Completed.

Access the console

Use the following command to get the URL to access the console:

oc get route -n <YOUR_OPERATOR_NAME> cp-console -o jsonpath=‘{.spec.host}’

The preceding command returns the following output:

cp-console.apps.mycluster.mydomain.com

Based on the example output, your console URL would be https://cp-console.apps.mycluster.mydomain.com.

Retrieve your console username and password

The default username to access the console is admin.

You can get the password for the admin username by running the following command:

oc -n <YOUR_OPERATOR_NAME> get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d

The following password is an example of the output of the preceding command:

EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA

Based on the example output, you would then use EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA as the password.

You have now successfully created and deployed your IBM Cloud Pak environment using a private container registry.

Assess compatibility with other IBM Cloud® Paks on the cluster

Some IBM Cloud Paks might only support installation at the AllNamespaces (cluster) installation mode. If your IBM Cloud Pak depends on IBM® Automation foundation, if the Automation foundation operators were installed by another IBM Cloud Pak, they must also be installed at the AllNamespaces installation mode. If there are other IBM Cloud Paks installed on the cluster, ensure that they were also installed by using the AllNamespaces installation mode. Refer to the IBM Documentation for your specific IBM Cloud Paks, to determine how to configure their installation mode. For more information about configuring operator installation mode, see Adding operators to a cluster Opens in a new tab .