Docker Upgrade

On this page you'll find procedures to upgrade your Solace PubSub+ event broker Docker images to version 10.1.1 or later (the current version is 10.12.0).

Upgrade a Standalone Docker Image from Version 10.0.1+

To upgrade a Solace PubSub+ event broker container instance, the user must delete the existing container instance and replace it with a new container instance running the target version. To preserve the existing state, the new container instance must be deployed with the storage elements from the existing instance.

This upgrade procedure will preserve the event broker’s configuration and stored messages. All of the persistent data needed to recreate a PubSub+ instance is contained in the storage elements. At a minimum, the var and internalSpool storage elements must be preserved in order to successfully upgrade an event broker instance.

This procedure describes upgrading from PubSub+ Enterprise to PubSub+ Enterprise.

On non-Enterprise event brokers, the following upgrades are also supported:

  • from Evaluation to Enterprise
  • from Standard to Standard
  • from Standard to Enterprise

For the upgrades between other editions, some prompts will have a different edition included and one must take care to change the file name and the docker create command (search for the word ‘enterprise’ and change as needed).

The following procedure is one method of upgrading a Docker container. The event broker Docker container can be upgraded using any supported Docker upgrade procedure. You should choose a procedure that matches your deployment. For example, if your event broker Docker deployment is managed by Linux service or systemctl, then this procedure will need to be adjusted accordingly.

To upgrade a standalone Docker image from version 10.0.1+ to version 10.1.1 or later:

  1. Log into the Docker host.
  2. Copy the tar file to the Docker host:
    3. [sysadmin@solace ~]$ scp [<username>@]<ip-addr>:solace-pubsub-enterprise-<version>-docker.tar.gz /tmp

    Where:

    <username>, <ip-addr>, and solace-pubsub-enterprise-<version>-docker.tar.gz correspond to the access information of where the new SolOS software is located.

  3. Load the new software event broker Docker version into Docker: 
    [sysadmin@solace ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

  4. Use Docker inspect to read and record the settings used to create the old event broker Docker instance (In this example, the container is named solace):

    [sysadmin@solace ~]$ docker inspect solace

    If you are using MQTT retained messages in your deployment, the next step clears the contents of each retain cache. If this content is stored somewhere else in the network, for example another DMR or MNR node, the content will be retrieved when this node comes back online.

  5. Stop the Docker instance:

    [sysadmin@solace ~]$ docker stop --time 1200 solace

  6. Record the host locations of the storage elements.

    Before removing the container in the next step, it is important to record the host locations of the storage elements so that they can be re-attached to the new instance. To get information on volumes and the host path to each volume, click on Finding Host Path to Volumes below.

  7. Remove the Docker container:

    [sysadmin@solace ~]$ docker rm solace

  8. Create a new Docker instance. Parameters should be selected by reading the documentation of the new software version and comparing them to the parameters used for the previous load. The timezone will be set to UTC unless it is overridden using the TZ environment variable. When selecting the volumes for upgrade, consider where the data is stored from the previous software version and how to map that into the container.

    The following docker create options is an example only.

    [user@host /]# exit
[sysadmin@solace ~]$ docker create \
--network=host \
--uts=host \
-v jail:/usr/sw/jail \
-v var:/usr/sw/var \
-v Code:/usr/sw/Code \
-v softAdb:/usr/sw/Code/softAdb \
-v adbBackup:/usr/sw/adb \
-v diagnostics:/var/lib/solace/diags \
--shm-size=4g \
--ulimit nofile=2448:38048 \
--env 'TZ=Canada/Eastern' \
--env 'umask=0022' \
--name=solace solace-pubsub-enterprise:<version>

    Config-keys can be specified in the docker create command. However, they only take effect when the container is booted for the first time and the database is absent. During an upgrade, config-keys are not re-evaluated and changes made to the config-keys when creating the new container will not take effect.

    As explained in Initializing a Software Event Broker Container, TZ (timezone) and UMASK are not configuration keys. They are simply environment variables that are processed by the container’s operating system. Unlike config-keys, changes to these environment variables (as shown in the above docker create command) take effect whenever the container is restarted.

  9. Restart software event broker Docker container.

    [sysadmin@solace ~]$ docker start solace

When the software event broker Docker container restarts, it will be running the configuration and message-spool from the previous version.

You have completed this procedure.