Upgrading the Cloud Pak for Data control plane

To obtain fixes, security updates, and new functionality, you must upgrade to the latest version of the Cloud Pak for Data control plane. If a previous refresh of Cloud Pak for Data Version 4.0 already installed on the cluster, a project administrator can upgrade the control plane to the latest version.

For a complete list of Cloud Pak for Data Version 4.0 refreshes, see Operator and operand versions.

Permissions you need for this task: You must be an administrator of the OpenShift® project (Kubernetes namespace) where Cloud Pak for Data is installed (identified by the ${PROJECT_CPD_INSTANCE} environment variable).
When you need to complete this task: When you upgrade to Refresh 9 of Version 4.0, you must complete this task to upgrade each instance of the Cloud Pak for Data control plane on your cluster. For example, if you have two instances of Cloud Pak for Data Version 4.0.x on your cluster, you must complete this task twice.
Additionally, if you install a newer version IBM Cloud Pak® foundational services after you upgrade to Refresh 9 of Version 4.0, you can optionally upgrade the control plane.
Information you need to confirm before you start this task: Before you upgrade the control plane, confirm the name of the project where Cloud Pak for Data is installed.
Information you need to complete this task: You cannot change the storage that is associated with this installation. If you try to change the storage, the upgrade will fail.

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 upgrade preparation tasks for your environment. Specifically, verify that a cluster administrator completed the following tasks:

IBM Cloud Pak foundational services Version 3.18.0 or later is installed. For details, see Upgrading IBM Cloud Pak foundational services.
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 before upgrading from Version 4.0.x.
The catalog source for the IBM Cloud Pak for Data platform operator is updated. For details, see Updating catalog sources.
The IBM Cloud Pak for Data platform operator operator is upgraded. For details, see Upgrading operator subscriptions.

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

Procedure

To upgrade the Cloud Pak for Data control plane:

Log in to the Red Hat® OpenShift Container Platform as a user with sufficient permissions to complete the task:
```
oc login ${OCP_URL}
```

Check the current version of the control plane:

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

If the version is below 4.4.4, update the version entry in the ZenService custom resource:

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

When you update the custom resource, the Zen operator upgrades the Cloud Pak for Data control plane.

Verifying the upgrade

The Zen operator continually monitors the contents of the ZenService custom resource and updates the microservices that comprise the Cloud Pak for Data control plane as needed. The control plane is upgraded when the ZenService status is Completed.

To check the status of the upgrade:

Change to the project where Cloud Pak for Data is installed. For example:
```
oc project ${PROJECT_CPD_INSTANCE}
```
Get the status of the ZenService:
```
oc get ZenService lite-cr -o jsonpath="{.status.zenStatus}{'\n'}"
```
The control plane is ready when the command returns Completed.

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

For Refresh 9 of Version 4.0, the minimum required version of the control plane is 4.4.4, which requires IBM Cloud Pak foundational services Version 3.18.0 or later.

If you install a later version of IBM Cloud Pak foundational services, you might see a later version of the control plane on your cluster depending on the upgrade plan that you choose.

Review the following guidance to determine which upgrade plan is appropriate for your environment:

Controlled upgrade (recommended)

It is strongly recommended that you pin the installation to a specific version to prevent unexpected upgrades of the Cloud Pak for Data control plane. When the installation is pinned, you must explicitly upgrade the Cloud Pak for Data control plane.

To use the controlled upgrade plan:

Determine whether the installation is pinned at a specific version.
The installation is pinned if the spec section of the ZenService custom resource includes a version entry. To check whether the installation is pinned at a specific version, run:
```
oc get ZenService lite-cr \
-n ${PROJECT_CPD_INSTANCE} \
-o jsonpath="{.spec.version}{'\n'}"
```
- If the installation is pinned, the response includes the version at which the installation is pinned.
- If the installation is not pinned, the response is empty.
If the installation is not pinned at a specific version and you want to move to the controlled upgrade plan, run the following command to add the version entry and pin the installation at 4.4.4:
```
oc patch ZenService lite-cr \
--namespace ${PROJECT_CPD_INSTANCE} \
--type=merge \
--patch '{"spec": {"version":"4.4.4"}}'
```

Automatic upgrade

If the ZenService custom resource does not include a version entry, the Cloud Pak for Data control plane is 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.

To use the automatic upgrade plan:

Determine whether the installation is pinned at a specific version.
The installation is pinned if the spec section of the ZenService custom resource includes a version entry. To check whether the installation is pinned at a specific version, run:
```
oc get ZenService lite-cr \
-n ${PROJECT_CPD_INSTANCE} \
-o jsonpath="{.spec.version}{'\n'}"
```
- If the installation is pinned, the response includes the version at which the installation is pinned.
- If the installation is not pinned, the response is empty.
If the installation is pinned at a specific version and you want to move to the automatic upgrade plan, run the following command to remove the version entry:
```
oc patch ZenService lite-cr \
--namespace ${PROJECT_CPD_INSTANCE} \
--type=json \
--patch '[{ "op": "remove", "path": "/spec/version" }]'
```