NATS Logo by Example

Supercluster in Topologies

A supercluster is a set of clusters that have gateway connections established between them. A gateway connection bridges communication, specifically by propagating the subject-interest graph across clusters.

In practice, this means a client connecting to cluster A that is interested in using a service by a client connected to cluster B, messages will transparently flow across clusters without the client needing to have any knowledge of physical location.

This example shows how to setup a basic supercluster with two clusters. Note, if you are using JetStream, please refer to the dedicated Supercluster with JetStream example.

CLI Go Python JavaScript Rust C# Java Ruby Elixir Crystal C
Jump to the output or the recording
$ nbe run topologies/supercluster/cli
View the source code or learn how to run this example yourself

Code

#!/bin/sh


set -euo pipefail

Define the system account to be included by all configurations.

cat <<- EOF > sys.conf
accounts: {
  \$SYS: {
    users: [{user: sys, password: sys}]
  }
}
EOF

Create the east and west single-node server configurations declaring gateway connections for each. By default, the gateway name will be used as the cluster name even if the cluster block is not specified. Of course, if this were a real cluster with routes defined, this would need to be defined as well.

cat <<- EOF > east.conf
port: 4222
http_port: 8222
server_name: n1


include sys.conf


gateway: {
  name: east,
  port: 7222,
  gateways: [
    {name: "east", urls: ["nats://0.0.0.0:7222"]},
    {name: "west", urls: ["nats://0.0.0.0:7223"]},
  ]
}
EOF


cat <<- EOF > west.conf
port: 4223
http_port: 8223
server_name: n2


include sys.conf


gateway: {
  name: west,
  port: 7223,
  gateways: [
    {name: "east", urls: ["nats://0.0.0.0:7222"]},
    {name: "west", urls: ["nats://0.0.0.0:7223"]},
  ]
}
EOF

Start the servers and sleep for a few seconds to startup.

nats-server -c east.conf > /dev/null 2>&1 &
nats-server -c west.conf > /dev/null 2>&1 &


sleep 3

Wait until the servers are healthy.

curl --fail --silent \
  --retry 5 \
  --retry-delay 1 \
  http://localhost:8222/healthz > /dev/null


curl --fail --silent \
  --retry 5 \
  --retry-delay 1 \
  http://localhost:8223/healthz > /dev/null

Save a couple NATS CLI contexts for convenience.

nats context save east \
  --server "nats://localhost:4222"


nats context save east-sys \
  --server "nats://localhost:4222" \
  --user sys \
  --password sys


nats context save west \
  --server "nats://localhost:4223"

Show the server list which will indicate the clusters and gateway connections.

nats --context east-sys server list

Start a service running in east.

nats --context east reply 'greet' 'hello from east' &


sleep 1

Send a request with a client connected to west.

nats --context west request 'greet' ''

Output

NATS Configuration Context "east"

  Server URLs: nats://localhost:4222
         Path: /root/.config/nats/context/east.json

NATS Configuration Context "east-sys"

  Server URLs: nats://localhost:4222
     Username: sys
     Password: ***
         Path: /root/.config/nats/context/east-sys.json

NATS Configuration Context "west"

  Server URLs: nats://localhost:4223
         Path: /root/.config/nats/context/west.json

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                  Server Overview                                                  │
├──────┬─────────┬──────┬─────────┬────┬───────┬──────┬────────┬─────┬────────┬───────┬───────┬──────┬────────┬─────┤
│ Name │ Cluster │ Host │ Version │ JS │ Conns │ Subs │ Routes │ GWs │ Mem    │ CPU % │ Cores │ Slow │ Uptime │ RTT │
├──────┼─────────┼──────┼─────────┼────┼───────┼──────┼────────┼─────┼────────┼───────┼───────┼──────┼────────┼─────┤
│ n1   │ east    │ 0    │ 2.10.1  │ no │ 1     │ 56   │      0 │   1 │ 12 MiB │ 0     │     8 │    0 │ 3.12s  │ 5ms │
│ n2   │ west    │ 0    │ 2.10.1  │ no │ 0     │ 55   │      0 │   1 │ 12 MiB │ 0     │     8 │    0 │ 3.12s  │ 7ms │
├──────┼─────────┼──────┼─────────┼────┼───────┼──────┼────────┼─────┼────────┼───────┼───────┼──────┼────────┼─────┤
│      │ 2       │ 2    │         │ 0  │ 1     │ 111  │        │     │ 24 MIB │       │       │    0 │        │     │
╰──────┴─────────┴──────┴─────────┴────┴───────┴──────┴────────┴─────┴────────┴───────┴───────┴──────┴────────┴─────╯

╭────────────────────────────────────────────────────────────────────────────╮
│                              Cluster Overview                              │
├─────────┬────────────┬───────────────────┬───────────────────┬─────────────┤
│ Cluster │ Node Count │ Outgoing Gateways │ Incoming Gateways │ Connections │
├─────────┼────────────┼───────────────────┼───────────────────┼─────────────┤
│ west    │          1 │                 1 │                 1 │           0 │
│ east    │          1 │                 1 │                 1 │           1 │
├─────────┼────────────┼───────────────────┼───────────────────┼─────────────┤
│         │          2 │                 2 │                 2 │           1 │
╰─────────┴────────────┴───────────────────┴───────────────────┴─────────────╯
19:30:56 Listening on "greet" in group "NATS-RPLY-22"
19:30:57 Sending request on "greet"
19:30:57 [#0] Received on subject "greet":
19:30:57 Received with rtt 922.083µs


hello from east

Recording

Note, playback is half speed to make it a bit easier to follow.