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

GitBook: [master] 7 pages modified

Browse Source
This commit is contained in:
Ginger Collison 2021-05-03 14:35:12 +00:00 committed by gitbook-bot
parent 38341ece09
commit 8a81a6d4a8
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
6 changed files with 30 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@ -100,7 +100,7 @@
* [Monitoring](nats-server/configuration/monitoring.md)
* [MQTT](nats-server/configuration/mqtt/README.md)
* [Configuration](nats-server/configuration/mqtt/mqtt_config.md)
* [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping/subject_mapping.md)
* [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping.md)
* [System Events](nats-server/configuration/sys_accounts/README.md)
* [System Events & Decentralized JWT Tutorial](nats-server/configuration/sys_accounts/sys_accounts.md)
* [WebSocket](nats-server/configuration/websocket/README.md)

2
jetstream/concepts/streams.md
View File

@ -16,7 +16,7 @@ When defining Streams the items below make up the entire configuration of the se
| Item | Description |
| :--- | :--- |
| Name | A name for the Stream that may not have spaces, tabs, period (`.`), greater than (`>`) or asterix (`*`) |
| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) |
| Storage | The type of storage backend, `File` and `Memory` |
| Subjects | A list of subjects to consume, supports wildcards |
| Replicas | How many replicas to keep for each message in a clustered JetStream, maximum 5 |

2
nats-protocol/nats-protocol/README.md
View File

@ -12,7 +12,7 @@ The NATS server implements a [zero allocation byte parser](https://youtu.be/ylRK
**Control line w/Optional Content**: Each interaction between the client and server consists of a control, or protocol, line of text followed, optionally by message content. Most of the protocol messages don't require content, only `PUB` and `MSG` include payloads.
**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '` `'\(space\) or`\t` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '```'\(space\) or``\t\` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
**Newlines**: NATS uses `CR` followed by `LF` \(`CR+LF`, `\r\n`, `0x0D0A`\) to terminate protocol messages. This newline sequence is also used to mark the end of the message payload in a `PUB` or `MSG` protocol message.

2
nats-protocol/nats-server-protocol.md
View File

@ -12,7 +12,7 @@ The NATS cluster protocol is very similar to that of the NATS client protocol. I
**Subject names and wildcards**: The NATS cluster protocol has the same features and restrictions as the client with respect to subject names and wildcards. Clients are bound to a single account, however the cluster protocol handles all accounts.
**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '` `'\(space\) or`\t` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '```'\(space\) or``\t\` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
**Newlines**: Like other text-based protocols, NATS uses `CR` followed by `LF` \(`CR+LF`, `\r\n`, `0x0D0A`\) to terminate protocol messages. This newline sequence is also used to mark the beginning of the actual message payload in a `RMSG` protocol message.

72
nats-server/configuration/subject_mapping/subject_mapping.md → nats-server/configuration/subject_mapping.md
View File

@ -2,14 +2,11 @@
_Supported since NATS Server version 2.2_
Subject mapping is a very powerful feature of the NATS server, useful for
canary deployments, A/B testing, chaos testing, and migrating to a new
subject namespace.
Subject mapping is a very powerful feature of the NATS server, useful for canary deployments, A/B testing, chaos testing, and migrating to a new subject namespace.
The `mappings` stanza can occur at the top level to apply
to the global account or be scoped within a specific account.
The `mappings` stanza can occur at the top level to apply to the global account or be scoped within a specific account.
```
```text
mappings = {
# Simple direct mapping. Messages published to foo are mapped to bar.
@ -46,32 +43,27 @@ mappings = {
## Simple Mapping
The example of `foo:bar` is straightforward. All messages the server receives on subject
`foo` are remapped and can be received by clients subscribed to `bar`.
The example of `foo:bar` is straightforward. All messages the server receives on subject `foo` are remapped and can be received by clients subscribed to `bar`.
## Subject Token Reordering
Wildcard tokens may be referenced via `$<position>`. For example, the first wildcard
token is $1, the second is $2, etc. Referencing these tokens can allow for reordering.
Wildcard tokens may be referenced via `$<position>`. For example, the first wildcard token is $1, the second is $2, etc. Referencing these tokens can allow for reordering.
With this mapping:
```
```text
bar.*.*: baz.$2.$1
```
Messages that were originally published to `bar.a.b` are remapped in the server to `baz.b.a`.
Messages arriving at the server on `bar.one.two` would be mapped to `baz.two.one`, and so forth.
Messages that were originally published to `bar.a.b` are remapped in the server to `baz.b.a`. Messages arriving at the server on `bar.one.two` would be mapped to `baz.two.one`, and so forth.
## Weighted Mappings for A/B Testing or Canary Releases
Traffic can be split by percentage from one subject to multiple subjects. Here's an example
for canary deployments, starting with version 1 of your service.
Traffic can be split by percentage from one subject to multiple subjects. Here's an example for canary deployments, starting with version 1 of your service.
Applications would make requests of a service at `myservice.requests`. The responders doing the
work of the server would subscribe to `myservice.requests.v1`. Your configuration would look like
this:
Applications would make requests of a service at `myservice.requests`. The responders doing the work of the server would subscribe to `myservice.requests.v1`. Your configuration would look like this:
```
```text
myservice.requests: [
{ destination: myservice.requests.v1, weight: 100% }
]
@ -79,28 +71,22 @@ this:
All requests to `myservice.requests` will go to version 1 of your service.
When version 2 comes along, you'll want to test it with a canary deployment. Version 2 would
subscribe to `myservice.requests.v2`. Launch instances of your service (don't forget
about queue subscribers and load balancing).
When version 2 comes along, you'll want to test it with a canary deployment. Version 2 would subscribe to `myservice.requests.v2`. Launch instances of your service \(don't forget about queue subscribers and load balancing\).
Update the configuration file to redirect some portion of the requests made to `myservice.requests`
to version 2 of your service. In this case we'll use 2%.
Update the configuration file to redirect some portion of the requests made to `myservice.requests` to version 2 of your service. In this case we'll use 2%.
```
```text
myservice.requests: [
{ destination: myservice.requests.v1, weight: 98% },
{ destination: myservice.requests.v2, weight: 2% }
]
```
You can [reload](../../nats_admin/signals.md) the server at this point to
make the changes with zero downtime. After reloading, 2% of your requests
will be serviced by the new version.
You can [reload](../nats_admin/signals.md) the server at this point to make the changes with zero downtime. After reloading, 2% of your requests will be serviced by the new version.
Once you've determined Version 2 stable switch 100% of the traffic over and
reload the server with a new configuration.
Once you've determined Version 2 stable switch 100% of the traffic over and reload the server with a new configuration.
```
```text
myservice.requests: [
{ destination: myservice.requests.v2, weight: 100% }
]
@ -110,11 +96,9 @@ Now shutdown the version 1 instances of your service.
## Traffic Shaping in Testing
Traffic shaping is useful in testing. You might have a service that runs in QA
that simulates failure scenarios which could receive 20% of the traffic to test
the service requestor.
Traffic shaping is useful in testing. You might have a service that runs in QA that simulates failure scenarios which could receive 20% of the traffic to test the service requestor.
```
```text
myservice.requests.*: [
{ destination: myservice.requests.$1, weight: 80% },
{ destination: myservice.requests.fail.$1, weight: 20% }
@ -123,20 +107,15 @@ the service requestor.
## Artificial Loss
Alternatively, introduce loss into your system for chaos testing by
mapping a percentage of traffic to the same subject. In this
drastic example, 50% of the traffic published to `foo.loss.a` would
be artificially dropped by the server.
Alternatively, introduce loss into your system for chaos testing by mapping a percentage of traffic to the same subject. In this drastic example, 50% of the traffic published to `foo.loss.a` would be artificially dropped by the server.
```
```text
foo.loss.>: [ { destination: foo.loss.>, weight: 50% } ]
```
You can both split and introduce loss for testing. Here, 90% of requests
would go to your service, 8% would go to a service simulating failure conditions,
and the unaccounted for 2% would simulate message loss.
You can both split and introduce loss for testing. Here, 90% of requests would go to your service, 8% would go to a service simulating failure conditions, and the unaccounted for 2% would simulate message loss.
```
```text
myservice.requests: [
{ destination: myservice.requests.v3, weight: 90% },
{ destination: myservice.requests.v3.fail, weight: 8% }
@ -144,6 +123,5 @@ and the unaccounted for 2% would simulate message loss.
]
```
*Note: Subject Mapping and Traffic Shaping are also supported in the NATS
JWT model, although currently only through the [JWT API](https://github.com/nats-io/jwt).
`nsc` tooling support for subject mapping is coming soon.*
_Note: Subject Mapping and Traffic Shaping are also supported in the NATS JWT model, although currently only through the_ [_JWT API_](https://github.com/nats-io/jwt)_. `nsc` tooling support for subject mapping is coming soon._

2
whats_new_22.md
View File

@ -65,7 +65,7 @@ Why wait for timeouts when services aren’t available? When a request is made t
### Subject Mapping and Traffic Shaping
Reduce risk when onboarding new services. Canary deployments, A/B testing, and transparent teeing of data streams are now fully supported in NATS. The NATS Server allows accounts to form subject mappings from one subject to another for both client inbound and service import invocations and allows weighted sets for the destinations. Map any percentage - 1 to 100 percent of your traffic - to other subjects, and change this at runtime with a server configuration reload. You can even artificially drop a percentage of traffic to introduce chaos testing in to your system.
Reduce risk when onboarding new services. Canary deployments, A/B testing, and transparent teeing of data streams are now fully supported in NATS. The NATS Server allows accounts to form subject mappings from one subject to another for both client inbound and service import invocations and allows weighted sets for the destinations. Map any percentage - 1 to 100 percent of your traffic - to other subjects, and change this at runtime with a server configuration reload. You can even artificially drop a percentage of traffic to introduce chaos testing into your system. See [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping.md) in NATS Server configuration for more details.
### Account Monitoring - More Meaningful Metrics