Table of contents

Installing Cloud Pak for Data

When you install IBM® Cloud Pak for Data, you update 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. Then, you create a custom resource to install Cloud Pak for Data in that project.

Permissions you need for this task
You must be either:
  • A cluster administrator
  • An administrator of the following projects:
    • The IBM Cloud Pak foundational services project (ibm-common-services)
    • The IBM Cloud Pak for Data platform operator project (cpd-operators or ibm-common-services)
    • The project where you plan to install Cloud Pak for Data
When you need to complete this task
You must complete this task each time you want to install an instance of Cloud Pak for Data on your cluster.
Information you need to complete this task
  • The Cloud Pak for Data control plane needs only the restricted security context constraint (SCC).
  • The Cloud Pak for Data control plane uses the following storage classes. If you don't use these storage classes on your cluster, ensure that you have a storage class with an equivalent definition:
    • OpenShift® Container Storage: ocs-storagecluster-cephfs
    • NFS: managed-nfs-storage
    • Portworx: portworx-shared-gp3
    • IBM Cloud File Storage: ibmc-file-gold-gid or ibm-file-custom-gold-gid
Important: The steps in this task assume that you are installing the latest software images.

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. 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.
  3. The cluster is configured to pull the software images. For details, see Configuring your cluster to pull Cloud Pak for Data images.
  4. The Cloud Pak for Data operator subscription and the IBM Namespace Scope 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 OpenShift_URL:port
  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:
    • 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: cpd-instance        # Replace with the project where you will install Cloud Pak for Data
      spec:
        requests: []
      EOF
    • Update the IBM NamespaceScope Operator in the Cloud Pak for Data operators project to watch the project where you plan to install Cloud Pak for Data.

      Edit the namespaceMembers list to add the project where you plan to install Cloud Pak for Data. For example, if you plan to install Cloud Pak for Data in the cpd-instance project, add that project to the list:

      cat <<EOF |oc apply -f -
      apiVersion: operator.ibm.com/v1
      kind: NamespaceScope
      metadata:
        name: cpd-operators
        namespace: cpd-operators        # (Default) Replace with the Cloud Pak for Data platform operator project name 
      spec:
        csvInjector:                    # This setting is required for some services. Do not delete this line if you specified it when you created operator subscriptions. 
          enable: true                  # This setting is required for some services. Do not delete this line if you specified it when you created operator subscriptions. 
        namespaceMembers:
        - cpd-operators                 # (Default) Replace with the Cloud Pak for Data platform operator project name
        - cpd-instance                  # Replace with the project where you will install Cloud Pak for Data
      EOF
  3. Create a custom resource to install Cloud Pak for Data. Follow the appropriate guidance for your environment:
    • 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: cpd-instance                # Replace with the project where you will install Cloud Pak for Data
      spec:
        license:
          accept: true
          license: Enterprise|Standard         # Specify the Cloud Pak for Data license you purchased
        storageVendor: ocs
      EOF
    • 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: cpd-instance                # Replace with the project where you will install Cloud Pak for Data
      spec:
        license:
          accept: true
          license: Enterprise|Standard         # Specify the Cloud Pak for Data license you purchased
        storageVendor: portworx
      EOF
    • 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: cpd-instance                             # Replace with the project where you will install Cloud Pak for Data
      spec:
        license:
          accept: true
          license: Enterprise|Standard                      # Specify the Cloud Pak for Data license you purchased
        storageClass: RWX-storage-class                     # Replace with the name of a RWX storage class, such as managed-nfs-storage
      EOF
    • 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.

      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: cpd-instance                             # Replace with the project where you will install Cloud Pak for Data
      spec:
        license:
          accept: true
          license: Enterprise|Standard                      # Specify the Cloud Pak for Data license you purchased
        storageClass: RWX-storage-class                     # Replace with the name of a RWX storage class
        zenCoreMetadbStorageClass: RWO-storage-class        # (Recommended) Replace with the name of a RWO storage class
      EOF
      Best practice:
      Configuring metadata storage
      The zenCoreMetadbStorageClass setting is optional but strongly recommended for reliability. Specify the ReadWriteOnce (RWO) storage class to use for Cloud Pak for Data metadata storage. Ideally, this storage class points to block storage, such as:
      • ocs-storagecluster-ceph-rbd on Red Hat OpenShift Container Storage
      • portworx-metastoredb-sc on Portworx

      If you do not specify this setting, the storage class that you specified for the storageClass value is used. If you do not want to specify this setting, remove or comment out this line.

Verifying the installation

When you create the custom resource, the IBM Cloud Pak for Data platform operator processes the contents of the custom resource and starts up the microservices that comprise the Cloud Pak for Data control plane, including the zenservice, which is defined by the lite-cr custom resource definition.

To check the status of the installation:

  1. Change to the project where you installed Cloud Pak for Data. For example:
    oc project cpd-instance
  2. Get the status of the control plane:
    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 lite-cr 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

Automatic upgrade (recommended)
By default, the Cloud Pak for Data control plane will be automatically upgraded when you install a newer version of the IBM Cloud Pak for Data platform operator on the cluster.

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

Manual upgrade
If you want to manually upgrade the Cloud Pak for Data control plane when you install a newer version of the IBM Cloud Pak for Data platform operator, you can optionally pin the installation to a specific version.

To change to the manual 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.1.0, run the following command:

    oc patch ZenService lite-cr \
    --namespace <cpd-instance> \
    --type merge \
    --patch '{"spec": {"version":"4.1.0"}'