Installing Cloud Pak for Data

Before you begin

Ensure that a cluster administrator completed the required pre-installation tasks for your environment. Specifically, verify that a cluster administrator completed the following tasks:

1. If you are using the specialized installation method, ensure that IBM Cloud Pak foundational services is installed. For details, see Installing IBM Cloud Pak foundational services.
2. The project where you plan to install Cloud Pak for Data exists. For details, see Setting up projects (namespaces) on Red Hat OpenShift Container Platform.
3. For environments that use a private container registry, such as air-gapped environments, the Cloud Pak for Data software images are mirrored to the private container registry. For details, see Mirroring images to your private container registry.
4. The cluster is configured to pull the software images. For details, see Configuring your cluster to pull Cloud Pak for Data images.
5. The Cloud Pak for Data platform operator catalog source exists. For details, see Creating catalog sources.
6. The Cloud Pak for Data platform operator subscription and the IBM NamespaceScope Operator subscription exist. For details, see Creating operator subscriptions.

If you do not complete these steps, the Cloud Pak for Data installation will fail.

Procedure

To install Cloud Pak for Data:

1. Log in to the Red Hat OpenShift Container Platform as a user with sufficient permissions to complete the task:

   oc login ${OCP_URL}

2. Enable the IBM Cloud Pak for Data platform operator and the IBM Cloud Pak foundational services operator to watch the project where you will install IBM Cloud Pak for Data:

   ---

   Express installations

   Create an operand request to grant permission to the IBM Cloud Pak for Data platform operator and the IBM Cloud Pak foundational services operator to manage the project where you plan to install Cloud Pak for Data.

   cat <<EOF |oc apply -f -
   apiVersion: operator.ibm.com/v1alpha1
   kind: OperandRequest
   metadata:
     name: empty-request
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     requests: []
   EOF

   ---

   Specialized installations

   Update the NamespaceScope object in the Cloud Pak for Data operators project to watch the project where you plan to install Cloud Pak for Data.

   1. Check whether there is already a NamespaceScope object named cpd-operators in the {PROJECT_CPD_OPS} project:

      oc get NamespaceScope -n ${PROJECT_CPD_OPS}

   2. Complete the appropriate step for your environment:

      The command returns No resources found in the ... namespace

      Run the following command to create the NamespaceScope object:

      cat <<EOF |oc apply -f -
      apiVersion: operator.ibm.com/v1
      kind: NamespaceScope
      metadata:
        name: cpd-operators
        namespace: ${PROJECT_CPD_OPS}
      spec:
        namespaceMembers:
        - ${PROJECT_CPD_OPS}
        - ${PROJECT_CPD_INSTANCE}
      EOF

      The command returns information about the NamespaceScope object

      1. Run the following command to update the NamespaceScope object in the {PROJECT_CPD_OPS} project:

         oc patch NamespaceScope cpd-operators \
         -n ${PROJECT_CPD_OPS} \
         --type json \
         --patch "[{ \"op\": \"add\", \"path\": \"/spec/namespaceMembers/0\", \"value\": \"${PROJECT_CPD_INSTANCE}\" }]"

      2. To confirm that the project was added, run the following command to see the contents of the NamespaceScope YAML:

         oc get NamespaceScope cpd-operators -n ${PROJECT_CPD_OPS} -o yaml

         The namespaceMembers list should contain:

         • The project where the Cloud Pak for Data operators are installed (as specified by ${PROJECT_CPD_OPS}).
         • The project where you plan to install Cloud Pak for Data (as specified by ${PROJECT_CPD_INSTANCE}).

   ---

3. Create a custom resource to install Cloud Pak for Data. Follow the appropriate guidance for your environment:
   Important: By creating an Ibmcpd custom resource with spec.license.accept: true, you are accepting the license terms for Cloud Pak for Data. You can find links to the relevant licenses in Cloud Pak for Data License Information.

   ---

   The cluster uses the recommended storage class names on Red Hat OpenShift Container Storage

   The recommended storage class names are described in Setting up shared persistent storage.

   Create a custom resource with the following format:

   cat <<EOF |oc apply -f -
   apiVersion: cpd.ibm.com/v1
   kind: Ibmcpd
   metadata:
     name: ibmcpd-cr                        # This is the recommended name, but you can change it
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     license:
       accept: true
       license: ${LICENSE_CPD}
     storageVendor: ocs
     csNamespace: ${PROJECT_CPFS_OPS}
   EOF

   ---

   The cluster uses the recommended storage class names on Portworx

   The recommended storage class names are described in Setting up shared persistent storage.

   Create a custom resource with the following format:

   cat <<EOF |oc apply -f -
   apiVersion: cpd.ibm.com/v1
   kind: Ibmcpd
   metadata:
     name: ibmcpd-cr                        # This is the recommended name, but you can change it
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     license:
       accept: true
       license: ${LICENSE_CPD}
     storageVendor: portworx
     csNamespace: ${PROJECT_CPFS_OPS}
   EOF

   ---

   The cluster uses IBM Spectrum Scale Container Native storage

   The recommended storage class names are described in Setting up shared persistent storage.

   Create a custom resource with the following format:

   cat <<EOF |oc apply -f -
   apiVersion: cpd.ibm.com/v1
   kind: Ibmcpd
   metadata:
     name: ibmcpd-cr                        # This is the recommended name, but you can change it
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     license:
       accept: true
       license: ${LICENSE_CPD}
     storageClass: ibm-spectrum-scale-sc
     csNamespace: ${PROJECT_CPFS_OPS}
   EOF

   ---

   The cluster uses NFS storage

   The recommended storage class names are described in Setting up shared persistent storage.

   cat <<EOF |oc apply -f -
   apiVersion: cpd.ibm.com/v1
   kind: Ibmcpd
   metadata:
     name: ibmcpd-cr                        # This is the recommended name, but you can change it
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     license:
       accept: true
       license: ${LICENSE_CPD}
     storageClass: managed-nfs-storage
     csNamespace: ${PROJECT_CPFS_OPS}
   EOF

   ---

   The cluster uses custom storage classes

   If your cluster uses storage class names other than those described in Setting up shared persistent storage, you must tell Cloud Pak for Data what storage class names to use.

   Important: You cannot run this command as written. You must edit this command to specify valid storage classes.

   cat <<EOF |oc apply -f -
   apiVersion: cpd.ibm.com/v1
   kind: Ibmcpd
   metadata:
     name: ibmcpd-cr                        # This is the recommended name, but you can change it
     namespace: ${PROJECT_CPD_INSTANCE}
   spec:
     license:
       accept: true
       license: ${LICENSE_CPD}
     storageClass: RWX-storage-class        # Replace with the name of a RWX storage class
     zenCoreMetadbStorageClass: RWO-storage-class        # Replace with the name of a RWO storage class that points to block storage
     csNamespace: ${PROJECT_CPFS_OPS}
   EOF

   Important:

   Configuring metadata storage

   If your cluster does not use the recommended storage classes, you must configure metadata storage for Cloud Pak for Data by specifying a storage class for the zenCoreMetadbStorageClass setting. The storage class must be ReadWriteOnce (RWO) and point to block storage, such as:

   • ocs-storagecluster-ceph-rbd on Red Hat OpenShift Container Storage
   • portworx-metastoredb-sc on Portworx

   ---

Verifying the installation

When you create the Ibmcpd custom resource, the IBM Cloud Pak for Data platform operator processes the contents of the custom resource and starts up the microservices that comprise Cloud Pak for Data, including the Cloud Pak for Data control plane.

The Cloud Pak for Data control plane is defined by the ZenSerivce lite-cr custom resource.

To check the status of the installation:

1. Change to the project where you installed Cloud Pak for Data. For example:

   oc project ${PROJECT_CPD_INSTANCE}

2. Get the status of the installation:
   1. Run the following command to determine whether the ibmcpd-cr has been created:

      oc get Ibmcpd ibmcpd-cr -o jsonpath="{.status.controlPlaneStatus}{'\n'}"

      Output	What to do next
      InProgress	Wait a few minutes. Then, run the command again.
      Completed	Go to step 2b.
      Failed	Go to step 2b.

   2. Run the following command to determine whether the control plane is ready:

      oc get ZenService lite-cr -o jsonpath="{.status.zenStatus}{'\n'}"

      Output	What to do next
      InProgress	Wait a few minutes. Then, run the command again. It can take up to 90 minutes for the command to return Completed. If the command still has not returned Completed after 90 minutes, contact IBM Software Support.
      Completed	The Cloud Pak for Data control plane is ready when the command returns Completed. Go to step 3.
      Failed	Contact IBM Software Support.

3. Get the URL of the Cloud Pak for Data web client:

   oc get ZenService lite-cr -o jsonpath="{.status.url}{'\n'}"

   The URL has the following format:

   https://cpd-namespace.apps.OCP-default-domain

4. Get the initial password for the admin user:

   oc extract secret/admin-user-details --keys=initial_admin_password --to=-

   Important: Save the output of this command so that you can log in to the web client. It is strongly recommended that you change the initial password the first time that you log in to the web client.

Choosing an upgrade plan for the Cloud Pak for Data control plane

Controlled upgrade (recommended)

It is strongly recommend that you pin the installation to a specific version to prevent unexpected upgrades of the Cloud Pak for Data control plane.

To use the controlled upgrade plan:

1. Update the ZenService custom resource.

   For a list of operand versions supported by the Zen operator, see Cloud Pak for Data operator and operand versions.

   For example, to pin the installation at 4.4.4, run the following command:

   oc patch ZenService lite-cr \
   --namespace ${PROJECT_CPD_INSTANCE} \
   --type=merge \
   --patch '{"spec": {"version":"4.4.4"}}'

Automatic upgrade

By default, the Cloud Pak for Data control plane will be automatically upgraded when you install a newer version of IBM Cloud Pak foundational services on the cluster.

Restriction: Allowing automatic updates is not recommended in production environments where predictability and stability are important. This option is recommended only for short-term installations, such as proof-of-concept deployments.

If you want to continue using the automatic upgrade plan, no additional action is required.

Note: For this release of Cloud Pak for Data, the default version of the control plane is 4.4.4. If you install the minimum required version of IBM Cloud Pak foundational services (Version 3.18.0), the control plane will remain at 4.4.4. If you install a later release of IBM Cloud Pak foundational services, you might see a later version of the control plane on your cluster.

What to do next

Ensure that you complete the appropriate Post-installation tasks for your environment.