Attention: This version of Event Streams has reached End of Support. For more information about supported versions, see the support matrix.

Upgrading to 2019.1.1

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

You can upgrade to Event Streams version 2019.1.1 from version 2018.3.1. If you have version 2018.3.0, you must first upgrade your Event Streams version to 2018.3.1, and then upgrade IBM Cloud Private to version 3.1.1 or 3.1.2, before following these steps to upgrade to Event Streams version 2019.1.1.

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.

Prerequisites

  • Ensure you have IBM Cloud Private version 3.1.1 or later installed.
  • If you are upgrading Event Streams (not Community Edition), download the package for the version you want to upgrade to, and make it available to your IBM Cloud Private instance.

Using the UI

  1. Log in to your IBM Cloud Private cluster management console from a supported web browser by using the URL https://<Cluster Master Host>:<Cluster Master API Port>. The master host and port for your cluster are set during the installation of IBM Cloud Private. For more information, see the IBM Cloud Private documentation.
  2. Click Workloads > Helm Releases from the navigation menu.
  3. Locate the release name of your installation in the Name column, and click More options icon More options > Upgrade in the corresponding row.
  4. Select the chart version to upgrade to from the Version drop-down list.
  5. Ensure you set Using previous configured values to Reuse Values.
  6. Click Upgrade.

The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting.

After the upgrade completes, you must perform the post-upgrade tasks.

Using the CLI

  1. 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, 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.2.0.tgz.
  2. Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
    cloudctl login -a https://<Cluster Master Host>:<Cluster Master API Port>
    The master host and port for your cluster are set during the installation of IBM Cloud Private.
    Important: You must have the Cluster Administrator role to upgrade the chart.
  3. Save the configuration settings of your existing installation to a file as follows:
    helm get values <release-name> > <saved-configuration-settings>.yaml
    For example:
    helm get values eventstreams1 > config-settings.yaml
  4. Run the helm upgrade command as follows, referencing the file where you saved your configuration settings and the helm chart you want to upgrade to:
    helm upgrade -f <saved-configuration-settings>.yaml --set global.image.repository="<cluster_CA_domain>:8500" <release-name> <latest-chart-version>
    For example, to upgrade the Community Edition:
    helm upgrade -f config-settings.yaml --set global.image.repository="ibmcom" eventstreams1 /Users/admin/upgrade/ibm-eventstreams-dev-1.2.0.tgz
    For example, to upgrade by using a chart downloaded in the PPA archive:
    helm upgrade -f config-settings.yaml --set global.image.repository="mycluster.icp:8500" eventstreams1 /Users/admin/upgrade/ibm-eventstreams-prod-1.2.0.tgz

The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting.

After the upgrade completes, you must perform the post-upgrade tasks.

Post-upgrade tasks

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

Retrieve new port number for UI

Important: The upgrade process changes the port number for the UI. You must refresh the IBM Cloud Private UI and determine the URL for the Event Streams UI again to obtain the new port number. You can then log in to the Event Streams UI.

Update inter-broker protocol version

Event Streams 2019.1.1 includes an update to Apache Kafka version 2.1.1.

Apache Kafka 2.1 includes changes to the internal schema used to store consumer offsets. It also includes changes to the inter-broker protocol. These changes are not enabled by default, so you need manually enable the changes by running the following command.

Warning: It is not possible to downgrade to previous versions after you enable the changes. Do not perform this final upgrade step until you have verified that the upgrade to Event Streams 2019.1.1 has been successful.

  1. Ensure you have the Event Streams CLI installed.
  2. Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
    cloudctl login -a https://<Cluster Master Host>:<Cluster Master API Port>
    The master host and port for your cluster are set during the installation of IBM Cloud Private.
  3. Run the following command:
    cloudctl es cluster-config --static-config-all-brokers --config log.message.format.version=2.1 --config inter.broker.protocol.version=2.1

Note: This command causes each of the brokers to restart. However, the Kafka cluster remains available during the restarts.

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:

  1. Check the teams you use:
    1. Log in to your IBM Cloud Private cluster management console from a supported web browser by using the URL https://<Cluster Master Host>:<Cluster Master API Port>. The master host and port for your cluster are set during the installation of IBM Cloud Private. For more information, see the IBM Cloud Private documentation.
    2. Enter an IBM Cloud Private administrator user name and password.
    3. From the navigation menu, click Manage > Identity & Access > Teams. Look for the teams you use with your Event Streams instance.
  2. Ensure you have installed the latest version of the Event Streams CLI.
  3. 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 UI bookmarks

If you have any bookmarks to the UI, you need to update them because the port number for the Event Streams UI changes as part of the upgrade to version 2019.1.1.

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.