Upgrade your Event Endpoint Management installation as follows. The Event Endpoint Management operator handles the upgrade of your Event Manager, and all Event Gateway instances that 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, current version, and target version.
Upgrade paths
You can upgrade Event Endpoint Management to the latest 11.4.x version directly from any earlier 11.4.x or 11.3.x version by using the latest 11.4.x operator.
If you are upgrading from Event Endpoint Management version 11.2.x or earlier, you must first upgrade your installation to 11.3.x, and then follow these instructions to upgrade to 11.4.1.
-
On OpenShift, you can upgrade to the latest version by using operator channel v11.4. Review the general upgrade prerequisites before you follow 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 you follow the instructions to upgrade on other Kubernetes platforms.
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 upgrade successfully, your Event Manager instance must have persistent storage enabled. If you upgrade an Event Manager instance with ephemeral storage, 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 stand-alone Event Gateway instances after you upgrade your Event Manager.
Important: If you have Event Gateway instances from Event Endpoint Management version 11.2.0 and earlier, review the additional upgrade steps.
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.
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 that you are subscribed to in the web console (see Update channel section), or by using the CLI as follows:
a. Run the following command to check your subscription details:
oc get subscription
b. Check the
CHANNEL
column for the channel you are subscribed to, for example, v11.3 in the following snippet:NAME PACKAGE SOURCE CHANNEL ibm-eventendpointmanagement ibm-eventendpointmanagement ibm-eventendpointmanagement-catalog v11.3
This is the subscription created during installation.
If your existing Subscription uses a channel earlier than v11.3, you must first upgrade your installation to 11.3.x before you can upgrade to 11.4.x.
If your existing Subscription is already on the v11.4 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, make the catalog source for the target version available in your cluster. The procedure depends on how you set up version control for your deployment:
-
Latest versions: If your catalog source is the IBM Operator Catalog, the 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 the catalog source for a previous version, you must download and use a new CASE bundle for your target version.
- If you used the CASE bundle for an online installation, apply the new catalog source to update the
CatalogSource
. - 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
. - In both cases, wait for the
status.installedCSV
field in theSubscription
to update. It eventually reflects the latest version available in the newCatalogSource
image for the currently selected channel in theSubscription
:- 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, thestatus.installedCSV
field shows the current operator version.
- In the OpenShift Container Platform web console, the current version of the operator is displayed under
- If you used the CASE bundle for an online installation, apply the new catalog source to update the
Upgrading Subscription 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.
- Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the
oc
CLI (oc login
). -
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.4
):oc patch subscription -n <namespace> ibm-eventendpointmanagement --patch '{"spec":{"channel":"vX.Y"}}' --type=merge
- If you are upgrading from 11.3.x, then update the
spec.license.license
ID in the custom resources of your Event Manager and Event Gateway instances to the license ID for 11.4.0 and later. The instances will not upgrade until the license ID is updated.
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.3). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
- Select the required channel, for example v11.4, and click Save on the Change Subscription update channel dialog.
- If you are upgrading from 11.3.x, then update the
spec.license.license
ID in the custom resources of your Event Manager and Event Gateway instances to the license ID for 11.4.0 and later. The instances will not upgrade until the license ID is updated.
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.
Planning your upgrade
Complete the following steps to plan your upgrade on other Kubernetes platforms.
-
Determine the chart version for your existing deployment:
a. Change to the namespace where your Event Manager instance is installed:
kubectl config set-context --current --namespace=<namespace>
b. Run the following command to check what version is installed:
helm list
c. Check the version installed in the
CHART
column, for example,<chart-name>-11.3.2
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.3.2 7133459-483976d
-
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.4.1
If the chart version for your existing deployment is earlier than 11.3.x, you must first upgrade your installation to 11.3.x, including any post-upgrade tasks. Return to these instructions to complete your upgrade to the 11.4.1 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 you upgrade.
If the chart version for your existing deployment is 11.3.x, then proceed to helm upgrade.
If the chart version for your existing deployment is 11.4.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 that is managing the CRDs:
kubectl get crd eventendpointmanagements.events.ibm.com -o jsonpath='{.metadata.annotations}'
Example output that shows CRDs managed by Helm release
eem-crds
in namespacemy-eem
:{"meta.helm.sh/release-name": "eem-crds", "meta.helm.sh/release-namespace": "eem"}
- Set your current namespace to the namespace that you identified in step 2.
kubectl config set-context --current --namespace=<namespace>
-
Add the IBM Helm repository:
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
-
Update the Helm repository:
helm repo update ibm-helm
-
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
-
Upgrade the Helm release of your operator installation.
helm -n <ibm-eem-operator namespace> upgrade <eem_release_name> ibm-helm/ibm-eem-operator <install_flags>
- If you are upgrading from 11.3.x, then update the
spec.license.license
ID in the custom resources of your Event Manager and Event Gateway instances to the license ID for 11.4.0 and later. The instances will not upgrade until the license ID is updated.
Where:
<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
<ibm-eem-operator namespace>
is the namespace where your Event Endpoint Management is installed.
Post-upgrade tasks
Verifying the upgrade
After the upgrade, verify the status of the Event Endpoint Management, by using the CLI or the UI.
Enable Event Gateway instances from version 11.2.0 and earlier to work with 11.4.0 and later
By default, Event Endpoint Management 11.4.0 and later versions do not allow any Event Gateway from Event Endpoint Management version 11.2.0 and earlier to register with the Event Manager and publish topics to them.
You can configure any such Event Gateway instances to continue to work with Event Manager instances from Event Endpoint Management 11.4.x as follows.
Note: Support for using an Event Gateway from Event Endpoint Management version 11.2.0 and earlier with 11.4.0 and later deployments will be removed in a future release.
-
Determine your current Event Gateway version by obtaining the
sha256
digests for the deployed Event Gateway container images. The steps to do this depend on whether your Event Gateway is operator-managed or a stand-alone deployment. -
Check if your Event Gateway images match any of the following digests:
- 11.2.0:
sha256:3a0651f5cf79bdb29afffa7328db796c06d27fe62748a86701f4bdbf501cf570
- 11.1.5:
sha256:168a2017976c6b59ff32a5966994946abb880ae8ddb3ee8e79dac2aab8f1f504
- 11.1.4:
sha256:6369e5416cbb55e861eafae7657bbccddf5b360a67e9626e922f2636a94a5be0
- 11.1.3:
sha256:83ae7964b1b85e690b50784889355b28f2d5181f9d793bf9f5fb004a112cbd4f
- 11.1.2:
sha256:fa0e266f1974467297469392b22175111541933619b2419d68ee7f4dd387d321
- 11.1.1:
sha256:2e4c371259b599b01bacf29ac96bc1cc90764c3a33cb202fb127472dffddc6c7
- 11.1.0:
sha256:8fa25e9f2774f20181e8fe8108d58aa1f473108ead013271a0a75dc0e3e87de6
- 11.0.5:
sha256:cf303004c78434741ec3bd492c4df84b7647091a8f1e13e44c919fa8aad8092c
- 11.0.4:
sha256:cade81de88d1567e04c319e2b6dd5115e7b1042e772253eadb728e543aef8794
- 11.0.3:
sha256:4e4a05f15639ed76e134a8d75f925fca68c86bb639c45da024bf8f26fb8d40f9
- 11.0.2:
sha256:ccaea352f4453bbc162692016af78b1b72dcdc466fdd477a356a34bdf198a12f
- 11.0.1:
sha256:96597a18b0bd50a71d1d341fb2d9acdda970d006fa35ceadfbe4d2396fec3eed
- 11.0.0:
sha256:cfdf937b0c1e20debb4f13bb63027ee8cb0840f96850095e3ceb6141f490a590
- 11.2.0:
-
If your gateway matches one of the digests listed in the previous step, it will not work with your Event Manager after upgrading unless you complete one of the following tasks:
- Upgrade your Event Gateway instance to the version from the Event Endpoint Management you are upgrading to.
- Apply the following configuration to the
EventEndpointManagement
custom resource that defines your Event Manager instance:
spec: manager: template: pod: spec: containers: - name: manager env: - name: ALLOW_PRE_V11.2.0_GATEWAYS value: "true"
Important: The
ALLOW_PRE_V11.2.0_GATEWAYS
configuration option will be removed in a future Event Endpoint Management release. To ensure compatibility, it is recommended that both your Event Gateway and Event Manager instances are from the same version of Event Endpoint Management.
Operator-managed Event Gateway instances
The sha256
digest is visible in the Deployment
of any Event Gateway, which has been created and managed by the Operator.
For example, where the Deployment
is named <GATEWAY INSTANCE NAME>-ibm-egw-gateway
, where <GATEWAY INSTANCE NAME>
is the name of your EventGateway
custom resource, the sha256
value is a part of the image
value:
...
ports:
- name: egw
containerPort: 8092
protocol: TCP
imagePullPolicy: IfNotPresent
volumeMounts:
- name: egw-certs
readOnly: true
mountPath: /certs/eem
- name: config
readOnly: true
mountPath: /config
- name: manager-cache
mountPath: /tmp
- name: manager-audit
mountPath: /var/log/audit
terminationMessagePolicy: File
image: 'cp.icr.io/cp/ibm-eventendpointmanagement/egw@sha256:3a0651f5cf79bdb29afffa7328db796c06d27fe62748a86701f4bdbf501cf570'
serviceAccount: <GATEWAY INSTANCE NAME>-ibm-egw-sa
...
Stand-alone Event Gateway instances
If you have a stand-alone Event Gateway instance, run the following command to list the digests of the running images on the host system:
docker image inspect $(docker ps -a --filter label="description=gateway microservice" --format "{{.Image}}" | sort) --format="{{.RepoTags}}:{{.Id}}"
The following shows an example result:
[cp.icr.io/cp/ibm-eventendpointmanagement/egw:11.0.0]:sha256:b328f6c844117e1c59ce0e6406c7691b8169d72dd73665bbe602835b8e06388c
Review the returned sha256
string or tag that is associated with the image to determine the version of your Event Gateway instance.