From 038572b3fae26cbdd71ef738f82787ce6be22816 Mon Sep 17 00:00:00 2001 From: Matthias Hanel Date: Fri, 21 Feb 2020 21:09:28 -0500 Subject: [PATCH 1/3] Incorporating unexplained leaf node features Signed-off-by: Matthias Hanel --- nats-server/configuration/leafnodes/README.md | 10 ++++++--- .../configuration/leafnodes/leafnode_conf.md | 22 ++++++++++--------- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/nats-server/configuration/leafnodes/README.md b/nats-server/configuration/leafnodes/README.md index ba2a488..e7e3589 100644 --- a/nats-server/configuration/leafnodes/README.md +++ b/nats-server/configuration/leafnodes/README.md @@ -1,14 +1,18 @@ # Leaf Nodes -A _Leaf Node_ extends a cluster or supercluster by bridging security domains. A leaf node proxies local messages to the cluster and cluster messages to the local server through the leaf node's connection client. 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 the leaf node's connection permissions. +A _Leaf Node_ extends a cluster or [supercluster](../gateways/README.md#gateways) by bridging security domains. A leaf node proxies local messages to the cluster and cluster messages to the local server through the leaf node's connection client. 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 the leaf node's connection permissions. -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. Messages flow in and out of the leaf node using the permissions available to the leaf node connection. +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. Messages flow in and out of the leaf node using the permissions available to the leaf node connection. -* Leaf nodes clients authenticate locally \(or just connect if authentication is not required\) +* 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](../clustering/README.md) or [gateway](../gateways/README.md) nodes, leaf nodes do not need to be reachable themselves and can be used to configure explicit tree topologies \(cycles are a miss configuration\). + +If a leaf node connects to a cluster, it is recommended to configure it with knowledge of **all** _seed server_ and heave **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. Configuring leaf node's to connect to servers of more than one cluster is considered a miss configuration. If one node in a cluster is configured as leaf node, **all** nodes 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. Synadia's [NATS Global Service \(NGS\)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters. [LeafNode Configuration Options](leafnode_conf.md) diff --git a/nats-server/configuration/leafnodes/leafnode_conf.md b/nats-server/configuration/leafnodes/leafnode_conf.md index e20f8bc..a6b93b3 100644 --- a/nats-server/configuration/leafnodes/leafnode_conf.md +++ b/nats-server/configuration/leafnodes/leafnode_conf.md @@ -2,16 +2,19 @@ ## `leafnodes` Configuration Block +The leaf node configuration block is used to configure incoming as well as outgoing leaf node connections. Most properties are for the configuration of incoming connections. The properties `remotes` and `reconnect` are for outgoing connections. + | Property | Description | | :--- | :--- | -| `advertise` | Hostport `:` to advertise to other servers. | -| `authorization` | Authorization block. [**See Authorization Block section below**](leafnode_conf.md#authorization-block). | | `host` | Interface where the server will listen for incoming leafnode connections. | -| `listen` | Combines `host` and `port` as `:` | -| `no_advertise` | if `true` the leafnode shouldn't be advertised. | | `port` | Port where the server will listen for incoming leafnode connections \(default is 7422\). | -| `remotes` | List of `remote` entries specifying servers where leafnode client connection can be made. | -| `tls` | TLS configuration block \(same as other nats-server `tls` configuration\). | +| `listen` | Combines `host` and `port` as `:` | +| `tls` | TLS configuration block \(same as other nats-server [`tls` configuration](../securing_nats/tls.md)\).| +| `advertise` | Hostport `:` to advertise how this server can be contacted by leaf nodes. This is useful in cluster setups with NAT. | +| `no_advertise` | if `true` the server shouldn't be advertised to leaf nodes. | +| `authorization` | Authorization block. [**See Authorization Block section below**](leafnode_conf.md#authorization-block). | +| `remotes` | List of [`remote`](#leafnode-remotes-entry-block) entries specifying servers where leafnode client connection can be made. | +| `reconnect` | Interval in seconds at which reconnect attempts to a remote server are made. | ## Authorization Block @@ -29,7 +32,7 @@ | :--- | :--- | | `user` | Username for the leaf node connection. | | `password` | Password for the user entry. | -| `account` | Account this leaf node connection should be bound to. | +| `account` | Account this leaf node connection should be bound to. | Here are some examples of using basic user/password authentication for leaf nodes \(note while this is using accounts it is not using JWTs\) @@ -89,9 +92,9 @@ If other form of credentials are used \(jwt, nkey or other\), then the server wi | `urls` | Leafnode URL array. Supports multiple URLs for discovery, e.g., urls: \[ "nats-leaf://host1:7422", "nats-leaf://host2:7422" \] | | `account` | Account public key identifying the leafnode. Account must be defined locally. | | `credentials` | Credential file for connecting to the leafnode server. | -| `tls` | A TLS configuration block. Leafnode client will use specified TLS certificates when connecting/authenticating. | +| `tls` | A [TLS configuration](#tls-configuration-block) block. Leafnode client will use specified TLS certificates when connecting/authenticating. | -## `tls` Configuration Block +### `tls` Configuration Block | Property | Description | | :--- | :--- | @@ -104,4 +107,3 @@ If other form of credentials are used \(jwt, nkey or other\), then the server wi | `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match golang version used to build the server. | | `curve_preferences` | List of TLS cypher curves to use in order. | | `timeout` | TLS handshake timeout in fractional seconds. | - From 406afd22b4ee20ac12f056eca3aad07cfed78445 Mon Sep 17 00:00:00 2001 From: Matthias Hanel Date: Mon, 24 Feb 2020 11:53:07 -0500 Subject: [PATCH 2/3] Incorporating comments Signed-off-by: Matthias Hanel --- nats-server/configuration/leafnodes/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/nats-server/configuration/leafnodes/README.md b/nats-server/configuration/leafnodes/README.md index e7e3589..6ddd6f0 100644 --- a/nats-server/configuration/leafnodes/README.md +++ b/nats-server/configuration/leafnodes/README.md @@ -1,17 +1,17 @@ # Leaf Nodes -A _Leaf Node_ extends a cluster or [supercluster](../gateways/README.md#gateways) by bridging security domains. A leaf node proxies local messages to the cluster and cluster messages to the local server through the leaf node's connection client. 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 the leaf node's connection permissions. +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 the remote NATS system 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 consumer first. Messages flow in and out of the leaf node using the permissions available to the leaf node connection. +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](../clustering/README.md) or [gateway](../gateways/README.md) nodes, leaf nodes do not need to be reachable themselves and can be used to configure explicit tree topologies \(cycles are a miss configuration\). +Unlike [cluster](../clustering/README.md) or [gateway](../gateways/README.md) nodes, leaf nodes do not need to be reachable themselves and can be used to configure explicit tree topologies \(cycles are a mis-configuration\). -If a leaf node connects to a cluster, it is recommended to configure it with knowledge of **all** _seed server_ and heave **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. Configuring leaf node's to connect to servers of more than one cluster is considered a miss configuration. If one node in a cluster is configured as leaf node, **all** nodes need to. +If a leaf node connects to a cluster, it is recommended to configure it with knowledge of **all** _seed server_ and heave **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. Configuring leaf node's to connect to servers of more than one cluster is considered a mis-configuration. 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** server 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. Synadia's [NATS Global Service \(NGS\)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters. From 6a2d03c83f84af4776a0c0ec4a93ae4b93c44ed4 Mon Sep 17 00:00:00 2001 From: Matthias Hanel Date: Mon, 9 Mar 2020 17:30:27 -0400 Subject: [PATCH 3/3] Clarifying topology (acyclic graph) and multiple remotes possible Signed-off-by: Matthias Hanel --- nats-server/configuration/leafnodes/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/nats-server/configuration/leafnodes/README.md b/nats-server/configuration/leafnodes/README.md index 6ddd6f0..b9ace55 100644 --- a/nats-server/configuration/leafnodes/README.md +++ b/nats-server/configuration/leafnodes/README.md @@ -1,6 +1,6 @@ # Leaf Nodes -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 the remote NATS system 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. +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 consumer first. @@ -9,9 +9,9 @@ Leaf nodes are useful in IoT and edge scenarios and when the local server traffi * 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](../clustering/README.md) or [gateway](../gateways/README.md) nodes, leaf nodes do not need to be reachable themselves and can be used to configure explicit tree topologies \(cycles are a mis-configuration\). +Unlike [cluster](../clustering/README.md) or [gateway](../gateways/README.md) 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 server_ and heave **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. Configuring leaf node's to connect to servers of more than one cluster is considered a mis-configuration. 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** server need to. +If a leaf node connects to a cluster, it is recommended to configure it with knowledge of **all** _seed server_ 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** server 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. Synadia's [NATS Global Service \(NGS\)](https://www.synadia.com/) allows accounts to use leaf nodes, but gain accessibility to the global network to inexpensively connect geographically distributed servers or small clusters.