2019.4

Upgrading

Upgrade your installation to the latest version of Event Streams as follows.

Upgrade paths

Complete the steps in the following sections to upgrade your Event Streams version to 2019.4.x. The following upgrade paths are available:

You can upgrade to Event Streams version 2019.4.6 directly from versions 2019.4.5, 2019.4.4, 2019.4.3, 2019.4.2, 2019.4.1 or 2019.2.1.
You can upgrade to Event Streams version 2019.4.5 directly from versions 2019.4.4, 2019.4.3, 2019.4.2, 2019.4.1 or 2019.2.1.
You can upgrade to Event Streams version 2019.4.4 directly from versions 2019.4.3, 2019.4.2, 2019.4.1 or 2019.2.1.
You can upgrade to Event Streams version 2019.4.3 directly from versions 2019.4.2, 2019.4.1 or 2019.2.1.
You can upgrade to Event Streams version 2019.4.2 directly from version 2019.4.1 or 2019.2.1.
You can upgrade to Event Streams version 2019.4.1 directly from version 2019.2.1.
If you have an earlier version than 2019.2.1, you must first upgrade your Event Streams version to 2019.2.1, before upgrading to 2019.4.x.

Prerequisites

Ensure you have IBM Cloud Private version 3.2.1. If you are using the OpenShift Container Platform, ensure you have version 3.11 or later. See the prerequisites for supported container environments.
The minimum resource requirements have changed. Ensure you have the required resources available.
If upgrading to version 2019.4.2, 2019.4.3, 2019.4.4, 2019.4.5, or 2019.4.6, download the fix pack from Fix Central.
If upgrading to version 2019.4.1, download the package from IBM Passport Advantage by searching for “Event Streams” and 2019.4.1. Download the images related to the part numbers for your platform.
Make the packages available to your IBM Cloud Private instance as described in steps 2 to 4 of the download task.
If you have encryption between pods enabled, then ensure you disable it before starting the upgrade. After the upgrade completes successfully, you can enable the encryption again.
If upgrading from version 2019.2.1, follow the post-upgrade tasks after the upgrade completes.

Important: Event Streams only supports upgrading to a newer chart version. Do not select an earlier chart version when upgrading. If you want to revert to an earlier version of Event Streams, see the instructions for rolling back.

Upgrading on IBM Cloud Private

You can upgrade your Event Streams version by using the IBM Cloud Private UI or CLI.

Using the UI

Log in to your IBM Cloud Private cluster management console as an administrator. For more information, see the IBM Cloud Private documentation.
Click Workloads > Helm Releases from the navigation menu.
Locate the release name of your installation in the Name column, and click More options > Upgrade in the corresponding row.
Select the chart version to upgrade to from the Version drop-down list.
Ensure you have Using previous configured values set to Reuse Values.
Note: Do not change any of the settings in the Parameters section. You can modify configuration settings after upgrade, for example, enable encryption between pods.
Click Upgrade.
The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting.
If upgrading from version 2019.2.1, follow the post-upgrade tasks after the upgrade completes.

Using the CLI

Ensure you have the latest Helm chart version available on your local file system.
- You can retrieve the charts from the UI.
- Alternatively, if you downloaded the archive from IBM Passport Advantage or fix pack from FixCentral, the chart file is included in the archive or fix pack. Extract the PPA archive or fix pack, and locate the chart file in the /charts directory, for example: ibm-eventstreams-prod-1.4.0.tgz
Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
cloudctl login -a https://<cluster-address>:<cluster-router-https-port>

Important: You must have the Team Administrator or Cluster Administrator role to upgrade the chart.
Run the helm upgrade command as follows, referencing the Helm chart you want to upgrade to:
helm upgrade <release-name> <latest-chart-version>

For example, to upgrade by using a chart downloaded in the PPA archive or fix pack:
helm upgrade eventstreams1 /Users/admin/upgrade/ibm-eventstreams-prod-1.4.0.tgz

Note: Do not set any parameter value during the upgrade, for example, helm upgrade --set <parameter>=<value> <release_name> <charts.tgz> --tls. You can modify configuration settings after upgrade, for example, enable encryption between pods.

The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting.
If upgrading from version 2019.2.1, follow the post-upgrade tasks after the upgrade completes.

Upgrading on OpenShift Container Platform

If you are using the OpenShift Container Platform, you can only upgrade by using the command line.

Ensure you have the latest Helm chart version available on your local file system.

Note: The Event Streams chart name no longer includes rhel in the name. For example, the chart name is now ibm-eventstreams-prod (not ibm-eventstreams-rhel-prod).
- You can retrieve the charts from the UI.
- Alternatively, if you downloaded the archive from IBM Passport Advantage, the chart file is included in the archive. Extract the PPA archive, and locate the chart file in the /charts directory, for example: ibm-eventstreams-prod-1.4.0.tgz
Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
cloudctl login -a https://<cluster-address>:<cluster-router-https-port>

Important: You must have the Team Administrator or Cluster Administrator role to upgrade the chart.
Delete the Kafka StatefulSet as follows:

kubectl delete statefulset <release-name>-ibm-es-kafka-sts --cascade=false -n <namespace>

The cascade=false flag deletes the StatefulSet, but leaves the Kafka pods running.
Run the helm upgrade command as follows, referencing the Helm chart you want to upgrade to:
helm upgrade <release-name> <latest-chart-version>

For example, to upgrade by using a chart downloaded in the PPA archive:
helm upgrade eventstreams1 /Users/admin/upgrade/ibm-eventstreams-prod-1.4.0.tgz

Note: Do not set any parameter value during the upgrade, for example, helm upgrade --set <parameter>=<value> <release_name> <charts.tgz> --tls. You can modify configuration settings after upgrade, for example, enable encryption between pods.

The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting.
If upgrading from version 2019.2.1, follow the post-upgrade tasks after the upgrade completes.

Post-upgrade tasks

Additional steps required after upgrading are described in the following sections.

Set up access management

If you have IBM Cloud Private teams set up for access management, you must associate the teams again with your Event Streams instance after successfully completing the upgrade.

To use your upgraded Event Streams instance with existing IBM Cloud Private teams, re-apply the security resources to any teams you have defined as follows:

Check the teams you use:
1. Log in to your IBM Cloud Private cluster management console as an administrator. For more information, see the IBM Cloud Private documentation.
2. From the navigation menu, click Manage > Identity & Access > Teams. Look for the teams you use with your Event Streams instance.
Ensure you have installed the latest version of the Event Streams CLI.
Run the following command for each team that references your instance of Event Streams:
cloudctl es iam-add-release-to-team --namespace <namespace> --helm-release <helm-release> --team <team-name>

Update browser certificates

If you trusted certificates in your browser for using the Event Streams UI, you might not be able to access the UI after upgrading.

To resolve this issue, you must delete previous certificates and trust new ones. Check the browser help for instructions, the process for deleting and accepting certificates varies depending on the type of browser you have.

Update cluster certificates

Upgrading your Event Streams version also updates your internal certificates automatically. You can manually change your internal certificates later. Internal certificates can only be self-generated certificates, they cannot be provided.

You can also update your external certificates manually after an upgrade, for example, if you want to change from using self-generated certificates to provided certificates.

Note: If you update your cluster certificates you might also need to update the certificates of any connecting clients.

Enable encryption between pods

As mentioned in the prerequisites, encryption between pods must be disabled before upgrading Event Streams.

If you had pod to pod encryption enabled before upgrading, enable it again.

Switch to routes

If you are using the OpenShift Container Platform and have upgraded to Event Streams version 2019.4.1, you can switch to using OpenShift routes. Routes allow access to your cluster through a host name instead of the host IP address and node port combination.

OpenShift Container Platform routes are the standard way of accessing applications inside an OpenShift cluster, and provide the benefit of being pre-determined and understandable.

Tip: If you installed Event Streams version 2019.4.1 without upgrading from a previous version, you will already be using routes.

Important: Switching to routes will alter the Event Streams certificates, and will therefore require redistributing the certificates to all your clients and updating their connection settings to use the new bootstrap route for their bootstrap server. This means the switch over will cause your clients to disconnect, resulting in downtime.

To switch to routes:

Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
cloudctl login -a https://<cluster-address>:<cluster-router-https-port>

Important: You must have the Team Administrator or Cluster Administrator role to upgrade the chart.
Ensure you have routes available in your container platform by running the following command:

kubectl api-resources | grep routes

If the command returns routes route.openshift.io true Route, then you have OpenShift routes available.
Ensure you have the latest Helm chart version available on your local file system.
Run the following command to configure your Event Streams installation to use routes:

helm upgrade --reuse-values --set global.security.externalCertificateLabel=upgraded --set proxy.upgradeToRoutes=true <release-name> <latest-chart-version>
After the upgrade completes successfully, and all pods are ready, run the following command to update your installation with the new routes.

NAMESPACE=<namespace>; kubectl patch $(kubectl get cm -n $NAMESPACE -l component=proxy -o name) -n $NAMESPACE -p "{\"data\":{\"externalListeners\":\"\",\"revision\":\"$(date +%s999999999)\"}}";
The Event Streams UI address changes to a route, which can be retrieved by using the following command:

echo https://$(kubectl get route -n <namespace> <release-name>-ibm-es-ui-route -o 'jsonpath={.spec.host}')
The Event Streams schema registry uses the REST API. Configuring Event Streams to use routes changes this endpoint value to a route, so ensure you update the clients that use schemas to use the route name. To retrieve the REST route name, run the following command:

echo https://$(kubectl get route -n <namespace> <releasename>-ibm-es-rest-route -o 'jsonpath={.spec.host}')
Update the connection settings for your clients that interact with Event Streams. This will require your clients to disconnect, and connect again after the changes are made, resulting in downtime.