Leaf Nodes

    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 consumer 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 cluster 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.

    LeafNode Configuration Options

    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

    1. ...
    2. [5774] 2019/12/09 11:11:23.064276 [INF] Listening for leafnode connections on 0.0.0.0:7422
    3. ...

    We create a replier on the server to listen for requests on ‘q’, which it will aptly respond with ‘42’:

    1. nats-rply -s nats://s3cr3t@localhost q 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):

    1. listen: "127.0.0.1:4111"
    2. leafnodes {
    3.     remotes = [ 
    4.         { 
    5.           url: "nats://s3cr3t@localhost"
    6.         },
    7.     ]
    8. }

    In the case where the remote leaf connection is connecting with tls:

    1. listen: "127.0.0.1:4111"
    2. leafnodes {
    3.     remotes = [ 
    4.         { 
    5.           url: "tls://s3cr3t@localhost"
    6.         },
    7.     ]
    8. }

    Start the leaf node server:

    1. nats-server -c /tmp/leaf.conf

    Output extract

    1. ....
    2. [3704] 2019/12/09 09:55:31.548308 [INF] Listening for client connections on 127.0.0.1:4111
    3. ...
    4. [3704] 2019/12/09 09:55:31.549404 [INF] Connected leafnode to "localhost"

    Connect a client to the leaf server and make a request to ‘q’:

    1. nats-req -s nats://127.0.0.1:4111 q ""

    Output

    In this example, we connect a leaf node to Synadia’s . Leaf nodes are supported on developer and paid accounts. To sign up for a developer account, you’ll need the ngs tool which you can install by following instructions in https://github.com/ConnectEverything/ngs-cli.

    Once you have the ngs tool installed, you can go ahead and import the synadia operator from ngs:

    1. nsc add operator -u synadia

    Output

    1. [ OK ] imported operator "synadia"

    Add (or create) an account named ‘leaftest’

    1. nsc add account leaftest

    Output

    1. [ OK ] generated and stored account key "ACR4E2VU2ZC4GPTGOLL6GLO3WHUBBIQBM2JWOGRCEJJQEV6SVXL64JWD"
    2.     [ OK ] pushed account jwt to the account server
    4.     > Use the 'ngs' command to manage your billing plan.
    5.     > If your account JWT is *not* in ~/.nsc, use the -d flag on ngs commands to locate it.
    6. [ OK ] pull jwt from account server
    7. [ OK ] added account "leaftest" to operator "Synadia Communications Inc."

    In order to use leaf nodes, you’ll have to upgrade the account to the developer plan. The developer plan has zero cost, but requires specifying an email and providing a credit card number:

    1. ngs edit

    Output

    2. Please select your new plan. For a complete description of offerings,
    3. please visit our website at https://www.https://www.synadia.com/.
    5. ? Select a Messaging Plan Developer $0.00/month
    7. Synadia will report service notifications and billing updates with the
    8. email address you associate with your account. This address will be
    9. verified if changed.
    11. ? Email natsuser@test.com
    13. ╭────────────────────────────────╮
    14. │        Account Details         │
    15. ├────────┬───────────────────────┤
    16. │ Email: │ natsuser@test.com     |
    17. │ Plan:  │ Developer $0.00/month │
    18. ╰────────┴───────────────────────╯
    21. ? Check your account details OK
    23. Your changes were sent to Synadia, but it looks like we need to verify
    24. your email and credit card before updating your account. You should
    25. receive a welcome email shortly.
    26. Once the update succeeds use nsc to sync the latest version of your
    27. synadia account JWT to disk.
    1. nsc pull

    Output

    1. [ OK ] pulled "leaftest" from the account server

    Show the account info

    Example output

    1. ╭──────────────────────────────────────────────────────────────────────────────────────╮
    2. │                                   Account Details                                    │
    3. │ Name                      │ leaftest                                                 │
    4. │ Account ID                │ ACR4E2VU2ZC4GPTGOLL6GLO3WHUBBIQBM2JWOGRCEJJQEV6SVXL64JWD │
    5. │ Issuer ID                 │ ODSKBNDIT3LTZWFSRAWOBXSBZ7VZCDQVU6TBJX3TQGYXUWRU46ANJJS4 │
    6. │ Issued                    │ 2019-12-09 14:44:55 UTC                                  │
    7. │ Expires                   │                                                          │
    8. ├───────────────────────────┼──────────────────────────────────────────────────────────┤
    9. │ Max Connections           │ 50                                                       │
    10. │ Max Leaf Node Connections │ 2                                                        │
    11. │ Max Data                  │ 5.0 GB (5000000000 bytes)                                │
    12. │ Max Exports               │ Unlimited                                                │
    13. │ Max Imports               │ Unlimited                                                │
    14. │ Max Msg Payload           │ 4.0 kB (4000 bytes)                                      │
    15. │ Max Subscriptions         │ 50                                                       │
    16. │ Exports Allows Wildcards  │ False                                                    │
    17. ├───────────────────────────┼──────────────────────────────────────────────────────────┤
    18. │ Exports                   │ None                                                     │
    19. ╰───────────────────────────┴──────────────────────────────────────────────────────────╯
    21. ....

    Note the limits on the account, specify that the account can have up-to 2 leaf node connections. Let’s use them:

    1. nsc add user leaftestuser

    Example output

    1. [ OK ] generated and stored user key "UB5QBEU4LU7OR26JEYSG27HH265QVUFGXYVBRD7SVKQJMEFSZTGFU62F"
    2. [ OK ] generated user creds file "~/.nkeys/creds/synadia/leaftest/leaftestuser.creds"
    3. [ OK ] added user "leaftestuser" to account "leaftest"

    Let’s craft a leaf node connection much like we did earlier:

    1. leafnodes {
    2.     remotes = [ 
    3.         { 
    4.           url: "tls://connect.ngs.global"
    5.           credentials: "/Users/alberto/.nkeys/creds/synadia/leaftest/leaftestuser.creds"
    6.         },
    7.     ]
    8. }

    The default port for leaf nodes is 7422, so we don’t have to specify it.

    Let’s start the leaf server:

    1. nats-server -c /tmp/ngs_leaf.conf

    Output

    1. ...
    2. [4985] 2019/12/09 10:55:51.577569 [INF] Listening for client connections on 0.0.0.0:4222
    3. ...
    4. [4985] 2019/12/09 10:55:51.918781 [INF] Connected leafnode to "connect.ngs.global"

    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:

    1. nats-req q ""

    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.