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
    Identified by the ${PROJECT_CPFS_OPS} environment variable.

    Typically the ibm-common-services project.

    The IBM Cloud Pak for Data platform operator project
    Identified by the ${PROJECT_CPD_OPS} environment variable.

    This project can be a separate project, such as cpd-operators or the same project as the IBM Cloud Pak foundational services project.

    The project where you plan to install Cloud Pak for Data
    Identified by the ${PROJECT_CPD_INSTANCE} environment variable.
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
    • IBM Spectrum® Scale Container Native: ibm-spectrum-scale-sc
    • 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

Best practice: You can run the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Best practice: Setting up install variables.

Ensure that you run the environment variable script before you run the commands in this task.

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

For example: