Upgrading Event Manager and operator-managed Event Gateways

Upgrade your Event Endpoint Management installation as follows. The Event Endpoint Management operator handles the upgrade of your Event Manager, and all operator-managed Event Gateway instances that are on the same cluster. To upgrade a Docker or Kubernetes Event Gateway, see Upgrading Docker and Kubernetes Event Gateways.

Review the upgrade procedure and decide the right steps to take for your deployment based on your platform, current version, and target version.

Planning your upgrade

Upgrade paths

You can upgrade Event Endpoint Management to the latest 11.6.x version directly from any earlier 11.6.x or 11.5.x version by using the latest 11.6.x operator.

If you are upgrading from Event Endpoint Management version 11.4.x or earlier, you must first upgrade your installation to 11.5.x, and then return to these instructions to upgrade to 11.6.x.

On OpenShift, you can upgrade to the latest version by using operator channel v11.6.

On other Kubernetes platforms, you must update the Helm repository and then upgrade Event Endpoint Management by using the Helm chart.

Prerequisites

Ensure that 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 followed the upgrade steps for IBM Cloud Pak for Integration before you upgrade Event Endpoint Management.
To keep your data, your Event Manager instance must have persistent storage enabled. If you upgrade an Event Manager instance with ephemeral storage, then all data is lost.
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.
Upgrade Docker or Kubernetes Deployment Event Gateway instances after you upgrade your Event Manager.
Rolling back an upgrade is not supported. If your upgrade fails, then reinstall Event Endpoint Management and restore your data from your backup.

Important: The upgrade process requires some downtime as Event Endpoint Management and Event Gateway pods are restarted.

Upgrading on the OpenShift Container Platform

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

Pre-upgrade checks and preparation

The pre-upgrade checks and preparation ensure that your Event Endpoint Management installation is ready to upgrade. These steps do not commit you to completing the upgrade, so you can do them before your upgrade window.

Determine which Operator Lifecycle Manager (OLM) channel is used by your existing Subscription. You can check the channel that you are subscribed to in the OpenShift web console, or by using the CLI as follows:

a. Run the following command to check your subscription details:
```
oc -n <namespace> get subscription
```
<namespace> is the Event Endpoint Management operator namespace.

b. Check the CHANNEL column for the channel you are subscribed to, for example, v11.5 in the following snippet:
```
NAME                                      PACKAGE                          SOURCE                                     CHANNEL
ibm-eventendpointmanagement               ibm-eventendpointmanagement      ibm-eventendpointmanagement-catalog        v11.5
```
This is the subscription that is created during installation.

If your existing Subscription uses a channel earlier than v11.5, you must first upgrade your installation to 11.5.x before you can upgrade to 11.6.x.
Back up your Event Manager and Event Gateway instances.
If you are managing your catalog sources with a CASE bundle, then download the CASE bundle for your target version.

a. Download and extract the latest Event Endpoint Management CASE version:
```
oc ibm-pak get ibm-eventendpointmanagement 
```
Note: You can specify an earlier version of the CASE by using --version <case version>.

b. Generate mirror manifests:
```
oc ibm-pak generate mirror-manifests ibm-eventendpointmanagement icr.io
```

If you installed by using the IBM Operator Catalog with the latest label, then the latest Event Endpoint Management release for your update channel is always available and updates are applied automatically. Proceed directly to verify your upgrade.

Upgrading by using the OpenShift CLI

If you are using the OpenShift command-line interface (CLI), complete the steps in the following sections to upgrade your Event Endpoint Management installation. Set <namespace> to the namespace of your Event Endpoint Management operator.

Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).
If you are managing your catalog sources with a CASE bundle, then apply the CASE bundle:
```
oc -n <namespace> apply -f ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case version>/catalog-sources.yaml
```
If your existing subscription is already on the v11.6 channel, then the upgrade to 11.6.x is applied automatically. Skip the remaining steps and proceed to verify your upgrade.

If you used the CASE bundle for an offline installation that uses a private registry, follow the instructions in installing offline to remirror images and update the CatalogSource.

Verify that the target version Event Endpoint Management Operator Upgrade Channel is available:

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

If you are upgrading from 11.5.x, then update the spec.license.license field in the custom resources of your Event Manager and Event Gateway instances to the license ID for 11.6.0 and later. The instances will not upgrade until the license ID is updated. Set <namespace> to the namespace of your Event Endpoint Management instance.

a. Get the names of your Event Manager and Event Gateway instances:

oc -n <namespace> get eventendpointmanagements.events.ibm.com

oc -n <namespace> get eventgateways.events.ibm.com

b. For each instance, update the license:

oc -n <namespace> patch eventendpointmanagements.events.ibm.com <manager instance name> --patch '{"spec":{"license":{"license":"<license ID>"}}}' --type=merge

oc -n <namespace> patch eventgateway.events.ibm.com <gateway instance name> --patch '{"spec":{"license":{"license":"<license ID>"}}}' --type=merge

Check the status of the Subscription custom resource to confirm that your Event Endpoint Management operator was updated to your target version.
```
oc -n <namespace> get -o yaml subscription
```
<namespace> is the Event Endpoint Management operator namespace. The status.installedCSV field in the output shows the current operator version.

All Event Endpoint Management pods that are updated as part of the upgrade are restarted.

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 project (namespace) the instance is installed in.
Locate the operator that manages your Event Manager instance in the project. 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.5). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
Select the required channel, for example v11.6, and click Save on the Change Subscription update channel dialog.
If you are upgrading from 11.5.x, then update the spec.license.license field in the custom resources of your Event Manager and Event Gateway instances to the license ID for 11.6.0 and later. The instances will not upgrade until the license ID is updated.
Monitor your Event Endpoint Management operator and instance in the web console to confirm that the upgrade completes.

All Event Endpoint Management pods that are updated as part of the upgrade are restarted.

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.

Pre-upgrade checks and preparation on other Kubernetes platforms

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

Ensure that you have a recent backup of your Event Manager and Event Gateway instances.

Identify the name, namespace, and chart of your Event Endpoint Management operators:

a. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

b. Run the following command:

helm list --all-namespaces

If you have several Helm releases installed, you can filter for eem, for example:

helm list --all-namespaces | grep eem

c. Take note of the NAME, NAMESPACE, and CHART values for ibm-eem-operator and ibm-eem-operator-crd:

NAME     NAMESPACE	REVISION	UPDATED                                	STATUS  	CHART                                   	APP VERSION     
eem-crd  eemns   	1       	2024-12-04 02:10:55.343886423 -0800 PST	deployed	ibm-eem-operator-crd-11.6.0             	26955880-704cca1
eem-op   eemns  	1         	2024-12-04 02:11:08.814270035 -0800 PST	deployed	ibm-eem-operator-11.6.0                 	26955880-704cca1

Check the latest chart version that you can upgrade to:

a. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

b. Add the IBM Helm repository:
```
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
```
c. Update the Helm repository:
```
helm repo update ibm-helm
```
d. Confirm the version of the chart that you are upgrading to:
```
helm show chart ibm-helm/ibm-eem-operator
```
Check the version: value in the output, for example: version: 11.6.1

If the chart version for your existing deployment is earlier than 11.5.x, you must first upgrade your installation to 11.5.x, including any post-upgrade tasks. Return to these instructions to complete your upgrade to the 11.6.x version.

If the chart version for your existing deployment is 11.5.x, then proceed to upgrading by using Helm.

If the chart version for your existing deployment is 11.6.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.
Upgrade the Helm release that manages your Event Endpoint Management Custom Resource Definitions (CRDs):
```
helm -n <EEM CRD namespace> upgrade <EEM CRD name> ibm-helm/ibm-eem-operator-crd
```
Replace <EEM CRD namespace> and <EEM CRD name> with the NAMESPACE and NAME values that you identified in the pre-upgrade checks.
Upgrade the Helm release of your operator installation.
```
helm -n <EEM operator namespace> upgrade <EEM operator name> ibm-helm/ibm-eem-operator 
```
Replace <EEM operator namespace> and <EEM operator name> with the NAMESPACE and NAME values that you identified in the pre-upgrade checks.

a. Retrieve the names of your Event Manager and Event Gateway instances:

kubectl -n <namespace> get eventendpointmanagements.events.ibm.com

kubectl -n <namespace> get eventgateways.events.ibm.com

b. For each instance, update the license:

kubectl -n <namespace> patch eventendpointmanagements.events.ibm.com <manager instance name> --patch '{"spec":{"license":{"license":"<license ID>"}}}' --type=merge

kubectl -n <namespace> patch eventgateways.events.ibm.com <gateway instance name> --patch '{"spec":{"license":{"license":"<license ID>"}}}' --type=merge

Verify that your upgrade completed:
```
helm list -n <namespace>
```
Confirm that the CHART column shows your target version for your Event Endpoint Management CRDs and operator.

Post-upgrade tasks

Verifying the upgrade

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