Upgrading

You can upgrade Event Processing and the IBM Operator for Apache Flink to the latest 1.0.x version by using the operator channel v1.0. Upgrade your Event Processing installation as follows.

Note:

If your operator upgrades are set to automatic, minor version upgrades are completed automatically. This means that the Event Processing and IBM Operator for Apache Flink operators will be upgraded to 1.0.x when they are available in the catalog, and your Event Processing and Flink instances are then also automatically upgraded.
You will experience some downtime during the Event Processing upgrade while the pods for the relevant components are recycled.
If your Flink instance is an application cluster for deploying advanced flows in production environments, the automatic upgrade cannot update the custom Flink image built by extending the IBM-provided Flink image. In this case, after the successful upgrade of the operator, complete steps 1a, 1b, 1e, and 2c in Build and deploy a Flink SQL runner to make use of the upgraded Flink image.

Prerequisites

If you installed as part of IBM Cloud Pak for Integration, ensure that you have followed the upgrade steps for IBM Cloud Pak for Integration before you upgrade Event Processing.
To upgrade without data loss, your Event Processing and IBM Operator for Apache Flink instances must have persistent storage enabled. If you upgrade instances which use ephemeral storage, all data will be lost.
If you installed the Event Processing operator to manage instances of Event Processing in any namespace (one per namespace), then you might need to control when each of these instances is upgraded to the latest version. You can control the updates by pausing the reconciliation of the instance configuration as described in the following sections.

Note: Pausing the reconciliation of the instance configuration is not available for IBM Operator for Apache Flink instances.

Scheduling the upgrade of an instance

If your operator manages more than one instance of Event Processing, you can control when each instance is upgraded by pausing the reconciliation of the configuration settings for each instance, running the upgrade, and then unpausing the reconciliation when ready to proceed with the upgrade for a selected instance.

Pausing reconciliation by using the CLI

To apply the annotation to an EventProcessing instance, run the following command:

kubectl annotate EventProcessing <instance-name> -n <instance-namespace> events.ibm.com/pause='true'

Follow the steps to upgrade by using the oc CLI, the OpenShift web console or the kubectl CLI.

Unpausing reconciliation by using the CLI

To unpause the reconciliation and continue with the upgrade of an Event Processing instance, run the following command:

kubectl annotate EventProcessing <instance-name> -n <instance-namespace> events.ibm.com/pause-

When the annotation is removed, the configuration of your instance is updated, and the upgrade to the latest version of Event Processing completes.

Pausing reconciliation by using the OpenShift web console

Log in to the OpenShift Container Platform web console using your login credentials.
Expand Operators in the navigation on the left, and click Installed Operators.
From the Project list, select the namespace (project) the instance is installed in.
Locate the operator that manages your Event Processing instance in the namespace. It is called Event Processing in the Name column. Click the Event Processing link in the row.
Select the instance you want to pause and click the YAML tab.

In the YAML for the custom resource, add events.ibm.com/pause: 'true' to the metadata.annotations field as follows:

apiVersion: events.ibm.com/v1beta1
kind: EventProcessing
metadata:
name: <instance-name>
namespace: <instance-namespace>
annotations:
   events.ibm.com/pause: 'true'

Follow the steps to upgrade by using the oc CLI or the OpenShift web console.

Unpausing reconciliation by using the OpenShift web console

To unpause the reconciliation and continue with the upgrade of an Event Processing instance, remove the annotation from the EventProcessing instance. When the annotation is removed, the configuration of your instance is updated, and the upgrade to the latest version of Event Processing completes.

Upgrading on the OpenShift Container Platform

Upgrade your Event Processing and Flink instances running on the OpenShift Container Platform by using the CLI or web console as follows.

Upgrading by using the OpenShift CLI

If you are using the OpenShift command-line interface (CLI), the oc command, complete the steps in the following sections to upgrade your Event Processing and Flink installations.

For Event Processing:

Ensure the required Event Processing Operator Upgrade Channel is available:

oc get packagemanifest ibm-eventprocessing -o=jsonpath='{.status.channels[*].name}'

Change the subscription to move to the required update channel, where vX.Y is the required update channel (for example, v1.1):
```
oc patch subscription -n <namespace> ibm-eventprocessing --patch '{"spec":{"channel":"vX.Y"}}' --type=merge
```

For Flink:

Ensure the required IBM Operator for Apache Flink Operator Upgrade Channel is available:

oc get packagemanifest ibm-eventautomation-flink -o=jsonpath='{.status.channels[*].name}'

If your Flink instance uses persistent storage, backup the Flink instance.
Change the subscription to move to the required update channel, where vX.Y is the required update channel (for example, v1.1):
```
oc patch subscription -n <namespace> ibm-eventautomation-flink --patch '{"spec":{"channel":"vX.Y"}}' --type=merge
```
If your Flink instance uses persistent storage, restore the backed up Flink instance.
If your Flink instance is an application cluster for deploying advanced flows in production environments, complete steps 1a, 1b, 1e, and 2c in Build and deploy a Flink SQL runner to make use of the upgraded Flink image.

All Event Processing and Flink pods that need to be updated as part of the upgrade will be rolled.

Upgrading by using the OpenShift web console

If you are using the OpenShift Container Platform web console, complete the steps in the following sections to upgrade your Event Processing installation.

For Event Processing:

Log in to the OpenShift Container Platform web console using your login credentials.
Expand Operators in the navigation on the left, and click Installed Operators.
From the Project list, select the namespace (project) the instance is installed in.
Locate the operator that manages your Event Processing instance in the namespace. It is called Event Processing in the Name column. Click the Event Processing in the row.
Click the Subscription tab to display the Subscription details for the Event Processing operator.
Select the version number in the Update channel section (for example, v1.0). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
Select the required channel, for example v1.1, and click the Save button on the Change Subscription update channel dialog.

All Event Processing pods that need to be updated as part of the upgrade will be rolled.

For Flink:

Log in to the OpenShift Container Platform web console using your login credentials.
If your Flink instance uses persistent storage, backup the Flink instance.
Expand Operators in the navigation on the left, and click Installed Operators.
From the Project list, select the namespace (project) the instance is installed in.
Locate the operator that manages your Flink instance in the namespace. It is called IBM Operator for Apache Flink in the Name column. Click the IBM Operator for Apache Flink in the row.
Click the Subscription tab to display the Subscription details for the Event Processing operator.
Select the version number in the Update channel section (for example, v1.0). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
Select the required channel, for example v1.1, and click the Save button on the Change Subscription update channel dialog.
If your Flink instance uses persistent storage, restore the backed up Flink instance.
If your Flink instance is an application cluster for deploying advanced flows in production environments, complete steps 1a, 1b, 1e, and 2c in Build and deploy a Flink SQL runner to make use of the upgraded Flink image.

All Flink pods that need to be updated as part of the upgrade will be rolled.

Upgrading on other Kubernetes platforms by using Helm

If you are running Event Processing on Kubernetes platforms that support the Red Hat Universal Base Images (UBI) containers, upgrade Event Processing by using the Helm chart as follows:

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
If your Flink instance uses persistent storage, backup the Flink instance.

Add the IBM Helm repository if you have not already done so:

helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm

Update the Helm repository:
```
helm repo update ibm-helm
```
Ensure you are running in the namespace containing the Helm release of the IBM Operator for Apache Flink CRDs.

Upgrade the Helm release by running the command:

helm upgrade <flink_crd_release_name> ibm-helm/ibm-eventautomation-flink-operator-crd

Upgrade the Helm release of IBM Operator for Apache Flink. Switch to the right namespace if your CRD Helm release is in a different namespace to your operator and then run:
```
helm upgrade <flink_release_name> ibm-helm/ibm-eventautomation-flink-operator
```
Identify the namespace where the Event Processing installation is located and the Helm release managing the CRDs by looking at the annotations on the CRDs:
```
kubectl get crd eventprocessings.events.ibm.com -o jsonpath='{.metadata.annotations}'
```
The following is an example output showing CRDs managed by Helm release ep-crds in namespace my-ep:
```
{"meta.helm.sh/release-name": "ep-crds", "meta.helm.sh/release-namespace": "ep"}
```
Ensure you are using the namespace where your Event Processing CRD Helm release is located (see previous step):
```
kubectl config set-context --current --namespace=<namespace>
```
Run the following command to upgrade the Helm release that manages your Event Processing CRDs:
```
helm upgrade <crd_release_name> ibm-helm/ibm-ep-operator-crd
```
Run the following command to upgrade the Helm release of your operator installation. Switch to the right namespace if your CRD Helm release is in a different namespace to your operator.
```
helm upgrade <ep_release_name> ibm-helm/ibm-ep-operator <install_flags>
```

Where:

<crd_release_name> is the Helm release name of the Helm installation that manages the Event Processing CRDs.
<ep_release_name> is the Helm release name of the Helm installation of the operator.
<install_flags> are any optional installation property settings, such as --set watchAnyNamespace=true.

Note: After you completed the previous steps, you can restore your Flink instances as follows:

If your Flink instance uses persistent storage, restore the backed up Flink instance.
If your Flink instance is an application cluster for deploying advanced flows in production environments, complete steps 1a, 1b, 1e, and 2c in Build and deploy a Flink SQL runner to make use of the upgraded Flink image.

Verifying the upgrade

After the upgrade, verify the status of the Event Processing and Flink instances, by using the CLI or the UI.