Bridging Solace Message VPNs

One of the advantages of distributing data via the Solace message routers is the ability to leverage their built-in bridging and routing capabilities. With these features, several Solace message routers can be joined together into a global data fabric without loss of service level or sacrificing quality of service. Your applications and developers do not have to care, the publish and subscribe code is the same whether messages are distributed within applications on the same switch or across continents. These built-in capabilities allow data to be distributed between Solace message VPNs which are virtualized messaging environments which provide encapsulation, resource management and security for your applications. For more information on Solace message VPNs you can refer to the message VPN introduction in our Developers Portal.

Here we introduce message VPN bridging and walk you through provisioning two different types of bridges: Unidirectional and Bidirectional. We hope this will help new Solace users reason about bridging, and standardize how we talk about them.

The Basics

1. Bridges can connect message VPNs on the same broker, or across different brokers. Almost all the requirements to configure a bridge apply to either case with the exception that for the broker-to-broker bridging additional options can be modified to optimize network performance.
2. Bridges can be Unidirectional (i.e. one-way) or Bidirectional (two-way). There are several use-cases for both, but one example would be to feed data from your production environment to a user-acceptance testing environment; in this case a Unidirectional bridge from PROD to UAT can still provide security to the PROD environment ensuring no data can flow from testing apps into PROD.
   NAMING TIP: encode directionality into your bridge name so it’s immediately evident to everyone. E.g.: redvpn_to_bluevpn versus redvpn_bi_bluevpn
3. Bridges are always defined from the perspective of the destination. The documentation always assumes this perspective but seldom states it. A bridge is configured with local and remote sides; the destination is considered the local bridge which connects via an internal bridge client to the remote side via credentials defined on the remote message VPN.For example, if you want to create a Unidirectional bridge delivering messages from the message VPN RED to message VPN BLUE, you create the local bridge on the BLUE message VPN, and create the remote part within that bridge to point to RED message VPN.Creating a bi-directional bridge would do the above on both sides, but each time treating the remote message VPN as the source of messages being drawn into the local message VPN.

4. Credentials and bridges configured in the Remote part of a bridge must exist in the remote message VPN. That is, the source message VPN on which messages originate. This is because the remote configuration defines how to connect to the remote message VPN and consume from a queue on that message VPN.
5. Best practice is to use a dedicated bridge client-username & client-profile. This username will be used when defining that remote portion of the bridge. This is because the client-profile is where we can optimize wan settings such as TCP window, Initial Congestion Window, etc.
6. Local message VPN-to-VPN bridges are just like cross-broker bridges, they just connect to the localhost instead of remote host. The minimal configuration difference between message VPN bridges within the same appliance, versus message VPN bridges across different appliances is the address for connecting the remote side:

   create bridge red_to_blue message VPN blue_test primary
   create remote message VPN red_test connect-via 127.0.0.1
   
   create bridge red_to_blue message VPN blue_test primary
   create remote message VPN red_test connect-via <broker-name>
   

Unidirectional Bridge Steps

1. Create all necessary message VPNs with message-spool allocated
2. On the Source message VPN:
   1. Create a separate bridge user on the source message VPN that is allowed to make Bridge Connections and Receive guaranteed messages
   2. Create a Bridge Queue, into which messages will accumulate that are to be fanned out to remote message VPNs, mapping appropriate topics to the Bridge Queue that should be fanned out to Destination message VPNs
3. On the Destination message VPN:
   1. Create an Application Queue for each consumer of bridged messages, mapping appropriate bridged topics to that queue
   2. Create a bridge appropriately named (e.g. _to__bridge):
      1. To that bridge, configure a remote message VPN pointing to the Source message VPN and Broker, the Bridge Queue (2b, above) and Bridge User (2a) on that Source message VPN
   3. Configuration is DONE.
   4. To USE this configuration:
      1. Publishers will publish persistent messages to the Source message VPN on topics that are bridged because they were mapped to the bridge-queue,
      2. Consumers will consume from the application Queue on the Destination message VPN

The Details

Here is an example configuration of a unidirectional bridge from one message VPN delivering guaranteed messages to another message VPN. In this case, the destination message VPN is on the same broker, but could easily be on a different broker.

The Source message VPN is named red_test and the Destination message VPN is named blue_test:

Step 1: Create message VPNs

! Same for each message-VPN, just substitute the name
create message-vpn red_test
  authentication
    user-class client
      basic auth-type none
end
configure
message-spool message-vpn red_test
  max-spool-usage 1000
  exit
message-vpn red_test
  no shut
  exit
end
configure
create message-vpn blue_test
  authentication
    user-class client
      basic auth-type none
end
configure
message-spool message-vpn blue_test
  max-spool-usage 1000
  exit
message-vpn blue_test
  no shutdown

Step 2a: SOURCE message VPN Create Bridge User

create client-profile "bridge_profile" message-vpn "red_test"
  allow-bridge-connections
  message-spool allow-guaranteed-message-receive
  exit

create client-username "bridge_user" message-vpn "red_test"
  acl-profile "default"
  client-profile "bridge_profile"
  no shutdown
  exit

Step 2b: SOURCE message VPN Create Bridge Queue

message-spool message-vpn "red_test"
  create queue "red_to_blue_bridge_queue" primary
    access-type "exclusive"
    max-spool-usage 1000
    owner "bridge_user"
    permission all "delete"
    subscription topic "bridged/>" 
    no shutdown ingress
    no shutdown egress

Step 3a: DESTIN message VPN Create App Queue

  message-spool message-vpn "blue_test"
  create queue "app_queue"; primary
    access-type "exclusive"
    max-spool-usage 1000
    permission all "delete"
    subscription topic "bridged/>" 
    no shutdown ingress
    no shutdown egress
    exit
  exit

Step 3b: DESTIN message VPN CREATE THE BRIDGE!

! On Primary HA Pair Member
create bridge red_to_blue message-vpn blue_test primary
create remote message-vpn red_test connect-via 127.0.0.1
client-username bridge_user
message-spool queue red_to_blue_bridge_queue
no shutdown
exit
exit
no shutdown
exit

! On Backup HA Pair Member
create bridge red_to_blue message-vpn blue_test backup

create remote message-vpn red_test connect-via 127.0.0.1
client-username bridge_user
message-spool queue red_to_blue_bridge_queue
no shutdown
exit
exit
no shutdown
exit

On the SolAdmin screen for Bridges & Remote message VPNs, for the destination local message VPN, select the red_to_blue bridge in the main Bridges listing. This will populate the Remote message VPNs list with all applicable Remote message VPNs for that bridge:

You should see the local bridge Inbound Operational State “Ready-In Sync”, and the Queue State “Bound.” On the Remote message VPN the Connection State should be “Up”.

Now you have a working unidirectional bridge selectively bridging messages published to message VPN red_test to message VPN blue_test.

Bidirectional Bridge Steps

1. Create a Unidirectional bridge between two message VPNs; so assume the example of the previous Unidirectional bridge step having been completed, but with a better bridge name like red_bi_blue to indicate that it is a bidirectional bridge.
2. That means that for these steps, we assume the Source and Destination message VPNs from the prior example are now reversed: Source is blue_test and Destination is now red_test.
3. On the Source message VPN:
   1. Create a separate bridge user on the source message VPN that is allowed to make Bridge Connections and Receive guaranteed messages
   2. Create a Bridge Queue, into which messages will accumulate that are to be fanned out to remote message VPNs, mapping appropriate topics to the Bridge Queue that should be fanned out to Destination message VPNs
4. On the Destination message VPN:
   1. Create an Application Queue for each consumer of bridged messages, mapping appropriate bridged topics to that queue
   2. Create a bridge named identically to your Unidirectional Bridge that you configured in the first steps. When they are named identically, Solace infers they are both sides of the same Bidirectional bridge
      1. To that bridge, configure a remote message VPN pointing to the Source message VPN and Broker, the Bridge Queue (3b, above) and Bridge User (3a) on that Source message VPN
   3. Configuration is DONE.
   4. To USE this configuration:
      1. Publishers will publish persistent messages to the Source message VPN on topics that are bridged because they were mapped to the bridge-queue,
      2. Consumers will consume from the application Queue on the Destination message VPN

Configuration is done, so enable all local and remote bridges. A happily-running bridge should look something like this:

For both directions, you should see the local bridge Inbound Operational State “Ready-In Sync”, and the Queue State “Bound.” On the Remote message VPN the Connection State should be “Up”. If so, your bidirectional bridge is up and bridging data in both directions.