Rolling Upgrade Overview

IBM Streams 4.2.0 introduced support for rolling upgrades of Streams domains and instances. With a rolling upgrade, a running domain or instance continues to run as it is upgraded to a newer version. Rolling upgrades can help reduce downtime when introducing a new Streams version into a running environment. Releases prior to 4.2.0 supported standard upgrades only. With a standard upgrade, the domain must be stopped and then restarted at the newer version in order to upgrade. Rolling upgrades can be done to new versions as well as to fix packs or interim fixes. Also note Streams 4.2.0 is the first release from which a rolling upgrade can be performed.

Upgrading a Domain

To perform a rolling upgrade of a domain, the new version of Streams must be installed using the same root path as the version the domain is currently running. The root path is the install path without the added version directory.  For example, if the domain is running 4.2.0 from /opt/ibm/InfoSphere_Streams/4.2.0 and you want to upgrade to the fix pack, you need to install the fix pack to /opt/ibm/InfoSphere_Streams as well.

The new Streams version should be installed to all domain resources where the main installation package for the existing version is installed.  Doing this ensures all product files, including development support files for Streams Studio, Streams for Excel, and the toolkits, are updated to the new version.  The new code is automatically provisioned to the other resources in the domain as part of the rolling upgrade process.  Installing the new version to multiple resources also has the advantage of providing additional resources from which the provisioning can be performed. It also has the advantage of having back-up resources for provisioning new domain resources in the event a different resource with the new installation becomes unavailable.

The rolling upgrade of the domain must be done with Streams sourced at the newer version. For example using the same scenario as above,  you would run:  source /opt/ibm/InfoSphere_Streams/ when upgrading from 4.2.0 to  The rolling upgrade can be initiated from Domain Manager or by running the streamtool upgradedomain command.

The following things happen as part of the rolling upgrade:

  • The¬† new code is provisioned to all remaining resources in the domain which did not have the new code installed.
  • The domain controller service is restarted on each resource at the newer version.
  • All remaining domain services are restarted at the new version.

While this is happening, running instances continue to run at the previous version and running jobs within those instances continue to run.¬† You can use the streamtool lsdomain command to verify the domain is running the newer version after the rolling upgrade completes.¬† streamtool getdomainstate –long is another verification option with additional details. It shows all versions installed within the same root path on each of the domain resources and it uses an asterisk to identify which version the controller service on each resource is running.

Upgrading Instances

Performing a rolling upgrade of an instance is done independently of the domain upgrade.  Similar to the domain upgrade, the rolling upgrade of an instance must be done with Streams sourced at the newer version.  Upgrading an instance also requires the domain to be running with a version at or newer than the version to which the instance is being upgraded.  The instance services continue to run while the instance is being upgraded; however currently, running jobs must be stopped before doing the rolling upgrade.

A rolling upgrade of an instance can be initiated from the Streams console or by running the streamtool upgradeinstance command.¬† With the streamtool command, you can specify to upgrade: a single instance, a subset of instances,¬† or all instances within the domain.¬† You can use the streamtool lsinstance –long command to verify an instance is running the newer version after the rolling upgrade completes.

Note: There is no rolling downgrade support to switch a domain or instance back to an earlier version; however, if this is necessary, a standard downgrade could be used by stopping the domain or instance and then restarting it with the earlier version.  This assumes the earlier version is still installed within the same root path as the current version.

Multi-version Support

IBM Streams 4.2.0 also introduced multi-version support.  This means a domain can be running at one Streams version while its instances are running one or more different versions.  Versions before 4.2.0 required the domain and its instances all to run the same version of Streams code.  As mentioned above, instance upgrades are done independently of the domain upgrade and instances upgrades can be done independently of each other and staged over time. In some cases, it can be advantageous to have the domain running one version while instances are running one or more different versions. For example, you might have applications that require an earlier Streams version or you might choose to run a new version on a test instance while running an earlier version on production instances.

With multi-version support, the domain must be running with a version at or newer than the newest version of any of its instances.  Also, 4.2.0 is the earliest version an instance can be running in this environment.  Similar to the rolling upgrade support, all versions to run within a domain need to be installed within the same root path.

Whenever an instance is started, the default behavior is to start it using the same version as the domain is running. In some cases, this might not be the desired behavior.  For example, using the scenario mentioned above with one test instance and multiple production instances, the production instances should always be restarted at the earlier version.  Two new configuration properties added in 4.2.0 can be used to override the default behavior:

  • instance.startAsVersion¬† This instance property specifies which Streams version is used when the instance is started.¬† Note: this value can also be overridden by specifying the —version option on the streamtool startinstance command.
  • domain.determineInstanceStartAsVersion¬† This domain property specifies whether the instance.startAsVersion property is automatically set when an instance is created or upgraded.¬† If true,¬†the instance.startAsVersion property is set to the version of Streams used to create or upgrade the instance.

The addition of rolling upgrade and multi-version support provides greater flexibility for introducing new Streams versions into existing environments where Streams is actively deployed.  You can use the information in this article to learn the requirements of this support and learn how you can put it into use in your environment.

2 comments on"Rolling Upgrade and Multi-Version Support with Streams 4.2"

  1. Alexandr_Semeshchenko October 17, 2018

    could giver some details about “however currently, running jobs must be stopped before doing the rolling upgrade.” ? IBM knowledge center has some part as “All existing PEs that were running before the upgrade is completed continue to run with their original release version”, no stopped.
    And further : “ny new job that you submit to the upgraded instance runs with the release version of the running instance”

    • jingdongsun October 24, 2018

      Streams v4.2 has the limitation that all jobs/PEs need to be canceled before doing a rolling upgrade.
      Streams v4.3 does not have this limitation, so Streams can be upgraded with some jobs/PEs running. After an upgrade, running jobs/PEs keep running with the old version until the end of job’s life cycle, but newly submitted jobs run with the new version. In the case where a rolling upgrade is done with just Streams services running and no running jobs/PEs, newly submitted jobs/PEs (after the upgrade) always run with the new version.

Join The Discussion