Docker Upgrade

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

Standalone from 9.8.1+
HA Group from 9.8.1+
HA Group from 9.8.1+ with Orchestration Tool

Upgrade a Standalone Docker Image from Version 9.8.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 9.8.1+ to version 9.9.0 or later:

Log into the Docker host.
Copy the tar file to the Docker host:

[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.

Load the new software event broker Docker version into Docker:

[sysadmin@solace ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

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.

Stop the Docker instance:

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

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.

Remove the Docker container:
```
[sysadmin@solace ~]$ docker rm solace
```
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.
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.

Upgrade a Redundant Docker Image Group from Version 9.8.1+

This upgrade procedure will preserve the event broker’s configuration, including Redundancy and the spooled messages while providing service. 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.

The procedure below 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 following procedure, we will refer ‘solace-primary’ as Primary Node, ‘solace-backup’ as Backup Node, and ‘solace-monitor’ as Monitoring Node.

It is important to reboot the three software event brokers one at a time. If the Monitoring and Backup Nodes are offline at the same time, the Primary Node will automatically reboot.

To upgrade a redundant Docker image group from version 9.8.1+ to version 9.9.0 or later, perform the following steps:

Step 1: Check the redundancy configuration on each node
Step 2: Upgrade the monitoring node
Step 3: Upgrade the backup node
Step 4: Upgrade the primary node

Step 1

Check the redundancy configuration on each node.

Log into each node as an admin user.

Ensure Redundancy Configuration Status is Enabled and Redundancy Status is Up on each node. On solace-primary the Message Spool Status should be AD-Active, and on solace-backup the Message Spool Status should be AD-Standby:

solace-primary> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up
Operating Mode           : Message Routing Node
Switchover Mechanism     : Hostlist
Auto Revert              : No
Redundancy Mode          : Active/Standby
Active-Standby Role      : Primary
Mate Router Name         : solace-backup
ADB Link To Mate         : Up
ADB Hello To Mate        : Up

                               Primary Virtual    Backup Virtual
                               Router             Router
                               ---------------    ---------------
Activity Status                Local Active       Shutdown
Routing Interface              intf0:1            intf0:1
Routing Interface Status       Up                 
VRRP Status                    Initialize         
VRRP Priority                  250                
Message Spool Status           AD-Active          
Priority Reported By Mate      Standby   

solace-backup> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up
Operating Mode           : Message Routing Node
Switchover Mechanism     : Hostlist
Auto Revert              : No
Redundancy Mode          : Active/Standby
Active-Standby Role      : Backup
Mate Router Name         : solace-primary
ADB Link To Mate         : Up
ADB Hello To Mate        : Up

                               Primary Virtual    Backup Virtual
                               Router             Router
                               ---------------    ---------------
Activity Status                Shutdown           Mate Active
Routing Interface              intf0:1            intf0:1
Routing Interface Status                          Up
VRRP Status                                       Initialize
VRRP Priority                                     100
Message Spool Status                              AD-Standby
Priority Reported By Mate                         Active

solace-monitor> show redundancy
Configuration Status     : Enabled
Redundancy Status        : Up
Operating Mode           : Monitoring Node
Switchover Mechanism     : Hostlist
Auto Revert              : No

Step 2

Perform the following steps on the monitoring node.

Log into the solace-monitoring Docker host.

Step 1 to step 10 illustrate 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.
Copy the tar file to the Docker host:
```
[sysadmin@solace-monitor ~]$ 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.

Load the new event broker Docker version into Docker:

[sysadmin@solace-monitor ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

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-monitor ~]$ docker inspect solace
```

Stop the docker instance:

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

Record the host locations of the storage elements.

Remove the Docker container:

[sysadmin@solace-monitor ~]$ docker rm solace

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. Note that 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-monitor ~]$ docker create \
--network=host \
--uts=host \
-v jail:/usr/sw/jail \-v var:/usr/sw/var \
-v internalSpool:/usr/sw/internalSpool \
-v softAdb:/usr/sw/internalSpool/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.
Restart event broker Docker container:
```
[sysadmin@solace-monitor ~]$ docker start solace
```
When solace-monitor restarts, it will be running the configuration and message-spool from the previous version.
Log into the monitoring node and confirm that it is running the new version:
```
solace-monitor> show version
```

Ensure Redundancy Status is Up on solace-monitor:

solace-monitor> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up

Step 3

Perform the following steps on the backup node.

Log into the backup node as an admin user.

Ensure Redundancy Configuration Status is Enabled and Redundancy Status is Up on solace-backup:

solace-backup> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up

If using Config-sync, ensure that it is in sync:

solace-backup> show config-sync
Admin Status            : Enabled
Oper Status             : Up

Log into solace-backup Docker host.

Step 4 to step 14 illustrate 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.
Copy the tar file to the Docker host:
```
[sysadmin@solace-backup ~]$ 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.

Load the new event broker Docker version into Docker:

[sysadmin@solace-backup ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

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-backup ~]$ docker inspect solace
```
If you are using MQTT retained messages in your deployment, verify that your retain cache instances are synchronized. For more information, refer to Verifying Retain Cache Redundancy.

Stop the Docker instance:

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

Record the host locations of the storage elements.

Remove the Docker container:

[sysadmin@solace-backup ~]$ docker rm solace

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. Note that 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-backup ~]$ docker create \
--network=host \
--uts=host \
-v jail:/usr/sw/jail \
-v var:/usr/sw/var \
-v internalSpool:/usr/sw/internalSpool \
-v softAdb:/usr/sw/internalSpool/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.
Restart event broker Docker container:
```
[sysadmin@solace-backup ~]$ docker start solace
```
When solace-backup restarts, it will be running the configuration and message-spool from the previous version.
Log into solace-backup and confirm that it is running the new version:
```
solace-backup> show version
```

Ensure Redundancy Status is Up on solace-backup:

solace-backup> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up

If using Config-sync, ensure that it is in sync:

solace-backup> show config-sync
Admin Status            : Enabled
Oper Status             : Up

If the backup node provides AD service, ensure the Message Spool Status is AD-Standby:
```
solace-backup> show redundancy 
Message Spool Status             AD-Standby
```

Step 4

Perform the following steps on the primary node.

Log into the primary node as an admin user.

Release activity from the primary node to the backup:

solace-primary> enable
solace-primary> configure
solace-primary> redundancy release-activity

On the primary node, ensure Redundancy Configuration Status is Enabled-Released and Redundancy Status is Down:

solace-primary> show redundancy 
Configuration Status     : Enabled-Relased
Redundancy Status        : Down

On the backup node, ensure Redundancy Configuration Status is Enabled, Redundancy Status is Down and the Activity Status on the Backup Virtual Router is Local Active:

Solace-backup> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Down

                               Primary Virtual    Backup Virtual
                               Router             Router
                               ---------------    ---------------
Activity Status                Shutdown           Local Active

Log into the solace-primary Docker host.

Step 5 to step 15 illustrate 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.
Copy the tar file to the Docker host:
```
[sysadmin@solace-prmiary ~]$ 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.

Load the new event broker version into Docker:

[sysadmin@solace-primary ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

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-primary ~]$ docker inspect solace
```
If you are using MQTT retained messages in your deployment, verify that your retain cache instances are synchronized. For more information, refer to Verifying Retain Cache Redundancy.

Stop the Docker instance:

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

Record the host locations of the storage elements.

Remove the Docker container:

[sysadmin@solace-primary ~]$ docker rm solace

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. Note that 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-primary ~]$ docker create \
--network=host \
--uts=host \
-v jail:/usr/sw/jail \-v var:/usr/sw/var \
-v internalSpool:/usr/sw/internalSpool \
-v softAdb:/usr/sw/internalSpool/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.
Restart event broker Docker container:
```
[sysadmin@ solace-primary ~]$ docker start solace
```
When solace-primary restarts, it will be running the configuration and message-spool from the previous version.
Log into solace-primary and confirm that it is running the new version:
```
solace-primary> show version
```

No Release activity from the primary node:

solace-primary> enable
solace-primary> configure
solace-primary> no redundancy release-activity

Ensure Redundancy Status is Up on solace-primary:

solace-primary> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up

If using Config-sync, ensure that it is in sync:

solace-primary> show config-sync
Admin Status            : Enabled
Oper Status             : Up

If the node provides AD service, ensure the Message Spool Status is AD-Standby:

solace-primary> show redundancy 
Message Spool Status             AD-Standby

You have completed this procedure.

The backup is now active and the primary is standby. For instructions describing how to revert the activity back to the primary, refer to Forcing Backups to Give Up Activity to Primaries.

Upgrade a Redundant Docker Image Group from Version 9.8.1+ Using an Orchestration Tool

This procedure is specifically for upgrades using a container orchestration tool such as Kubernetes. The capabilities of such tools vary widely. For example, some do provide the flexibility to control the order in which an HA pair of Solace event brokers can be upgraded. When possible, it is recommended to use the upgrade procedure ‘Upgrading Redundant Docker Image Group’ as it may reduce the number of activity switchover and ensures config-sync is in-sync during the upgrade. Otherwise, the procedure in this section is provided.

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

The nodes (primary, backup and monitoring) can be upgrades in any order.

It is important to reboot the three software event brokers one at time. If the Monitoring and Backup Nodes are offline at the same time, the Primary Node will automatically reboot.

To upgrade a redundant Docker image group from version 9.8.1+ to version 9.9.0 or later using an orchestration tool:

Pick a node not upgraded yet.
Log into the node as an admin user.
Ensure Redundancy Configuration Status is Enabled and Redundancy Status is Up on:
```
solace> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up
```
The following step 4 to 11 illustrates one method of upgrading a Docker container. Event broker Docker 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.
Log into the solace Docker host.
Copy the tar file to the Docker host:
```
[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.

Load the new event broker Docker version into Docker:

[sysadmin@solace ~]$ docker load --input /tmp/solace-pubsub-enterprise-<version>-docker.tar.gz

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, verify that your retain cache instances are synchronized. For more information, refer to Verifying Retain Cache Redundancy.

Stop the docker instance:

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

Remove the Docker container:
```
[sysadmin@solace ~]$ docker rm solace
```
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.
Restart event broker Docker:
```
[sysadmin@solace ~]$ docker start solace
```
When solace-primary restarts, it will be running the configuration and message-spool from the previous version.
Log into solace-primary and confirm that it is running the new version:
```
solace> show version
```

Ensure Redundancy Status is Up on solace:

solace> show redundancy 
Configuration Status     : Enabled
Redundancy Status        : Up

If the upgraded event broker is a messaging node and provides AD service, ensure the Message Spool Status is AD-Standby:
```
solace> show redundancy 
Message Spool Status             AD-Standby
```
Repeat from step 1 until all three nodes are upgraded.

You have completed this procedure.

Provide feedback