Upgrading

Upgrade your Event Endpoint Management installation as follows. The Event Endpoint Management operator handles the upgrade of your Event Manager and Event Gateway instances if they are on the same cluster. To upgrade a stand-alone Event Gateway, see upgrading a stand-alone Event Gateway.

Review the upgrade procedure and decide the right steps to take for your deployment based on your platform and the version level you are upgrading to.

Upgrade paths

You can upgrade Event Endpoint Management to the latest 11.3.x version directly from any earlier 11.3.x or any 11.2.x version by using the latest 11.3.x operator. The upgrade procedure depends on whether you are upgrading to a major, minor, or patch level version, and what your catalog source is.

If you are upgrading from Event Endpoint Management version 11.1.x, you must first upgrade your installation to 11.2.x and then follow these instructions to upgrade to 11.3.x.

On OpenShift, you can upgrade to the latest version by using operator channel v11.3. Review the general upgrade prerequisites before following the instructions to upgrade on OpenShift.
On other Kubernetes platforms, you must update the Helm repository for any level version update (any digit update: major, minor, or patch), and then upgrade by using the Helm chart. Review the general upgrade prerequisites before following the instructions to upgrade on other Kubernetes platforms.

Prerequisites

Ensure you have a supported version of the OpenShift Container Platform installed. For supported versions, see the support matrix.
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 Endpoint Management.
To upgrade successfully, your Ensure that both your Event Gateway and Event Manager instances are from the same version of Event Endpoint Management, or that the Event Gateway is from an earlier version. instance must have persistent storage enabled. If you upgrade an Event Manager instance with ephemeral storage, all data will be lost.
Always upgrade your Event Manager instance before upgrading your Event Gateway instance.

Important: You will experience some downtime during the Event Endpoint Management upgrade while the pods for the relevant components are recycled.

Ensuring Kafka certificates include their hostname

In Event Endpoint Management 11.3.0 and later, hostname verification is enabled on the connection between your Kafka cluster and the Event Gateway. This requires that the hostname presented in the Kafka certificates matches the URL that the Event Gateway uses to connect to Kafka.

Before upgrading to Event Endpoint Management 11.3.x from any 11.2.x version, ensure that the certificates have been updated on your Kafka cluster to provide the hostname.

Without the hostname, the connection between Kafka and the Event Gateway will be broken, which will cause Kafka clients that are connecting through the Event Gateway to fail.

To check whether the certificates on your Kafka cluster include the hostname, contact your certificate provider.

Upgrading on the OpenShift Container Platform

Find out how to upgrade your deployment on an OpenShift Container Platform.

Planning your upgrade

Complete the following steps to plan your upgrade on OpenShift.

Determine which Operator Lifecycle Manager (OLM) channel is used by your existing Subscription. You can check the channel you are subscribed to in the web console (see Update channel section), or by using the CLI as follows (this is the subscription created during installation):
1. Run the following command to check your subscription details:
```
oc get subscription
```
2. Check the CHANNEL column for the channel you are subscribed to, for example, v11.2 in the following snippet:
```
NAME                                      PACKAGE                          SOURCE                                     CHANNEL
ibm-eventendpointmanagement               ibm-eventendpointmanagement      ibm-eventendpointmanagement-catalog        v11.2
```
If your existing Subscription uses a channel earlier than v11.2, you must first upgrade your installation to 11.2.x before you can upgrade to 11.3.x.
If your existing Subscription uses the v11.2 channel, change it to 11.3 to upgrade. Complete the following steps:
1. Ensure the catalog source for new version is available.
2. Change your Subscription to the v11.2 channel by using the CLI or the web console. The channel change will upgrade your operator, and then the operator will automatically upgrade your Event Manager instance, and if applicable, your Event Gateway instance as well.
3. Follow steps in post-upgrade tasks to make sure you are using current license IDs for the new channel.
If your existing Subscription is already on the v11.3 channel, your upgrade is a change to the patch level (third digit) only. Make the catalog source for your new version available to upgrade to the latest level. If you installed by using the IBM Operator Catalog with the latest label, new versions are automatically available. The operator will upgrade your Event Endpoint Management instance automatically.

Making new catalog source available

Before you can upgrade to the latest version, make the catalog source for the version available in your cluster. This depends on how you set up version control for your deployment.

Latest versions: If your catalog source is the IBM Operator Catalog, latest versions are always available when published, and you do not have to make new catalog sources available.
Specific versions: If you used the CASE bundle to install catalog source for a specific previous version, you must download and use a new CASE bundle for the version you want to upgrade to.
- If you used the CASE bundle for an online install, apply the new catalog source to update the CatalogSource.
- If you used the CASE bundle for an offline install that uses a private registry, follow the instructions in installing offline to remirror images and update the CatalogSource.
- In both cases, wait for the status.installedCSV field in the Subscription to update. It eventually reflects the latest version available in the new CatalogSource image for the currently selected channel in the Subscription:
  - In the OpenShift Container Platform web console, the current version of the operator is displayed under Installed Operators.
  - If you are using the CLI, check the status of the Subscription custom resource, the status.installedCSV field shows the current operator version.

The change to a new Channel, if needed, would be a later step.

Upgrading Subscription 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 Endpoint Management installation.

Ensure the required Event Endpoint Management Operator Upgrade Channel is available:

oc get packagemanifest ibm-eventendpointmanagement -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, v11.3):
```
oc patch subscription -n <namespace> ibm-eventendpointmanagement --patch '{"spec":{"channel":"vX.Y"}}' --type=merge
```

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

Upgrading Subscription by using the OpenShift web console

If you are using the web console, complete the steps in the following sections to upgrade your Event Endpoint Management installation.

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 Manager instance in the namespace. It is called Event Endpoint Management in the Name column. Click the Event Endpoint Management link in the row.
Click the Subscription tab to display the Subscription details for the Event Endpoint Management operator.
Select the version number link in the Update channel section (for example, v11.2). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
Select the required channel, for example v11.3, and click the Save button on the Change Subscription update channel dialog.

All Event Endpoint Management 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 Endpoint Management on Kubernetes platforms that support the Red Hat Universal Base Images (UBI) containers, you can upgrade Event Endpoint Management by using the Helm chart.

Planning your upgrade

Complete the following steps to plan your upgrade on other Kubernetes platforms.

Determine the chart version for your existing deployment:

Change to the namespace where your Event Manager instance is installed:
```
kubectl config set-context --current --namespace=<namespace>
```
Run the following command to check what version is installed:
```
helm list
```

Check the version installed in the CHART column, for example, <chart-name>-11.0.5 in the following snippet:

NAME                  NAMESPACE  REVISION  UPDATED                                 STATUS   CHART                        APP VERSION    
ibm-eem-operator      eem        1         2023-11-22 12:27:03.6018574 +0000 UTC   deployed ibm-eem-operator-11.0.5      7133459-483976d  

Check the latest chart version that you can upgrade to:
1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
2. Add the IBM Helm repository:
```
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
```
3. Update the Helm repository:
```
helm repo update ibm-helm
```
4. Check the version of the chart you will be upgrading to is the intended version:
```
helm show chart ibm-helm/ibm-eem-operator
```
  Check the version: value in the output, for example: version: 11.3.2
If the chart version for your existing deployment is earlier than 11.2.x, you must first upgrade your installation to 11.2.x, including any post-upgrade tasks. Return to these instructions to complete your upgrade to the 11.3.x version.
If your existing installation is in an offline environment, you must repeat the steps in the offline installation instructions to Download the CASE bundle and mirror the images before upgrading. Then complete the helm upgrade instructions in the following section.
If the chart version for your existing deployment is 11.3.x, your upgrade involves a change in a minor version. Complete the following steps to upgrade to the latest version:
1. Before upgrading, update your instance configuration to ensure compatibility across the version change.
2. Follow the steps in upgrading by using Helm to update your Custom Resource Definitions (CRDs) and operator charts to the latest version. The operator will then automatically upgrade your Event Manager instance, and if applicable, your Event Gateway instance as well.
3. Follow steps in post-upgrade tasks to make sure you are using current license IDs for the new channel.
If the chart version for your existing deployment is 11.3.x, your upgrade is a change in patch level only. Follow the steps in upgrading by using Helm to update your Custom Resource Definitions (CRDs) and operator charts to the latest version. The operator will then upgrade your Event Manager instance automatically.

Upgrading by using Helm

You can upgrade your Event Endpoint Management on other Kubernetes platforms by using Helm.

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Identify the namespace where the installation is located and the Helm release managing the CRDs by looking at the annotations on the CRDs:
```
kubectl get crd eventendpointmanagements.events.ibm.com -o jsonpath='{.metadata.annotations}'
```
The following is an example output showing CRDs managed by Helm release eem-crds in namespace my-eem:
```
{"meta.helm.sh/release-name": "eem-crds", "meta.helm.sh/release-namespace": "eem"}
```
Ensure you are using the namespace where your Event Endpoint Management CRD Helm release is located (see previous step):
```
kubectl config set-context --current --namespace=<namespace>
```

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
```
Run the following command to upgrade the Helm release that manages your Event Endpoint Management CRDs (as identified in step 2):
```
helm upgrade <crd_release_name> ibm-helm/ibm-eem-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 <eem_release_name> ibm-helm/ibm-eem-operator <install_flags>
```

In the earlier commands:

<crd_release_name> is the Helm release name of the Helm installation that manages the Event Endpoint Management CRDs.
<eem_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

Post-upgrade tasks

Verifying the upgrade

After the upgrade, verify the status of the Event Endpoint Management, by using the CLI or the UI.

Updating license IDs

After upgrading to Event Endpoint Management 11.3.x from version 11.2.x, you must update the license ID value in the spec.license.license field of your custom resources depending on the program that you purchased. You cannot modify your custom resources until you provide a valid license ID.