Supercluster (CLI)

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 Deno Node Rust C# Java Ruby Elixir 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}]
  }
}


system_account: 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" > /dev/null


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


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

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

Network 4a184720_default  Creating
Network 4a184720_default  Created
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                 Server Overview                                                  │
├──────┬────────────┬───────────┬─────────┬────┬───────┬──────┬────────┬─────┬─────────┬─────┬──────┬────────┬─────┤
│ Name │ Cluster    │ IP        │ Version │ JS │ Conns │ Subs │ Routes │ GWs │ Mem     │ CPU │ Slow │ Uptime │ RTT │
├──────┼────────────┼───────────┼─────────┼────┼───────┼──────┼────────┼─────┼─────────┼─────┼──────┼────────┼─────┤
│ n1   │ east       │ 0.0.0.0   │ 2.9.1   │ no │ 1     │ 45   │ 0      │ 1   │ 11 MiB  │ 0.0 │ 0    │ 3.23s  │ 2ms │
│ n2   │ west       │ 0.0.0.0   │ 2.9.1   │ no │ 0     │ 44   │ 0      │ 1   │ 9.2 MiB │ 0.0 │ 0    │ 3.23s  │ 2ms │
├──────┼────────────┼───────────┼─────────┼────┼───────┼──────┼────────┼─────┼─────────┼─────┼──────┼────────┼─────┤
│      │ 2 Clusters │ 2 Servers │         │ 0  │ 1     │ 89   │        │     │ 20 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           │
╰─────────┴────────────┴───────────────────┴───────────────────┴─────────────╯
21:32:25 Listening on "greet" in group "NATS-RPLY-22"
21:32:26 Sending request on "greet"
21:32:26 [#0] Received on subject "greet":


21:32:26 Received with rtt 2.624434ms
hello from east

Recording

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