Redirecting...

This page has moved to https://docs.nats.io.

Click here if you are not redirected.

Gateways

Gateways enable connecting one or more clusters together; they allow the formation of super clusters from smaller clusters. Cluster and Gateway protocols listen in different ports. Clustering is used for adjacent servers; gateways are for joining clusters together. Typically all cluster nodes will also be gateway nodes, but this is not a requirement.

Gateway configuration is similar to clustering:

• gateways have a dedicated port where they listen for gateway requests
• gateways gossip gateway members and remote discovered gateways

Unlike clusters, gateways:

• don't form a full mesh
• are bound by uni-directional connections

Gateways exist to:

• reduce the number of connections required between servers
• optimize the interest graph propagation

Gateway Connections

A nats-server in a gateway role will specify a port where it will accept gateways connections. If the configuration specifies other external gateways, the gateway will create one outbound gateway connection for each gateway in its configuration. It will also gossip other gateways it knows or discovered.

If the local cluster has three gateway nodes, this means there will be three outbound connections to each external gateway.

In the example above cluster A has configured gateway connections for B (solid lines). B has discovered gateway connections to A (dotted lines). Note that the number of outgoing connections always matches the number of gateways with the same name.

In this second example, again configured connections are shown with solid lines and discovered gateway connections are shown using dotted lines. Gateways A and C were both discovered via gossiping; B discovered A and A discovered C.

A key point in the description above is that each node in the cluster will make a connection to a single node in the remote cluster — a difference from the clustering protocol, where every node is directly connected to all other nodes.

For those mathematically inclined, cluster connections are N(N-1)/2 where N is the number of nodes in the cluster. On gateway configurations, outbound connections are the summation of Ni(M-1) where Ni is the number of nodes in a gateway i, and M is the total number of gateways. Inbound connections are the summation of U-Ni where U is the sum of all gateway nodes in all gateways, and N is the number of nodes in a gateway i. It works out that both inbound and outbound connection counts are the same.

The number of connections required to join clusters using clustering vs. gateways is apparent very quickly. For 3 clusters, with N nodes:

Interest Propagation

Gateways propagate interest using three different mechanisms:

• Optimistic Mode
• Interest-only Mode
• Queue Subscriptions

Optimistic Mode

When a publisher in A publishes "foo", the A gateway will check if cluster B has registered no interest in "foo". If not, it forwards "foo" to B. If upon receiving "foo", B has no subscribers on "foo", B will send a gateway protocol message to A expressing that it has no interest on "foo", preventing future messages on "foo" from being forwarded.

Should a subscriber on B create a subscription to "foo", B knowing that it had previously rejected interest on foo, will send a gateway protocol message to cancel its previous no interest on "foo" in A.

Interest-only Mode

When a gateway on A sends many messages on various subjects for which B has no interest. B sends a gateway protocol message for A to stop sending optimistically, and instead send if there's known interest in the subject. As subscriptions come and go on B, B will update its subject interest with A.

Queue Subscriptions

When a queue subscriber creates a new subscription, the gateway propagates the subscription interest to other gateways. The subscription interest is only propagated once per Account and subject. When the last queue subscriber is gone, the cluster interest is removed.

Queue subscriptions work on Interest-only Mode to honor NATS' queue semantics across the Super Cluster. For each queue group, a message is only delivered to a single queue subscriber. Only when a local queue group member is not found, is a message forwarded to a different interested cluster; gateways will always try to serve local queue subscribers first and only failover when a local queue subscriber is not found.

Gateway Configuration

The Gateway Configuration document describes all the options available to gateways.