Installing IBM Cloud Paks

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.

1. Log in to your OpenShift cluster's console.
2. Click Operators > OperatorHub. The OperatorHub page is displayed.
3. In the All Items field, enter the full name of your IBM Cloud Pak. The operator is displayed.
4. 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.
5. Click Install. The Install Operator page is displayed.

6. 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.

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

1. 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.

2. 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
   

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

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

1. 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.
2. In the OpenShift console, ensure that you are in the Project (for example, paks) that you installed the operator into.
3. Click Workloads > Secrets > Create, then select Image pull secret.
4. In the Secret name field, enter ibm-entitlement-key.
5. In the Registry server address field, enter cp.icr.io.
6. In the Username field, enter cp.
7. In the Password field, enter the credential that you received from entitlement.
8. (Optional) In the Email field, enter a contact email address.

1. 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.
2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.

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

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

1. In the Name field, enter a name for the new instance or leave the default.
2. Next to License, click the arrow to expand the license acceptance section.
3. Set License Accept to true if you accept the license agreement of your Cloud Pak.
4. 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.

5. 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.

6. Set any other configuration values as appropriate.

7. 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).

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

1. Change metadata.namespace to your project (namespace) name.
2. Change spec.license.accept to true if you accept the license agreement for your Cloud Pak.
3. 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.
4. 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.
5. 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).

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

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

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.

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.