taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

Rewording and clarifying added missing properties

Browse Source 
Signed-off-by: Matthias Hanel <mh@synadia.com>
This commit is contained in:
Matthias Hanel 2020-02-14 17:36:21 -05:00
parent bd26d182c0
commit 5e10150a07
2 changed files with 31 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
nats-server/configuration/gateways/README.md
View File

@ -2,26 +2,30 @@
## Gateways ## 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. Gateways enable connecting one or more clusters together into a full mesh; they allow the formation of super clusters from smaller clusters. Cluster and Gateway protocols listen on different ports. Clustering is used for adjacent servers; gateways are for joining clusters together.
Gateway configuration is similar to clustering: Gateway configuration is similar to clustering:
* gateways have a dedicated port where they listen for gateway requests * gateways have a dedicated port where they listen for gateway requests
* gateways gossip gateway members and remote discovered gateways * gateways gossip gateway nodes and remote discovered gateways
Unlike clusters, gateways: Unlike clusters, gateways:
* don't form a full mesh * have names, specifying the cluster they are in
* don't form a full mesh between gateway nodes, but form a full mesh between cluster instead
* are bound by uni-directional connections * are bound by uni-directional connections
* don't gossip gateway nodes to clients
Gateways exist to: Gateways exist to:
* reduce the number of connections required between servers * reduce the number of connections required between servers
* optimize the interest graph propagation * optimize the interest graph propagation
If gateways are to be used in a cluster, **all** server of this cluster need to have a gateway configuration with the **same name**. Furthermore, every gateway node needs to be able to **connect to every** other gateway node and vice versa. Everything else is considered a miss configuration.
## Gateway Connections ## 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. A nats-server in a gateway role will specify a port where it will accept gateway 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. Fewer _external_ `gateways` mean less configuration. Ye, the ability to discover more gateways and gateway nodes depends on these server running. This is similar to _seed server_ in cluster. It is recommended to have all _seed server_ of a cluster listed in the `gateways` section.
If the local cluster has three gateway nodes, this means there will be three outbound connections to each external gateway. If the local cluster has three gateway nodes, this means there will be three outbound connections to each external gateway.
@ -31,9 +35,9 @@ If the local cluster has three gateway nodes, this means there will be three out
![Gateway Discovered Gateways](../../../.gitbook/assets/three_gw.svg) ![Gateway Discovered Gateways](../../../.gitbook/assets/three_gw.svg)
> 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_. > 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. A key point in the description above is that each node in the cluster will make a connection to a single node in every 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. 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.
@ -48,14 +52,17 @@ The number of connections required to join clusters using clustering vs. gateway
| 5 | 105 | 30 | | 5 | 105 | 30 |
| 30 | 4005 | 180 | | 30 | 4005 | 180 |
## Interest Propagation A cluster section is not needed for gateways, they work with single server as well. Yet, they start to be useful when participating cluster consist of more than one server and they reduce the number of connections.
Gateways propagate interest using three different mechanisms: ## Interest Propagation
Messages from clients directly connected to a gateway node will be sent along outgoing gateway connections according to the following three interest propagation mechanisms:
* Optimistic Mode * Optimistic Mode
* Interest-only Mode * Interest-only Mode
* Queue Subscriptions * Queue Subscriptions
Local interest permitting, the receiving gateway node sends the messages directly to it's subscribing clients as well as server within the cluster that have subscribing clients.
### Optimistic Mode ### 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. 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.
@ -70,7 +77,7 @@ When a gateway on _A_ sends many messages on various subjects for which _B_ has
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. 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. 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. The interested cluster is picked based on lowest RTT.
### Gateway Configuration ### Gateway Configuration

27
nats-server/configuration/gateways/gateway.md
View File

@ -1,6 +1,6 @@
# Configuration # Configuration
The `gateway` configuration block is similar to a `cluster` block: The `gateway` configuration block is similar to a [`cluster`](../clustering/cluster_config.md) block:
```text ```text
gateway { gateway {
@ -47,28 +47,31 @@ Starting a server:
Once all the gateways are up, these clusters of one will forward messages as expected: Once all the gateways are up, these clusters of one will forward messages as expected:
```text ```text
> nats-sub -s localhost:4333 ">"
Listening on [>]
# On a different session...
> nats-pub -s localhost:4444 foo bar > nats-pub -s localhost:4444 foo bar
Published [foo] : 'bar' Published [foo] : 'bar'
# On a different session... # nats-sub should print
> nats-sub -s localhost:4333 ">" [#1] Received on [foo] : 'bar'
Listening on [>]
``` ```
## `Gateway` Configuration Block ## `Gateway` Configuration Block
| Property | Description | | Property | Description |
| :--- | :--- | | :--- | :--- |
| `advertise` | Hostport `<host>:<port>` to advertise to other gateways. |
| `authorization` | Authorization block \(same as other nats-server `authorization` configurations\). |
| `connect_retries` | Number of times the server will try to connect to a discovered gateway. |
| `gateways` | List of Gateway entries - see below. |
| `host` | Interface where the gateway will listen for incoming gateway connections. |
| `listen` | Combines `host` and `port` as `<host>:<port>` |
| `name` | Name for this cluster, all gateways belonging to the same cluster, should specify the same name. | | `name` | Name for this cluster, all gateways belonging to the same cluster, should specify the same name. |
| `port` | Port where the gateway will listen for incoming gateway connections. |
| `reject_unknown` | If `true`, gateway will reject connections from gateways that are not configured in `gateways`. | | `reject_unknown` | If `true`, gateway will reject connections from gateways that are not configured in `gateways`. |
| `tls` | TLS configuration block \(same as other [nats-server `tls` configurations](../securing_nats/tls.md#tls-configuration)\). | | `gateways` | List of Gateway [entries](#Gateway-Entry) - see below. |
| `host` | Interface where the gateway will listen for incoming gateway connections. |
| `port` | Port where the gateway will listen for incoming gateway connections. |
| `listen` | Combines `host` and `port` as `<host>:<port>` |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for securing gateway connections. |
| `advertise` | Hostport `<host>:<port>` to advertise how this server can be contacted by other gateway members. This is useful in setups with NAT. |
| `connect_retries` | After how many failed connect attempts to give up establishing a connection to a discovered gateway. Default is `0`, do not retry. When enabled, attempts will be made once a second. This, does not apply to explicitly configured gateways. |
| `authorization` | [Authorization](../securing_nats/auth_intro/README.md#Authorization-Map) map for gateways. When `token` or a single `username`/`password` are used, they define the authentication mechanism this server expects. What authentication values other server have to provide when connecting. They also specify how this server will authenticate itself when establishing a connection to a discovered gateway. This will not be used for gateways explicitly listed in [`gateways`](#Gateway-Entry) and therefore have to be provided as part of the URL. If you use token or password based authentication, either use the same credentials throughout the system or list every gateway explicitly on every server. If the `tls` configuration map specifies `verify_and_map` only provide the expected `username`. Here different certificates can be used, but they do have to map to the same `username`. The authorization map also allows for `timeout` which is honored but `users` and `permissions` are ignored. |
### `Gateway` Entry ### `Gateway` Entry