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

Upgrading to 2018.3.1

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

Use the CLI to upgrade Event Streams. You cannot use the UI to upgrade to Event Streams 2018.3.1.

  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. Ensure it is available to your IBM Cloud Private instance.
  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 install the chart.
  3. Optional: Due to a known defect in the Kafka health check, the upgrade process creates a short outage period whilst the upgrade takes place where messages cannot be sent to topics. If you want to avoid an outage, follow these steps to upgrade the health check before upgrading Event Streams:
    1. Run the following command:
      kubectl edit sts <release-name>-ibm-es-kafka-sts
      This command opens the stateful set configuration in the default editor (for example, the vi editor).
    2. There are four image: tags in the statefulset definition, search for the tag containing the word healthcheck.
      An example of the string for a Community Edition installation is as follows:
      image: ibmcom/eventstreams-healthcheck-ce:2018-09-18-11.23.15-1a8f35a71d2b2edc91bf1eccf664d821e04f8420

      If you installed from an image downloaded from IBM Passport Advantage, your IBM Cloud Private Docker registry name would be displayed instead of ibmcom, and the string would not have ce included.

    3. Update the tag with the unique identifier after ibmcom/.
      Note: The ibmcom/ can also be docker/ or a different <repository-name>/.
      • For Community Edition installations, the unique identifier is as follows:
         eventstreams-healthcheck-ce-icp-linux-amd64:2018-11-21-16.21.30-9947d87
      • For Event Streams downloaded from IBM Passport Advantage, the unique identifier is as follows:
         eventstreams-healthcheck-icp-linux-amd64:2018-11-21-16.21.30-9947d87


        The following example shows the changing of the tag for a Community Edition installation after ibmcom/:
        From

        ibmcom/eventstreams-healthcheck-ce:2018-09-18-11.23.15-1a8f35a71d2b2edc91bf1eccf664d821e04f8420

        To

        ibmcom/eventstreams-healthcheck-ce-icp-linux-amd64:2018-11-21-16.21.30-9947d87
    4. Save your changes and exit the editor.
  4. Optional: The helm resource requirements changed for release 2018.3.1. If you modified the default settings for your existing installation, ensure you have the ZooKeeper memory limit set to at least 1 GB, the ZooKeeper request memory set to at least 750 MB, and the Elastic Search memory limit set to at least 4 GB.
    To set the values, run the helm upgrade command as follows:
    • Set the ZooKeeper memory limit and request memory to at least 1 GB and 750 MB, respectively:
      helm upgrade --reuse-values --set zookeeper.resources.limits.memory=1Gi --set zookeeper.resources.requests.memory=750Mi <release-name> <chart-file>.tgz
      For example:
      helm upgrade --reuse-values --set zookeeper.resources.limits.memory=1Gi --set zookeeper.resources.requests.memory=750Mi event-streams-1 ibm-eventstreams-dev-1.0.0.tgz
    • Set the Elastic Search memory limit to at least 4 GB:
      helm upgrade --reuse-values --set messageIndexing.resources.limits.memory=4Gi <release-name> <chart-file>.tgz
      For example:
      helm upgrade --reuse-values --set messageIndexing.resources.limits.memory=4Gi event-streams-1 ibm-eventstreams-dev-1.0.0.tgz
  5. 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
  6. 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 <release-name> <latest-chart-version> --set global.arch=amd64
    For example:
    helm upgrade -f config-settings.yaml eventstreams1 /Users/admin/upgrade/ibm-eventstreams-dev-1.1.0.tgz --set global.arch=amd64

The upgrade process begins and restarts your pods. During the process, the UI shows pods as unavailable and restarting. When the upgrade is complete, refresh your browser, and continue to use the Event Streams UI.

Depending on your set-up, consider completing the post-upgrade tasks.

Post-upgrade tasks

Depending on your set-up, you might need to complete additional steps as described in the following sections.

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>

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.