Leaf Nodes
Last updated
Was this helpful?
Last updated
Was this helpful?
A Leaf Node extends an existing NATS system of any size, optionally bridging both operator and security domains. A leafnode server will transparently route messages as needed from local clients to one or more remote NATS system(s) and vice versa. The leaf node authenticates and authorizes clients using a local policy. Messages are allowed to flow to the cluster or into the leaf node based on leaf node connection permissions of either.
Leaf nodes are useful in IoT and edge scenarios and when the local server traffic should be low RTT and local unless routed to the super cluster. NATS' queue semantics are honored across leaf connections by serving local queue consumers first.
Clients to leaf nodes authenticate locally (or just connect if authentication is not required)
Traffic between the leaf node and the cluster assumes the restrictions of the user configuration used to create the leaf connection.
Subjects that the user is allowed to publish are exported to the cluster.
Subjects the user is allowed to subscribe to, are imported into the leaf node.
Unlike or nodes, leaf nodes do not need to be reachable themselves and can be used to explicitly configure any acyclic graph topologies.
If a leaf node connects to a cluster, it is recommended to configure it with knowledge of all seed servers and have each seed server accept connections from leaf nodes. Should the remote cluster's configuration change, the discovery protocol will gossip peers capable of accepting leaf connections. A leaf node can have multiple remotes, each connecting to a different cluster. Each URL in a remote needs to point to the same cluster. If one node in a cluster is configured as leaf node, all nodes need to. Likewise, if one server in a cluster accepts leaf node connections, all servers need to.
Leaf Nodes are an important component as a way to bridge traffic between local NATS servers you control and servers that are managed by a third-party. allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters.
The main server is just a standard NATS server. Clients to the main cluster are just using token authentication, but any kind of authentication can be used. The server allows leaf node connections at port 7422 (default port):
Start the server:
Output extract
We create a replier on the server to listen for requests on 'q', which it will aptly respond with '42':
The leaf node, allows local clients to connect to through port 4111, and doesn't require any kind of authentication. The configuration specifies where the remote cluster is located, and specifies how to connect to it (just a simple token in this case):
In the case where the remote leaf connection is connecting with tls:
Note the leaf node configuration lists a number of remotes. The url specifies the port on the server where leaf node connections are allowed.
Start the leaf node server:
Output extract
Connect a client to the leaf server and make a request to 'q':
The nsc tool can operate with many accounts and operators, so it's essential to make sure you're working with the right operator and account. You can set the account using the nsc tool like below. The DELETE_ME account is used as an example, which is registered with NGS as a free account.
The nsc tool is aware of the account, so let's proceed to create a user for our example.
Let's craft a leaf node connection much like we did earlier:
The default port for leaf nodes is 7422, so we don't have to specify it.
Let's start the leaf server:
Again, let's connect a replier, but this time to Synadia's NGS. NSC connects specifying the credentials file:
And now let's make the request from the local host:
As of NATS v2.10.0
In this example, we connect a leaf node to Synadia's . Leaf nodes are supported on free developer and paid accounts. To use NGS, ensure that you've signed up and have an account loaded on your local system. It takes less than 30 seconds to grab yourself a free account to follow along if you don't have one already!
In some cases you may want to restrict what messages can be exported from the leaf node or imported from the leaf connection. You can specify restrictions by limiting what the leaf connection client can publish and subscribe to. See for how you can do this.
Leafnode connections follow the model where when a TCP connection is created to the server, the server will immediately send an in clear text. This INFO protocol provides metadata, including whether the server requires a secure connection.
Some environments prefer not to want a server that is configured to accept TLS connections for leafnodes having any traffic sent in clear text. It was possible to by-pass this using a websocket connection. However, if websocket is not desired, the accepting and remote servers can be to perform a TLS handshake before sending the INFO protocol message.