From 8a81a6d4a82f344426bb0cc27ee932d60044b14e Mon Sep 17 00:00:00 2001 From: Ginger Collison Date: Mon, 3 May 2021 14:35:12 +0000 Subject: [PATCH] GitBook: [master] 7 pages modified --- SUMMARY.md | 2 +- jetstream/concepts/streams.md | 2 +- nats-protocol/nats-protocol/README.md | 2 +- nats-protocol/nats-server-protocol.md | 2 +- .../{subject_mapping => }/subject_mapping.md | 72 +++++++------------ whats_new_22.md | 2 +- 6 files changed, 30 insertions(+), 52 deletions(-) rename nats-server/configuration/{subject_mapping => }/subject_mapping.md (55%) diff --git a/SUMMARY.md b/SUMMARY.md index d78d016..c5a2046 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -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) diff --git a/jetstream/concepts/streams.md b/jetstream/concepts/streams.md index 58ab6fd..e4e7aef 100644 --- a/jetstream/concepts/streams.md +++ b/jetstream/concepts/streams.md @@ -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 | diff --git a/nats-protocol/nats-protocol/README.md b/nats-protocol/nats-protocol/README.md index e0fc7ab..83f76b1 100644 --- a/nats-protocol/nats-protocol/README.md +++ b/nats-protocol/nats-protocol/README.md @@ -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. diff --git a/nats-protocol/nats-server-protocol.md b/nats-protocol/nats-server-protocol.md index 8a006a8..eee0269 100644 --- a/nats-protocol/nats-server-protocol.md +++ b/nats-protocol/nats-server-protocol.md @@ -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. diff --git a/nats-server/configuration/subject_mapping/subject_mapping.md b/nats-server/configuration/subject_mapping.md similarity index 55% rename from nats-server/configuration/subject_mapping/subject_mapping.md rename to nats-server/configuration/subject_mapping.md index 7bb8b26..078bb7c 100644 --- a/nats-server/configuration/subject_mapping/subject_mapping.md +++ b/nats-server/configuration/subject_mapping.md @@ -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 `$`. 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 `$`. 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._ + diff --git a/whats_new_22.md b/whats_new_22.md index 00bea6c..1721083 100644 --- a/whats_new_22.md +++ b/whats_new_22.md @@ -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