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 Event Gateway, see Upgrading Docker 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.

Upgrade paths

You can upgrade Event Endpoint Management to 11.5.0 directly from any 11.4.x by using the latest 11.5.0 operator.

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

• On OpenShift, you can upgrade to the latest version by using operator channel v11.5. 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 Docker or Kubernetes Deployment Event Gateway instances after you upgrade your Event Manager.

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.

1. 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:

    Copy Copy   oc get subscription
   

   b. Check the CHANNEL column for the channel you are subscribed to, for example, v11.4 in the following snippet:

    Copy Copy   NAME                                      PACKAGE                          SOURCE                                     CHANNEL
      ibm-eventendpointmanagement               ibm-eventendpointmanagement      ibm-eventendpointmanagement-catalog        v11.4
   

   This is the subscription created during installation.

If your existing Subscription uses a channel earlier than v11.4, you must first upgrade your installation to 11.4.x before you can upgrade to 11.5.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 created the catalog sources 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 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.

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.

1. Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).

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

    Copy Copyoc get packagemanifest ibm-eventendpointmanagement -o=jsonpath='{.status.channels[*].name}'
   

3. Change the subscription to move to the required update channel, where vX.Y is the required update channel (for example, v11.4):

    Copy Copyoc patch subscription -n <namespace> ibm-eventendpointmanagement --patch '{"spec":{"channel":"vX.Y"}}' --type=merge
   

4. If you are upgrading from 11.4.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.5.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.

1. Log in to the OpenShift Container Platform web console using your login credentials.

2. Expand Operators in the navigation on the left, and click Installed Operators.

   

3. From the Project list, select the project (namespace) the instance is installed in.
4. 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.
5. Click the Subscription tab to display the Subscription details for the Event Endpoint Management operator.
6. Select the version number link in the Update channel section (for example, v11.4). The Change Subscription update channel dialog is displayed, showing the channels that are available to upgrade to.
7. Select the required channel, for example v11.4, and click Save on the Change Subscription update channel dialog.
8. If you are upgrading from 11.4.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.5.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.

1. Determine the chart version for your existing deployment:

   a. Change to the namespace where your Event Manager instance is installed:

    Copy Copy   kubectl config set-context --current --namespace=<namespace>
   

   b. Run the following command to check what version is installed:

    Copy Copy   helm list
   

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

    Copy Copy   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.4.2      7133459-483976d  
   

2. 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:

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

   c. Update the Helm repository:

    Copy Copy   helm repo update ibm-helm
   

   d. Confirm the version of the chart that you are upgrading to:

    Copy Copy   helm show chart ibm-helm/ibm-eem-operator
   

   Check the version: value in the output, for example: version: 11.5.0

If the chart version for your existing deployment is earlier than 11.4.x, you must first upgrade your installation to 11.4.x, including any post-upgrade tasks. Return to these instructions to complete your upgrade to the 11.5.0 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.4.x, then proceed to helm upgrade.

If the chart version for your existing deployment is 11.5.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.

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

2. Identify the namespace where the installation is located and the Helm release that is managing the CRDs:

    Copy Copykubectl get crd eventendpointmanagements.events.ibm.com -o jsonpath='{.metadata.annotations}'
   

   Example output that shows CRDs managed by Helm release eem-crds in namespace my-eem:

    Copy Copy{"meta.helm.sh/release-name": "eem-crds", "meta.helm.sh/release-namespace": "eem"}
   

3. Set your current namespace to the namespace that you identified in step 2.

    Copy Copykubectl config set-context --current --namespace=<namespace>
   

4. Add the IBM Helm repository:

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

5. Update the Helm repository:

    Copy Copyhelm repo update ibm-helm
   

6. Upgrade the Helm release that manages your Event Endpoint Management CRDs (as identified in step 2):

    Copy Copyhelm upgrade <crd_release_name> ibm-helm/ibm-eem-operator-crd
   

7. Upgrade the Helm release of your operator installation.

    Copy Copyhelm -n <ibm-eem-operator namespace> upgrade <eem_release_name> ibm-helm/ibm-eem-operator <install_flags>
   

8. If you are upgrading from 11.4.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.5.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.

Update the service endpoints to define the server endpoint

Note: Only required when you configure ingress on Kubernetes platforms other than OpenShift.

In Event Endpoint Management 11.5.0 and later, any existing EventEndpointManagement custom resources require a server endpoint in array spec.manager.endpoints[]. If that is not present, the custom resource shows an error in the status field. Patch your instances by adding a new element called server to spec.manager.endpoints[]. The hostname that you specify must start with eem..

For example, using the kubectl CLI, the following command adds the element to an existing instance eem-manager-instance in namespace my-namespace:

 Copy Copykubectl patch EventEndpointManagement eem-manager-instance -n my-namespace --type json -p='[{"op": "add", "path": "/spec/manager/endpoints/0", "value": {"name": "server", "host": "eem.manager.mycluster.example.com"} }]'

If you are using an alternative system to manage your custom resources (such as ArgoCD or Ansible), then update your EventEndpointManagement definitions accordingly.

Important: In Event Endpoint Management 11.5.0 and later, the admin service endpoint no longer includes a type option to set the network exposure and availability of the Admin API (disabled, internal, or external). The service endpoint is always available externally, making the API available from outside the cluster.

Update user roles

In Event Endpoint Management 11.5.0 and later, the author role no longer has the permissions to manage Event Gateways. You must assign the admin role to any user who requires permissions to deploy or manage Event Gateways.