HA Group Configuration for Windows

In this section we'll show you how to manually set up and run an HA redundancy group of Solace PubSub+ software event broker Docker containers on a Windows platform.

Alternatively, if you'd like to set up an HA group with Docker Compose, take a look at the template and instructions at GitHub: https://github.com/SolaceLabs/solace-ha-docker-compose.

Before you begin

The configuration shown in this example, which makes use of Solace PubSub+ Standard, is suitable for demonstrating and testing PubSub+ fundamentals, such as HA failover and guaranteed messaging, in non-production situations. It's but one way of setting up an HA group in a resource limited environment such as a laptop. The intent of the configuration is to help you become familiar with the ins-and-outs of HA set up as a step towards using more advanced, production-oriented configurations.

Assumptions

It's assumed you have:

  1. Windows Pro 10.
  2. Windows PowerShell. The example is written for the PowerShell environment for readability, but generically formatted commands are also provided for cutting-and-pasting into other command environments.
  3. Docker installed, with at least 6 GiB of virtual memory (4 GiB must be RAM) and 2 virtual cores dedicated to Docker for Windows. Allocating more cores, if they can be provided, will improve the overall performance. For this example, 4 GiB of RAM, 2 GiB of swap space, and 4 virtual cores have been dedicated to Docker for Windows. To learn about allocating memory and swap space, refer to the Docker Settings page.
  4. A host machine with 8 GB RAM and 4 CPU cores with hyper-threading enabled (8 virtual cores) is recommended.
  5. All software event broker Docker container images in the HA group configured with the same version: Solace PubSub+ 8.10 or higher.
  6. All messaging nodes within the HA group configured to use the same connection scaling tier. In the example shown, the HA configuration is suitable for use with up to 100 client connections on messaging nodes. However, a maximum of 1,000 client connections can be configured on your platform provided appropriate resources have been provisioned. For information on client connection scaling, refer to Scaling Tiers for Software Event Brokers.

Limitations

  1. The following features are not supported: Replication; Docker Engine Swarm mode.
  2. Multi-Node Routing (MNR) is not supported at the 100 connection scaling tier. To use MNR, you must use the 1,000 connection scaling tier or higher.

Step 1: Get a Software Event Broker

First, you need to obtain an event broker Docker package, which is a compressed tar archive containing an event broker Docker repository consisting of a single event broker Docker image.

  • Solace PubSub+ Standard: Go to the Solace PubSub+ Downloads page. Select the Docker square in the PubSub+ Standard section and then select the Download link. You will be able to download a compressed archive file called solace-pubsub-standard-<version>-docker.tar.gz.
  • Solace PubSub+ Enterprise Evaluation Edition: Go to the Solace PubSub+ Downloads page. Select the Docker square in the PubSub+ Enterprise Evaluation section and then select the Download link. You will be able to download a compressed archive file called solace-pubsub-evaluation-<version>-docker.tar.gz.
  • Solace PubSub+ Enterprise: If you have purchased a Docker image of Solace PubSub+ Enterprise, Solace will give you information for how to download the compressed tar archive package from a secure Solace server. Contact Solace Support at support@solace.com if you require assistance.

Once you have obtained a copy of the event broker package, you can upload it to a directory on your host and load the image using these two steps:

  1. Start Docker and open PowerShell.
  2. Load the image:

    > docker load -i C:\Users\username\Downloads\solace-pubsub-standard-8.10.x.x-docker.tar.gz

    In this example, the compressed tar archive of Solace PubSub+ Standard has been uploaded to C:\Users\username\Downloads.

    :  When loading is finished, you can check the image with the images command.

    > docker images
    REPOSITORY                TAG         IMAGE ID        CREATED        SIZE
    solace-pubsub-standard    8.10.x.x    b8a61124d92f    10 days ago    911MB

Step 2: Create a Docker Bridge Network

Once you have loaded the image, create a new Docker bridge network using the docker network create command. The new bridge will allow using the hostname to connect the event brokers in the HA group.

In the example below, we have created a new Docker bridge network called solace-net.

> docker network create solace-net

Step 3: Configure the HA Group

In this step, you'll create the Docker containers to be used for the HA group's primary, backup, and monitoring nodes using the docker create command. You should make note of the following before getting started:

  • The --network solace-net option is used to connect all three containers to the solace-net Docker bridge network.
  • The HA group is set up using configuration keys. In the example below, the configuration key redundancy/enable is used in the line --env 'redundancy_enable=yes' to enable redundancy. The containers are connected to each other using their hostnames through the use of the redundancy/group/node/<name>/connectvia configuration key in the line --env 'redundancy_group_node_primary_connectvia=<hostname>'. In this example, the values of the <hostname> variable are primary, backup, and monitoring. For a complete list of configuration keys associated with HA, refer to the table Solace PubSub+ Software Event Broker Configuration Keys in Setting Configuration Keys.
  • It should also be noted that the redundancy group's pre-shared-key, <pre-shared-key>, in the docker create command must be the same for each node in the HA group.
  • If you loaded the image from a compressed tar archive, replace solace/solace-pubsub-standard in the example with the repository and tag that corresponds with your image. For example, if you loaded version 8.10.0.1022 of the Solace PubSub+ Evaluation Edition, use solace-pubsub-evaluation:8.10.0.1022.

To create the Docker containers and configure the HA group, execute the following commands:

  1. Run the following command to configure the primary event broker:

    > docker create -p 212:2222 -p 213:8080 -p 214:55555 -p 215:8300 -p 216:8301 -p 217:8302 -p 218:8741 `
    --shm-size=1g `
    --ulimit nofile=2448:38048 `
    --env 'username_admin_globalaccesslevel=admin' `
    --env 'username_admin_password=admin' `
    --env 'system_scaling_maxconnectioncount=100' `
    --name=primary `
    --hostname=primary `
    --env 'routername=primary' `
    --network solace-net `
    --env 'nodetype=message_routing' `
    --env 'configsync_enable=yes' `
    --env 'redundancy_enable=yes' `
    --env 'redundancy_group_node_primary_connectvia=primary' `
    --env 'redundancy_group_node_primary_nodetype=message_routing' `
    --env 'redundancy_group_node_backup_connectvia=backup' `
    --env 'redundancy_group_node_backup_nodetype=message_routing' `
    --env 'redundancy_group_node_monitoring_connectvia=monitoring' `
    --env 'redundancy_group_node_monitoring_nodetype=monitoring' `
    --env 'redundancy_authentication_presharedkey_key=<pre-shared-key>' `
    --env 'redundancy_activestandbyrole=primary' `
    --env 'redundancy_matelink_connectvia=backup' `
    solace-pubsub-standard:8.10.x.x

  2. Run the following command to configure the backup event broker:

    > docker create -p 312:2222 -p 313:8080 -p 314:55555 -p 315:8300 -p 316:8301 -p 317:8302 -p 318:8741 `
    --shm-size=1g `
    --ulimit nofile=2448:38048 `
    --env 'username_admin_globalaccesslevel=admin' `
    --env 'username_admin_password=admin' `
    --env 'system_scaling_maxconnectioncount=100' `
    --name=backup `
    --hostname=backup `
    --env 'routername=backup' `
    --network solace-net `
    --env 'nodetype=message_routing' `
    --env 'configsync_enable=yes' `
    --env 'redundancy_enable=yes' `
    --env 'redundancy_group_node_primary_connectvia=primary' `
    --env 'redundancy_group_node_primary_nodetype=message_routing' `
    --env 'redundancy_group_node_backup_connectvia=backup' `
    --env 'redundancy_group_node_backup_nodetype=message_routing' `
    --env 'redundancy_group_node_monitoring_connectvia=monitoring' `
    --env 'redundancy_group_node_monitoring_nodetype=monitoring' `
    --env 'redundancy_authentication_presharedkey_key=<pre-shared-key>' `
    --env 'redundancy_activestandbyrole=backup' `
    --env 'redundancy_matelink_connectvia=primary' `
    solace-pubsub-standard:8.10.x.x

  3. Run the following command to configure the monitoring node:

    > docker create -p 412:2222 -p 413:8080 -p 414:55555 -p 415:8300 -p 416:8301 -p 417:8302 -p 418:8741 `
    --shm-size=1g `
    --ulimit nofile=2448:38048 `
    --env 'username_admin_globalaccesslevel=admin' `
    --env 'username_admin_password=admin' `
    --env 'system_scaling_maxconnectioncount=100' `
    --name=monitoring `
    --hostname=monitoring `
    --env 'routername=monitoring' `
    --network solace-net `
    --env 'nodetype=monitoring' `
    --env 'redundancy_enable=yes' `
    --env 'redundancy_group_node_primary_connectvia=primary' `
    --env 'redundancy_group_node_primary_nodetype=message_routing' `
    --env 'redundancy_group_node_backup_connectvia=backup' `
    --env 'redundancy_group_node_backup_nodetype=message_routing' `
    --env 'redundancy_group_node_monitoring_connectvia=monitoring' `
    --env 'redundancy_group_node_monitoring_nodetype=monitoring' `
    --env 'redundancy_authentication_presharedkey_key=<pre-shared-key>' `
    solace-pubsub-standard:8.10.x.x

  4. After the Docker containers are created, execute the docker start command to run them.

    > docker start primary backup monitoring

Step 4: Assert the Primary’s Configuration

In the previous step, we enabled Config-Sync on the primary and backup event brokers using the configuration key configsync/enable in the line --env configsync_enable=yes. When enabling Config-Sync for the first time on an HA pair, you must assert the system-level configuration of the master event broker (usually it’s the primary event broker in the pair) over its mate.

To assert the system-level configuration on the primary event broker, perform the following steps:

  1. You need to access the Solace CLI on the primary event broker. Enter the following docker exec command to do so:

    > docker exec -it <container-name> /usr/sw/loads/currentload/bin/cli -A

    Where,

    <container-name> is the name of the primary event broker container, which in this example is primary.

  2. You can now use the assert-master router command as shown below.

    primary> enable
    primary# admin
    primary(admin/config-sync)# assert-master router
    Processed 1 config-sync tables 

    As a result of this operation the Open Status of Config-Sync should change from Down to Up on both primary and backup event brokers, check it with the show config-sync User EXEC command.

  3. Verify the redundancy status of the HA group by executing the show redundancy command.

Next Steps

At this point you have an HA redundancy group running on your platform and Guaranteed Messaging is enabled. You can now do things like use the SDKPerf tool to test messaging, or test the HA group’s failover operation.

Once you have tried out some basic HA related functionality, you may be interested in some more advanced HA topics.