# Table of Contents - [Welcome | NATS Docs](#welcome-nats-docs) - [NATS 2.12 | NATS Docs](#nats-2-12-nats-docs) - [What's New! | NATS Docs](#what-s-new-nats-docs) - [NATS 2.11 | NATS Docs](#nats-2-11-nats-docs) - [NATS 2.2 | NATS Docs](#nats-2-2-nats-docs) - [Core NATS | NATS Docs](#core-nats-nats-docs) - [Request-Reply Walkthrough | NATS Docs](#request-reply-walkthrough-nats-docs) - [Publish-Subscribe | NATS Docs](#publish-subscribe-nats-docs) - [What is NATS | NATS Docs](#what-is-nats-nats-docs) - [Walkthrough Setup | NATS Docs](#walkthrough-setup-nats-docs) - [Request-Reply | NATS Docs](#request-reply-nats-docs) - [Subject-Based Messaging | NATS Docs](#subject-based-messaging-nats-docs) - [Queueing Walkthrough | NATS Docs](#queueing-walkthrough-nats-docs) - [Overview | NATS Docs](#overview-nats-docs) - [Pub/Sub Walkthrough | NATS Docs](#pub-sub-walkthrough-nats-docs) - [Example | NATS Docs](#example-nats-docs) - [Example | NATS Docs](#example-nats-docs) - [Compare NATS | NATS Docs](#compare-nats-nats-docs) - [NATS 2.10 | NATS Docs](#nats-2-10-nats-docs) - [JetStream Walkthrough | NATS Docs](#jetstream-walkthrough-nats-docs) - [Queue Groups | NATS Docs](#queue-groups-nats-docs) - [Key/Value Store | NATS Docs](#key-value-store-nats-docs) - [Source and Mirror Streams | NATS Docs](#source-and-mirror-streams-nats-docs) - [Object Store | NATS Docs](#object-store-nats-docs) - [Key/Value Store Walkthrough | NATS Docs](#key-value-store-walkthrough-nats-docs) - [NATS Service Infrastructure | NATS Docs](#nats-service-infrastructure-nats-docs) - [Email Protection | Cloudflare](#email-protection-cloudflare) --- # Welcome | NATS Docs [](https://docs.nats.io/#the-official-nats-documentation) The official [NATS](https://nats.io/) documentation ------------------------------------------------------------------------------------------------------------------- NATS is a simple, secure and high performance open source data layer for cloud native applications, IoT messaging, and microservices architectures. We feel that it should be the backbone of your communication between services. It doesn't matter what language, protocol, or platform you are using; NATS is the best way to connect your services. ### [](https://docs.nats.io/#id-10-000-foot-view) 10,000 foot view * Publish and subscribe to messages at millions of messages per second. At most once delivery. * Supports fan-in/out delivery patterns * Request/reply * Every major language is supported * Persistence via JetStream * at least once delivery or **exactly once** delivery * work queues * stream processing * data replication * data retention * data deduplication * Higher order data structures * Key/Value with watchers, versioning, and TTL * Object storage with versioning * Security * TLS * JWT-based zero trust security * Clustering * High availability * Fault tolerance * Auto-discovery * Protocols supported * TCP * MQTT * WebSockets All of this in a single binary that is easy to deploy and manage. No external dependencies, just drop it in and add a configuration file to point to other NATS servers and you are ready to go. In fact, you can even embed NATS in your application (for Go users)! [](https://docs.nats.io/#guided-tour) Guided tour ------------------------------------------------------ 1. In general we recommend trying to solve your problems first using [Core NATS](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/core-nats/README.md) . 2. If you need to share state between services, take a look at the [KV](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/jetstream/key-value-store/README.md) or [Object Store](https://docs.nats.io/nats-concepts/jetstream/obj_store) in JetStream. 3. When you need lower level access to persistence streams, move on to using [JetStream](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/jetstream/README.md) directly for more advanced messaging patterns. 4. Learn about [deployment strategies](https://docs.nats.io/nats-concepts/service_infrastructure/adaptive_edge_deployment) 5. Secure your deployments with [zero trust security](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt) [](https://docs.nats.io/#contribute) Contribute ---------------------------------------------------- NATS is Open Source as is this documentation. Please [let us know](https://docs.nats.io/cdn-cgi/l/email-protection#d8b1b6beb798b6b9acabf6b1b7) if you have updates and/or suggestions for these docs. You can also create a Pull Request using the `Edit on GitHub` link on each page. [](https://docs.nats.io/#additional-questions) Additional questions? ------------------------------------------------------------------------- Feel free to chat with us on Slack [slack.nats.io](https://slack.nats.io/) . Thank you from the entire NATS Team of Maintainers for your interest in NATS! [NextWhat's New!](https://docs.nats.io/release-notes/whats_new) Last updated 3 months ago Was this helpful? --- # NATS 2.12 | NATS Docs This guide is tailored for existing NATS users upgrading from NATS version v2.11.x. This will read as a summary with links to specific documentation pages to learn more about the feature or improvement. [](https://docs.nats.io/release-notes/whats_new/whats_new_212#features) Features ------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#streams) Streams * **Atomic batch publish:** The `AllowAtomicPublish` stream configuration option allows to atomically publish N messages into a stream. This includes support for replicated and non-replicated streams, as well as doing per-message consistency checks prior to committing the batch. More information is available in [ADR-50](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-50.md) . * **Distributed Counter CRDT:** The `AllowMsgCounter` stream configuration option allows increment/decrement counter semantics on a stream. These counter streams can also be mirrored or aggregated through stream mirroring and sourcing. More information is available in [ADR-49](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-49.md) * **Delayed Message Scheduling:** The `AllowMsgSchedules` stream configuration option allows the scheduling of messages. Users can use this feature for delayed publishing/scheduling of messages. More information is available in [ADR-51](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-51.md) ### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#consumers) Consumers * **Prioritized pull consumer policy:** In addition to the consumer policies like overflow or client pinning, a new `prioritized` policy has been added. In contrast with the overflow policy, this allows a consumer to receive messages sooner instead of delaying failover, but at the cost of potentially flip-flopping work between clients. More information is available in [ADR-42](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-42.md#prioritized-policy) ### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#operations) Operations * **Server metadata:** Similar to `server_tags` which contains a set of tags describing the server, `server_metadata` is a map containing string keys and values describing metadata of the server. * **Promoting mirrors:** A stream that’s mirroring can now be promoted to be the primary, enabling new disaster recovery methodology. The current primary stream should be deleted or have its configured subjects removed prior to promoting mirrors, before configuring the promoted mirrors to start listening on those subjects. * **Exponential backoff on route and gateway connections:** Cluster routes and gateways can now use exponential backoff on reconnection attempts by setting `connect_backoff`. If `true`, will start exponential backoff at 1 second up to 30 seconds. This can slow down the speed of reconnection but significantly reduces the amount of DNS queries and general connection attempts during server restarts or outages. * **Offline assets:** When downgrading to an older version, the server can now recognize new features were used and puts the stream and/or consumer into an unsupported/offline mode. For more information, read also the downgrade considerations. More information is available in [ADR-44](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-44.md#offline-assets) * **Stream/consumer scaleup and reset disk/state protection:** The server now has better protections against leader elections based on empty state. This also improves reliability of replicated in-memory streams. Usually a quorum of servers needs to be online and contain data. Now all but one server can be restarted and the in-memory stream’s data can reliably be caught back up. However, during such a scenario all servers involved with replication of that stream will need to be available, not just what’s needed for quorum. This lets the servers decide the best course of action to preserve all data. [](https://docs.nats.io/release-notes/whats_new/whats_new_212#improvements) Improvements --------------------------------------------------------------------------------------------- * **Async stream flushing:** Replicated streams will now asynchronously flush data to the underlying store on disk, resulting in a significant improvement in performance. Writes to a replicated stream are still persisted synchronously in the Raft log prior to committing them, so the improved performance has no downsides with respect to consistency. * **Elastic pointers in the filestore:** File-based streams now use elastic pointers for its write-through caches. This allows the server to better respond during garbage collection, these caches can be evicted early to avoid out-of-memory conditions (see upgrade considerations below). * **Use cipher suites from** `**crypto/tls**`**:** New cipher suites are now automatically added. Additionally, insecure cipher suites are disabled by default, but can be allowed when enabling `allow_insecure_cipher_suites`. * **System events for the** `**$G**` **account:** The global account (`$G`) will now also produce system events, such as connect and disconnect events. * `**GOMAXPROCS**` **and** `**GOMEMLIMIT**` **in server stats:** The server stats already contained the CPU and memory usage of the server but now also contains the effective Go limits. * **New subject transforms:** `**partition(n)**` **and** `**random(n)**`**:** In addition to `partition(n, …)` which allows to determine a partition number based on tokens at specified indices, `partition(n)` and `random(n)` are convenience functions to create a partition or random number up to `n` based on the whole subject. * **Account name and user logging:** Any logging related to a client connection, for example when reaching maximum connections or for authentication errors, will now include the account name and user of that client connection. * **Logging improvements:** Any logging related to a client connection now includes the account and user name. Connection closed logging now includes the remote server name. * **Isolated leaf node property:** In a large deployment with lots of leaf nodes, propagating east-west interest can result in a lot of traffic, which is wasted if leaf nodes don't need to be able to publish/subscribe to each other directly. Instead of the workaround of setting the cluster name of those leaf nodes to be the same, the `isolate_leafnode_interest` property can now be used. * **Disable leaf node connection through config reload:** This allows disabling a remote leaf node using configuration reload, when using `disabled: true`. If changed from false to true, a solicited leaf node will be disconnected and will not reconnect. If changed from true to false, the leafnode will be solicited again. [](https://docs.nats.io/release-notes/whats_new/whats_new_212#upgrade-considerations) Upgrade Considerations ----------------------------------------------------------------------------------------------------------------- #### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#memory-usage) Memory usage With the new elastic pointers in the filestore, it is expected that a NATS Server running 2.12 may show a different memory usage pattern to before. In some systems this may result in lower resident set size (RSS) reported, in others it may result in higher, depending on the number of assets and publish/access patterns. For the first time, the server will be able to respond to memory pressure by freeing filestore caches on demand and returning the memory to the operating system. This reduces the chance that sudden spikes in utilisation will result in an out-of-memory (OOM) kill. However, this means that the server can more optimistically retain caches in memory when available resources allow in order to facilitate improved read access times. This behaviour is largely controlled by the GC thresholds as set by the `GOMEMLIMIT` [environment variable](https://tip.golang.org/doc/gc-guide#Memory_limit) . You may wish to tune this value in your environment based on available system memory, or in the case of Kubernetes environments, memory reservations. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#strict-jetstream-api) Strict JetStream API Starting from version v2.11, the server would start logging the following statement if an invalid JetStream request was received: Copy [WRN] Invalid JetStream request '$G > $JS.API.STREAM.CREATE.test-stream': json: unknown field "unknown" Starting from version v2.12, the server will not only log, but also return an error to the client as “strict mode” is now enabled by default. This means invalid JetStream requests will be rejected by default. If the above log message is observed, please make sure that the application or client is sending correct requests to the server and that NATS client libraries are up-to-date. Strict mode can be temporarily disabled in the server configuration, allowing you more time to fix the issue: Copy jetstream { strict: false } [](https://docs.nats.io/release-notes/whats_new/whats_new_212#downgrade-considerations) Downgrade Considerations --------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nats.io/release-notes/whats_new/whats_new_212#stream-state) Stream state When downgrading from v2.12 to v2.11, the stream state files on disk will be rebuilt due to a change in the format of these files in v2.12. This requires re-scanning all stream message blocks, which may use higher CPU than usual and will likely take longer for the restarted node to report healthy. This will only happen on the first restart after downgrading and will not result in data loss. When downgrading, only downgrade to v2.11.9 or higher. Starting from this version, the server will recognize the use of new v2.12 features and will safely put the stream and/or consumer that uses these new features into an unsupported/offline mode. Importantly, this will both protect the data as well as the server itself from accessing unsupported features or data. [PreviousWhat's New!](https://docs.nats.io/release-notes/whats_new) [NextNATS 2.11](https://docs.nats.io/release-notes/whats_new/whats_new_211) Last updated 1 month ago Was this helpful? --- # What's New! | NATS Docs The NATS.io team is continually working to bring you features that enhance your NATS experience. Below, you will find summaries of new NATS implementations. Release notes for the latest patch releases are available on [GitHub Releases](https://github.com/nats-io/nats-server/releases) [](https://docs.nats.io/release-notes/whats_new#roadmap-for-future-releases) Roadmap for future releases ------------------------------------------------------------------------------------------------------------- See [https://nats.io/about/#roadmap](https://nats.io/about/#roadmap) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.12.0) Server release v2.12.0 --------------------------------------------------------------------------------------------------- Check out the: * [Upgrade guide](https://docs.nats.io/release-notes/whats_new/whats_new_212) * [Release notes](https://github.com/nats-io/nats-server/releases/tag/v2.12.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.11.0) Server release v2.11.0 --------------------------------------------------------------------------------------------------- Check out the: * [Upgrade guide](https://docs.nats.io/release-notes/whats_new/whats_new_211) * [Release notes](https://github.com/nats-io/nats-server/releases/tag/v2.11.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.10.0) Server release v2.10.0 --------------------------------------------------------------------------------------------------- Check out the: * [Upgrade guide](https://docs.nats.io/release-notes/whats_new/whats_new_210) * [Podcast EP06: The journey and features of the NATS.io 2.10 release](https://youtu.be/9J4pRzHSc2k) * [Release notes](https://github.com/nats-io/nats-server/releases/tag/v2.10.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.9.0) Server release v2.9.0 ------------------------------------------------------------------------------------------------- Please check out the [announcement post](https://nats.io/blog/nats-server-29-release/) on the blog and the [detailed release notes](https://github.com/nats-io/nats-server/releases/tag/v2.9.0) in the server repo. [](https://docs.nats.io/release-notes/whats_new#server-release-v2.8.0) Server release v2.8.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#leafnode) LeafNode Support for a `min_version` in the `leafnodes{}` that would reject servers with a lower version. Note that this would work only for servers that are v2.8.0 and above. ### [](https://docs.nats.io/release-notes/whats_new#monitoring) Monitoring * Server version in monitoring landing page. * Logging to `/healthz` endpoint when failure occurs. * MQTT and Websocket blocks in the `/varz` endpoint. ### [](https://docs.nats.io/release-notes/whats_new#jetstream) JetStream * Consumer check added to `healthz` endpoint. * Max stream bytes checks. * Ability to limit a consumer's `MaxAckPending` value. * Allow streams and consumers to migrate between clusters. _This feature is considered "beta"_. * New `unique_tag` option in `jetstream{}` configuration block to prevent placing a stream in the same availability zone twice. * Stream `Alternates` field in `StreamInfo` response. They provide a priority list of mirrors and the source in relation to where the request originated. * Deterministic subject tokens to partition mapping. For full release information, see links below; * Release notes [2.8.0](https://github.com/nats-io/nats-server/releases/tag/v2.8.0) * Full list of Changes [2.7.4...2.8.0](https://github.com/nats-io/nats-server/compare/v2.7.4...v2.8.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.7.0) Server release v2.7.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#notice-for-jetstream-users) **Notice for JetStream Users** See [important note](https://github.com/nats-io/nats-server/pull/2693#issuecomment-996212582) if using LeafNode regarding domains. ### [](https://docs.nats.io/release-notes/whats_new#configuration) Configuration Ability to configure account limits (`max_connections`, `max_subscriptions`, `max_payload`, `max_leafnodes`) in server configuration file. ### [](https://docs.nats.io/release-notes/whats_new#jetstream-1) JetStream * Overflow placement for streams. A stream can now be placed in the closest cluster from the origin request if it can be placed there. * Support for ephemeral Pull consumers (client libraries will need to be updated to allow those). * New consumer configuration options * For Pull Consumers: `MaxRequestBatch` to limit the batch size any client can request `MaxRequestExpires` to limit the expiration any client can request * For ephemeral consumers: `InactiveThreshold` duration that instructs the server to cleanup ephemeral consumers that are inactive for that long. * Ability to configure `max_file_store` and `max_memory_store` in the `jetstream{}` block as strings with the following suffixes `K`, `M`, `G` and `T`, for instance: `max_file_store: "256M"`. * Support for the JWT field `MaxBytesRequired`, which defines a per-account maximum bytes for assets. ### [](https://docs.nats.io/release-notes/whats_new#mqtt) MQTT Support for websocket protocol. MQTT clients must connect to the opened websocket port and add `/mqtt` to the URL path. ### [](https://docs.nats.io/release-notes/whats_new#tls) TLS Ability to rate-limit the clients connections by adding the `connection_rate_limit: ` in the `tls{}` top-level block. For full release information, see links below; * Release notes [2.7.0](https://github.com/nats-io/nats-server/releases/tag/v2.7.0) * Full list of Changes [2.6.6...2.7.0](https://github.com/nats-io/nats-server/compare/v2.6.6...v2.7.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.6.0) Server release v2.6.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#notice-for-jetstream-users-1) **Notice for JetStream Users** See important [note](https://github.com/nats-io/nats-server/releases/tag/v2.4.0) if upgrading from a version prior to NATS Server v2.4.0. ### [](https://docs.nats.io/release-notes/whats_new#notice-for-mqtt-users) Notice for MQTT Users See important [notes](https://github.com/nats-io/nats-server/releases/tag/v2.5.0) if upgrading from a version prior to v2.5.0. ### [](https://docs.nats.io/release-notes/whats_new#monitoring-1) Monitoring * JetStream's reserved memory and memory used from accounts with reservations in `/jsz` and `/varz` endpoints. * Hardened systemd service. For full release information, see links below; * Release notes [2.6.0](https://github.com/nats-io/nats-server/releases/tag/v2.6.0) * Full list of Changes [2.5.0...2.6.0](https://github.com/nats-io/nats-server/compare/v2.6.0...v2.5.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.5.0) Server release v2.5.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#notice-for-jetstream-users-2) **Notice for JetStream Users** See important [note](https://github.com/nats-io/nats.docs/blob/master/release_notes/README.md#notice-for-jetstream-users) if upgrading from a version prior to NATS Server v2.4.0. ### [](https://docs.nats.io/release-notes/whats_new#mqtt-monitoring) MQTT/Monitoring * `MQTTClient` in the `/connz` connections report and system events CONNECT and DISCONNECT. Ability to select on `mqtt_client`. ### [](https://docs.nats.io/release-notes/whats_new#mqtt-improvement) MQTT Improvement * Sessions are now all stored inside a single stream, as opposed to individual streams, reducing resources usage. ### [](https://docs.nats.io/release-notes/whats_new#mqtt-update) MQTT Update * Due to the aforementioned improvement described above, when an MQTT client connects for the first time after an upgrade to this server version, the server will migrate all individual `$MQTT_sess_` streams to a new `$MQTT_sess` stream for the user's account. For full release information, see links below; * Release notes [2.5.0](https://github.com/nats-io/nats-server/releases/tag/v2.5.0) * Full list of Changes [2.4.0...2.5.0](https://github.com/nats-io/nats-server/compare/v2.4.0...v2.5.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.4.0) Server release v2.4.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#notice-for-jetstream-users-3) Notice for JetStream Users With the latest release of the NATS server, we have fixed bugs around queue subscriptions and have restricted undesired behavior that could be confusing or introduce data loss by unintended/undefined behavior of client applications. If you are using queue subscriptions on a JetStream Push Consumer or have created multiple push subscriptions on the same consumer, you may be affected and need to upgrade your client version along with the server version. We’ve detailed the behavior with different client versions below. With a NATS Server **prior** to v2.4.0 and client libraries **prior** to these versions: NATS C client v3.1.0, Go client v1.12.0, Java client 2.12.0-SNAPSHOT, NATS.js v2.2.0, NATS.ws v1.3.0, NATS.deno v1.2.0, NATS .NET 0.14.0-pre2: * It was possible to create multiple non-queue subscription instances for the same JetStream durable consumer. This is not correct since each instance will receive the same copy of a message and acknowledgment is therefore meaningless since the first instance to acknowledge the message will prevent other instances to control if/when a message should be acknowledged. * Similar to the first issue, it was possible to create many different queue groups for one single JetStream consumer. * For queue subscriptions, if no consumer nor durable name was provided, the libraries would create ephemeral JetStream consumers, which meant that each member of the same group would receive the same message as the other members, which was not the expected behavior. Users assumed that 2 members subscribing to “foo” with the queue group named “bar” would load-balance the consumption of messages from the stream/consumer. * It was possible to create a queue subscription on a JetStream consumer configured with heartbeat and/or flow control. This does not make sense because by definition, queue members would receive some (randomly distributed) messages, so the library would think that heartbeats are missed, and flow control would also be disrupted. If above client libraries are not updated to the latest but the NATS Server is upgraded to v2.4.0: * It is still possible to create multiple non-queue subscription instances for the same JetStream durable consumer. Since the check is performed by the library (with the help of a new field called `PushBound` in the consumer information object set by the server), this misbehavior is still possible. * Queue subscriptions will not receive any message. This is because the server now has a new field `DeliverGroup` in the consumer configuration, which won’t be set for existing JetStream consumers and by the older libraries, and detects interest (and starts delivering) only when a subscription on the deliver subject for a queue subscription matching the “deliver group” name is found. Since the JetStream consumer is thought to be a non-deliver-group consumer, the opposite happens: the server detects a core NATS _queue_ subscription on the “deliver subject”, therefore does not trigger delivery on the JetStream consumer’s “deliver subject”. The 2 other issues are still present because those checks are done in the updated libraries. If the above client libraries are updated to the latest version, but the NATS Server is still to version prior to v2.4.0 (that is, up to v2.3.4): * It is still possible to create multiple non-queue subscription instances for the same JetStream durable consumer. This is because the JetStream consumer’s information retrieved by the library will not have the `PushBound` boolean set by the server, therefore will not be able to alert the user that they are trying to create multiple subscription instances for the same JetStream consumer. * Queue subscriptions will fail because the consumer information returned will not contain the `DeliverGroup` field. The error will be likely to the effect that the user tries to create a queue subscription to a non-queue JetStream consumer. Note that if the application creates a queue subscription for a non-yet created JetStream consumer, then this call will succeed, however, adding new members or restarting the application with the now existing JetStream consumer will fail. * Creating queue subscriptions without a named consumer/durable will now result in the library using the queue name as the durable name. * Trying to create a queue subscription with a consumer configuration that has heartbeat and/or flow control will now return an error message. For completeness, using the latest client libraries and NATS Server v2.4.0: * Trying to start multiple non-queue subscriptions instances for the same JetStream consumer will now return an error to the effect that the user is trying to create a “duplicate subscription”. That is, there is already an active subscription on that JetStream consumer. It is now only possible to create a queue group for a JetStream consumer created for that group. The `DeliverGroup` field will be set by the library or need to be provided when creating the consumer externally. * Trying to create a queue subscription without a durable nor consumer name results in the library creating/using the queue group as the JetStream consumer’s durable name. * Trying to create a queue subscription with a consumer configuration that has heartbeat and/or flow control will now return an error message. Note that if the server v2.4.0 recovers existing JetStream consumers that were created prior to v2.4.0 (and with older libraries), none of them will have a `DeliverGroup`, so none of them can be used for queue subscriptions. They will have to be recreated. ### [](https://docs.nats.io/release-notes/whats_new#jetstream-2) JetStream * Domain to the content of a `PubAck` protocol * `PushBound` boolean in `ConsumerInfo` to indicate that a push consumer is already bound to an active subscription * `DeliverGroup` string in `ConsumerConfig` to specify which deliver group (or queue group name) the consumer is created for * Warning log statement in situations where catchup for a stream resulted in an error ### [](https://docs.nats.io/release-notes/whats_new#monitoring-2) Monitoring * The ability for normal accounts to access scoped `connz` information ### [](https://docs.nats.io/release-notes/whats_new#misc) Misc * Operator option `resolver_pinned_accounts` to ensure users are signed by certain accounts For full release information, see links below; * Release notes [2.4.0](https://github.com/nats-io/nats-server/releases/tag/v2.4.0) * Full list of Changes [2.3.4...2.4.0](https://github.com/nats-io/nats-server/compare/v2.3.4...v2.4.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.3.0) Server release v2.3.0 ------------------------------------------------------------------------------------------------- * [OCSP support](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/ocsp) ### [](https://docs.nats.io/release-notes/whats_new#jetstream-3) JetStream * Richer API errors. JetStream errors now contain an ErrCode that uniquely describes the error. * Ability to send more advanced Stream purge requests that can purge all messages for a specific subject * Stream can now be configured with a per-subject message limit * Encryption of JetStream data at rest For full release information, see links below; * Release notes [2.3.0](https://github.com/nats-io/nats-server/releases/tag/v2.3.0) * Full list of Changes [2.2.6...2.3.0](https://github.com/nats-io/nats-server/compare/v2.2.6...v2.3.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.2.0) Server release v2.2.0 ------------------------------------------------------------------------------------------------- See [NATS 2.2](https://docs.nats.io/release-notes/whats_new/whats_new_22) for new features. [](https://docs.nats.io/release-notes/whats_new#server-release-v2.1.7) Server release v2.1.7 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#monitoring-endpoints-available-via-system-services) Monitoring Endpoints Available via System Services Monitoring endpoints as listed in the table below are accessible as system services using the following subject pattern: * `$SYS.REQ.SERVER..` (request server monitoring endpoint corresponding to endpoint name.) * `$SYS.REQ.SERVER.PING.` (from all server request server monitoring endpoint corresponding to endpoint name - will return multiple messages) For more information on monitoring endpoints see [NATS Server Configurations System Events](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts) . ### [](https://docs.nats.io/release-notes/whats_new#addition-of-no_auth_user-configuration) Addition of `no_auth_user` Configuration Configuration of `no_auth_user` allows you to refer to a configured user/account when no credentials are provided. For more information and examples, see [Securing NATS](https://docs.nats.io/running-a-nats-service/configuration/securing_nats) For full release information, see links below; * Release notes [2.1.7](https://github.com/nats-io/nats-server/releases/tag/v2.1.7) * Full list of Changes [2.1.6...2.1.7](https://github.com/nats-io/nats-server/compare/v2.1.6...v2.1.7) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.1.6) Server release v2.1.6 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#tls-configuration-for-account-resolver) TLS Configuration for Account Resolver This release adds the ability to specify TLS configuration for the account resolver. Copy resolver_tls { cert_file: ... key_file: ... ca_file: ... } ### [](https://docs.nats.io/release-notes/whats_new#additional-trace-and-debug-verbosity-options) Additional Trace & Debug Verbosity Options `trace_verbose` and command line parameters `-VV` and `-DVV` added. See [NATS Logging Configuration](https://docs.nats.io/running-a-nats-service/configuration/logging#configuring-logging) ### [](https://docs.nats.io/release-notes/whats_new#subscription-details-in-monitoring-endpoints) Subscription Details in Monitoring Endpoints We've added the option to include subscription details in monitoring endpoints `/routez` and `/connz`. For instance `/connz?subs=detail` will now return not only the subjects of the subscription, but the queue name (if applicable) and some other details. * Release notes [2.1.6](https://github.com/nats-io/nats-server/releases/tag/v2.1.6) * Full list of Changes [2.1.4...2.1.6](https://github.com/nats-io/nats-server/compare/v2.1.4...v2.1.6) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.1.4) Server release v2.1.4 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#log-rotation) Log Rotation NATS introduces `logfile_size_limit` allowing auto-rotation of log files when the size is greater than the configured limit set in `logfile_size_limit` as a number of bytes. You can provide the size with units, such as MB, GB, etc. The backup files will have the same name as the original log file with the suffix .yyyy.mm.dd.hh.mm.ss.micros. For more information see Configuring Logging in the [NATS Server Configuration section](https://docs.nats.io/running-a-nats-service/configuration/logging) . * Release notes [2.1.4](https://github.com/nats-io/nats-server/releases/tag/v2.1.4) * Full list of Changes [2.1.2...2.1.4](https://github.com/nats-io/nats-server/compare/v2.1.2...v2.1.4) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.1.2) Server release v2.1.2 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#queue-permissions) Queue Permissions Queue Permissions allow you to express authorization for queue groups. As queue groups are integral to implementing horizontally scalable microservices, control of who is allowed to join a specific queue group is important to the overall security model. Original PR - [https://github.com/nats-io/nats-server/pull/1143](https://github.com/nats-io/nats-server/pull/1143) More information on Queue Permissions can be found in the [Developing with NATS](https://docs.nats.io/using-nats/developer/receiving/queues) section. [](https://docs.nats.io/release-notes/whats_new#server-release-v2.1.0) Server release v2.1.0 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#service-latency-tracking) Service Latency Tracking As services and service mesh functionality has become prominent, we have been looking at ways to make running scalable services on NATS.io a great experience. One area we have been looking at is observability. With publish/subscribe systems, everything is inherently observable, however we realized it was not as simple as it could be. We wanted the ability to transparently add service latency tracking to any given service with no changes to the application. We also realized that global systems, such as those NATS.io can support, needed something more than a single metric. The solution was to allow any sampling rate to be attached to an exported service, with a delivery subject for all collected metrics. We collect metrics that show the requestor’s view of latency, the responder’s view of latency and the NATS subsystem itself, even when requestor and responder are in different parts of the world and connected to different servers in a NATS supercluster. * Release notes [2.1.0](https://github.com/nats-io/nats-server/releases/tag/v2.1.0) * Full list of Changes [2.0.4...2.1.0](https://github.com/nats-io/nats-server/compare/v2.0.4...v2.1.0) [](https://docs.nats.io/release-notes/whats_new#server-release-v2.0.4) Server release v2.0.4 ------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new#response-only-permissions) Response Only Permissions For services, the authorization for responding to requests usually included wildcards for \_INBOX.> and possibly $GR.> with a supercluster for sending responses. What we really wanted was the ability to allow a service responder to only respond to the reply subject it was sent. ### [](https://docs.nats.io/release-notes/whats_new#response-types) Response Types Exported Services were originally tied to a single response. We added the type for the service response and now support singletons (default), streams and chunked. Stream responses represent multiple response messages, chunked represents a single response that may have to be broken up into multiple messages. * Release notes [2.0.4](https://github.com/nats-io/nats-server/releases/tag/v2.0.4) * Full list of Changes [2.0.2...2.0.4](https://github.com/nats-io/nats-server/compare/v2.0.2...v2.0.4) [PreviousWelcome](https://docs.nats.io/) [NextNATS 2.12](https://docs.nats.io/release-notes/whats_new/whats_new_212) Last updated 1 month ago Was this helpful? --- # NATS 2.11 | NATS Docs This guide is tailored for existing NATS users upgrading from NATS version v2.10.x. This will read as a summary with links to specific documentation pages to learn more about the feature or improvement. [](https://docs.nats.io/release-notes/whats_new/whats_new_211#features) Features ------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#observability) Observability * **Distributed message tracing:** Users can now trace messages as they move through the system by setting a `Nats-Trace-Dest` header to an inbox subject. Servers on the message path will return events to the provided subject that report each time a message enters or leaves a server, by which connection type, when subject mappings occur, or when messages traverse an account import/export boundary. Additionally, the `Nats-Trace-Only` header (if set to true) will allow tracing events to propagate on a specific subject without delivering them to subscribers of that subject. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#streams) Streams * **JetStream per-message TTLs:** It is now possible to age out individual messages using a per-message TTL. The `Nats-TTL` header, in either string or integer format (in seconds) allows for individual message expiration independent of stream limits. This can be combined with other limits in place on the stream. More information is available in [ADR-43](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-43.md) . * **Subject delete markers on MaxAge:** The `SubjectDeleteMarkerTTL` stream configuration option now allows for the placement of delete marker messages in the stream when the configured `MaxAge` limit causes the last message for a given subject to be deleted. The delete markers include a `Nats-Marker-Reason` header explaining which limit was responsible for the deletion. * **Stream ingest rate limiting:** New options `max_buffered_size` and `max_buffered_msgs` in the `jetstream` configuration block enable rate limiting on Core NATS publishing into JetStream streams, protecting the system from overload. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#consumers) Consumers * **Pull consumer priority groups:** Pull consumers now support priority groups with pinning and overflow, enabling flexible failover and priority management when multiple clients are pulling from the same consumer. Configurable policies based on the number of pending messages on the consumer, or the number of pending acks, can control when messages overflow from one client to another, enabling new design patterns or regional awareness. * **Consumer pausing:** Message delivery to consumers can be temporarily suspended using the new pause API endpoint (or the `PauseUntil` configuration option when creating), ideal for maintenance or migrations. Message delivery automatically resumes once the configured deadline has passed. Consumer clients continue to receive heartbeat messages as usual to ensure that they do not surface errors during the pause. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#operations) Operations * **Replication traffic in asset accounts:** Raft replication traffic can optionally be moved into the same account in which replicated assets live on a per-account basis, rather than being sent and received in the system account using the new [`cluster_traffic` property](https://docs.nats.io/running-a-nats-service/configuration#jetstream-account-settings) in the JetStream account settings of an account. When combined with multiple route connections, this can help to reduce latencies and avoid head-of-line blocking issues that may occur in heavily-loaded multi-tenant or multi-account deployments. * **TLS first on leafnode connections:** A new `handshake_first` in the leafnode `tls` block allows setting up leafnode connections that perform TLS negotiation first, before any other protocol handshakes take place. * **Configuration state digest:** A new `-t` command line flag on the server binary can generate a hash of the configuration file. The `config_digest` item in `varz` displays the hash of the currently running configuration file, making it possible to check whether a configuration file has changed on disk compared to the currently running configuration. * **TPM encryption on Windows:** When running on Windows, the filestore can now store encryption keys in the TPM, useful in environments where physical access may be a concern. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#mqtt) MQTT * **SparkplugB:** The built-in MQTT support is now compliant with SparkplugB Aware, with support for `NBIRTH` and `NDEATH` messages. [](https://docs.nats.io/release-notes/whats_new/whats_new_211#improvements) Improvements --------------------------------------------------------------------------------------------- * **Replicated delete proposals:** Message removals in clustered interest-based or workqueue streams are now propagated via Raft to guarantee consistent removal order across replicas, reducing a number of possible ways that a cluster failure can result in de-synced streams. * **Metalayer, stream and consumer consistency:** A new leader now only responds to read/write requests after synchronizing with its Raft log, preventing desynchronization between KV key updates and the stream during leader changes. * **Replicated consumer reliability:** Replicated consumers now consistently redeliver unacknowledged messages after a leader change. * **Consumer starting sequence:** The consumer starting sequence is now always respected, except for internal hidden consumers for sources/mirrors. [](https://docs.nats.io/release-notes/whats_new/whats_new_211#upgrade-considerations) Upgrade Considerations ----------------------------------------------------------------------------------------------------------------- #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#stream-ingest-rate-limiting) Stream ingest rate limiting The NATS Server can now return a 429 error with type `JSStreamTooManyRequests` when too many messages have been queued up for a stream. It should not generally be possible to hit this limit while using JetStream publishes and waiting for PubAcks, but may trigger if trying to publish into JetStream using Core NATS publishes without waiting for PubAcks, which is not advised. The new `max_buffered_size` and `max_buffered_msgs` options control how many messages can be queued for each stream before the rate limit is hit, therefore if needed, you can increase these limits on your deployments. The default values for `max_buffered_size` and `max_buffered_msgs` are 128MB and 10,000 respectively, whereas in v2.10 these were unlimited. You can detect in the server logs whether running into a queue limit with the following warning: Copy [WRN] Dropping messages due to excessive stream ingest rate on 'account' > 'my-stream': IPQ len limit reached If your application starts to log the above warnings then you can first try to increase the limits to higher values while investigating the fast publishers, for example: Copy jetstream { max_buffered_msgs: 50000 max_buffered_size: 256mib } #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#replicated-delete-proposals) Replicated delete proposals Since stream deletes are now replicated through group proposals in a replicated stream, there may be a slight increase in replication traffic on this version. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#jetstream-healthcheck) JetStream healthcheck The `js-server-only` healthcheck no longer checks for the health of the metaleader on v2.11.0. Since this healthcheck was designed to detect the server readiness (or in k8s for the readiness probe) checking the metaleader would sometimes cause a NATS server to be considered unhealthy when restarting the servers. In v2.11, this should no longer be an issue. If the previous behavior from v2.10 is preferred, there is a new healthcheck option `js-meta-only` which can be used to check whether the meta group is healthy. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#exit-code) Exit code Earlier versions of the NATS Server would return an exit code 1 when gracefully shut down, i.e. after SIGTERM. From v2.11, an exit code of 0 (zero) will now be returned instead. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#server-cluster-and-gateway-names) Server, cluster and gateway names Configurations that have server, cluster, and gateway names with spaces are now considered invalid, as this can cause problems at the protocol level. A server running NATS v2.11 will fail to start with spaces configured in these names. Please ensure that spaces are not used in server, cluster or gateway names. [](https://docs.nats.io/release-notes/whats_new/whats_new_211#downgrade-considerations) Downgrade Considerations --------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nats.io/release-notes/whats_new/whats_new_211#stream-state) Stream state When downgrading from v2.11 to v2.10, the stream state files on disk will be rebuilt due to a change in the format of these files in v2.11. This requires re-scanning all stream message blocks, which may use higher CPU than usual and will likely take longer for the restarted node to report healthy. This will only happen on the first restart after downgrading and will not result in data loss. [PreviousNATS 2.12](https://docs.nats.io/release-notes/whats_new/whats_new_212) [NextNATS 2.10](https://docs.nats.io/release-notes/whats_new/whats_new_210) Last updated 2 months ago Was this helpful? --- # NATS 2.2 | NATS Docs NATS 2.2 is the largest feature release since version 2.0. The 2.2 release provides highly scalable, highly performant, secure and easy-to-use next generation streaming in the form of JetStream, allows remote access via websockets, has simplified NATS account management, native MQTT support, and further enables NATS toward our goal of securely democratizing streams and services for the hyperconnected world we live in. [](https://docs.nats.io/release-notes/whats_new/whats_new_22#next-generation-streaming) Next Generation Streaming ---------------------------------------------------------------------------------------------------------------------- JetStream is the next generation streaming platform for NATS, highly resilient, highly available, and easy to use. We’ve spent a long time listening to our community, learning from our experiences, looking at the needs of today, and thinking deeply about the needs of tomorrow. We built JetStream to address these needs. JetStream: * is easy to deploy and manage, built into the NATS server * simplifies and accelerates development * supports wildcard subjects * supports at least once delivery and exactly once within a window * is horizontally scalable at runtime with no interruptions * persists data via streams and delivers or replays via consumers * supports multiple patterns to consume data on the same stream * supports push and pull modes when consuming messages * is account aware * allows for detailed granularity of security, by stream, by consumer, by function Get started with [JetStream](https://docs.nats.io/nats-concepts/jetstream) . [](https://docs.nats.io/release-notes/whats_new/whats_new_22#security-and-simplified-account-management) Security and Simplified Account Management -------------------------------------------------------------------------------------------------------------------------------------------------------- Account management just became much easier. This version of NATS has a built-in account management system, eliminating the need to set up an account manager when not using the memory account resolver. With automated default system account generation, and the ability to preload accounts, simply enable a set of servers in your deployment to be account resolvers or account resolver caches, and they will handle public account information provided to the NATS system through the NATS nsc tooling. Have enterprise-scale account management up and running in minutes. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#cidr-block-account-restrictions) CIDR Block Account Restrictions By specifying a CIDR block restriction for a user, policy can be applied to limit connections from clients within a certain range or set of IP addresses. Use this as another layer of security atop user credentials to better secure your distributed system. Ensure your applications can only connect from within a specific cloud, enterprise, geographic location, virtual or physical network. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#time-based-account-restrictions) Time-Based Account Restrictions Scoped to the user, you can now [specify a specific block of time](https://docs.nats.io/using-nats/nats-tools/nsc/basics#user-authorization) during the day when applications can connect. For example, permit certain users or applications to access the system during specified business hours, or protect business operations during the busiest parts of the day from batch driven back-office applications that could adversely impact the system when run at the wrong time. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#default-user-permissions) Default User Permissions Now you can specify [default user permissions](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/authorization#examples) within an account. This significantly reduces efforts around policy, reduces chances for error in permissioning, and simplifies the provisioning of user credentials. [](https://docs.nats.io/release-notes/whats_new/whats_new_22#websockets) WebSockets ---------------------------------------------------------------------------------------- Connect mobile and web applications to any NATS server using [WebSockets](https://docs.nats.io/running-a-nats-service/configuration/websocket) . Built to more easily traverse firewalls and load balancers, NATS WebSocket support provides even more flexibility to NATS deployments and makes it easier to communicate to the edge and endpoints. This is currently supported in NATS server leaf nodes, nats.ts, nats.deno, and the nats.js clients. [](https://docs.nats.io/release-notes/whats_new/whats_new_22#native-mqtt-support) Native MQTT Support ---------------------------------------------------------------------------------------------------------- With the [Adaptive Edge architecture](https://nats.io/blog/synadia-adaptive-edge/) and the ease with which NATS can extend a cloud deployment to the edge, it makes perfect sense to leverage existing investments in IoT deployments. It’s expensive to update devices and large edge deployments. Our goal is to enable the hyperconnected world, so we added first-class support for [MQTT 3.1.1](https://docs.nats.io/running-a-nats-service/configuration/mqtt) directly into the NATS Server. Seamlessly integrate existing IoT deployments using MQTT 3.1.1 with a cloud-native NATS deployment. Add a leaf node that is MQTT enabled and instantly send and receive messages to your MQTT applications and devices from a NATS deployment whether it be edge, single-cloud, multi-cloud, on-premise, or any combination thereof. [](https://docs.nats.io/release-notes/whats_new/whats_new_22#build-better-systems) Build Better Systems ------------------------------------------------------------------------------------------------------------ We’ve added a variety of features to allow you to build a more resilient, secure, and simply better system at scale. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#message-headers) Message Headers We’ve added the ability to optionally use headers, following the HTTP semantics familiar to developers. Headers naturally apply overhead, which was why we resisted adding them for so long. By creating new internal protocol messages transparent to developers, we maintain the extremely fast processing of simple NATS messages that we have always had while supporting headers for those who would like to leverage them. Adding headers to messages allows you to provide application-specific metadata, such as compression or encryption-related information, without touching the payload. We also provide some NATS specific headers for use in JetStream and other features. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#seamless-maintenance-with-lame-duck-notifications) Seamless Maintenance with Lame Duck Notifications When taking down a server for maintenance, servers can be signaled to enter [Lame Duck Mode](https://docs.nats.io/running-a-nats-service/nats_admin/lame_duck_mode) where they do not accept new connections and evict existing connections over a period of time. Maintainer supported clients will notify applications that a server has entered this state and will be shutting down, allowing a client to smoothly transition to another server or cluster and better maintain business continuity during scheduled maintenance periods. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#react-quicker-with-no-responder-notifications) React Quicker with No-Responder Notifications Why wait for timeouts when services aren’t available? When a request is made to a service (request-reply) and the NATS Server knows there are no services available the server will short circuit the request. A “no-responders” protocol message will be sent back to the requesting client which will break from blocking API calls. This allows applications to immediately react which further enables building a highly responsive system at scale, even in the face of application failures and network partitions. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#subject-mapping-and-traffic-shaping) 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 into your system. See [Configuring Subject Mapping and Traffic Shaping](https://docs.nats.io/running-a-nats-service/configuration/configuring_subject_mapping) in NATS Server configuration for more details. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_22#account-monitoring-more-meaningful-metrics) Account Monitoring - More Meaningful Metrics NATS now allows for [fine-grained monitoring](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring#monitoring-nats) to identify usage metrics tied to a particular account. Inspect messages and bytes sent or received and various connection statistics for a particular account. Accounts can represent anything - a group of applications, a team or organization, a geographic location, or even roles. If NATS is enabling your SaaS solution you could use NATS account scoped metrics to bill users. [PreviousNATS 2.10](https://docs.nats.io/release-notes/whats_new/whats_new_210) [NextNATS 2.0](https://docs.nats.io/release-notes/whats_new/whats_new_20) Last updated 2 years ago Was this helpful? --- # Core NATS | NATS Docs Core NATS is the foundational functionality in a NATS system. It operates on a publish-subscribe model using subject/topic-based addressing. This model offers two significant advantages: location independence and a default many-to-many (M:N) communication pattern. These fundamental concepts enable powerful and innovative solutions for common development patterns, such as microservices, without requiring additional technologies like load balancers, API gateways, or DNS configuration. NATS systems can be enhanced with [JetStream](https://docs.nats.io/nats-concepts/jetstream) , which adds persistence capabilities. While Core NATS provides best-effort, at-most-once message delivery, JetStream introduces at-least-once and exactly-once semantics. [PreviousSubject-Based Messaging](https://docs.nats.io/nats-concepts/subjects) [NextPublish-Subscribe](https://docs.nats.io/nats-concepts/core-nats/pubsub) Last updated 1 year ago Was this helpful? --- # Request-Reply Walkthrough | NATS Docs NATS supports [request-reply](https://docs.nats.io/nats-concepts/core-nats/reqreply) messaging. In this tutorial you explore how to exchange point-to-point messages using NATS. [](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough#prerequisites) Prerequisites --------------------------------------------------------------------------------------------------------------- If you have not already done so, you need to [install](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup) the `nats` CLI Tool and optionally, the nats-server on your machine. [](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough#walkthrough) Walkthrough ----------------------------------------------------------------------------------------------------------- Start two terminal sessions. These will be used to run the NATS request and reply clients. ### [](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough#in-one-terminal-run-the-reply-client-listener) In one terminal, run the reply client listener Copy nats reply help.please 'OK, I CAN HELP!!!' You should see the message: _Listening on \[help.please\]_ This means that the NATS receiver client is listening for request messages on the "help.please" subject. In NATS, the receiver is a subscriber. ### [](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough#in-the-other-terminal-run-the-request-client) In the other terminal, run the request client Copy nats request help.please 'I need help!' The NATS requestor client makes a request by sending the message "I need help!" on the “help.please” subject. The NATS receiver client receives the message, formulates the reply ("OK, I CAN HELP!!!"), and sends it to the inbox of the requester. [PreviousRequest-Reply](https://docs.nats.io/nats-concepts/core-nats/reqreply) [NextQueue Groups](https://docs.nats.io/nats-concepts/core-nats/queue) Last updated 3 years ago Was this helpful? --- # Publish-Subscribe | NATS Docs [](https://docs.nats.io/nats-concepts/core-nats/pubsub#publish-subscribe) Publish-Subscribe ------------------------------------------------------------------------------------------------ NATS implements a publish-subscribe message distribution model for one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression (but only a bit). This one-to-many pattern is sometimes called a fan-out. ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-22d59af386038cc2717176561ffc95c63c295926%252Fpubsub.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=1a700ae8&sv=2) [](https://docs.nats.io/nats-concepts/core-nats/pubsub#messages) Messages ------------------------------------------------------------------------------ Messages are composed of: 1. A subject. 2. A payload in the form of a byte array. 3. Any number of header fields. 4. An optional 'reply' address field. Messages have a maximum size (which is set in the server configuration with `max_payload`). The size is set to 1 MB by default, but can be increased up to 64 MB if needed (though we recommend keeping the max message size to something more reasonable like 8 MB). [PreviousCore NATS](https://docs.nats.io/nats-concepts/core-nats) [NextPub/Sub Walkthrough](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough) Last updated 3 years ago Was this helpful? --- # What is NATS | NATS Docs Software applications and services need to exchange data. NATS is an infrastructure that allows such data exchange, segmented in the form of messages. We call this a "**message oriented middleware**". With NATS, application developers can: * Effortlessly build distributed and scalable client-server applications. * Store and distribute data in realtime in a general manner. This can flexibly be achieved across various environments, languages, cloud providers and on-premises systems. ### [](https://docs.nats.io/nats-concepts/what-is-nats#nats-client-applications) NATS Client Applications Developers use one of the NATS client libraries in their application code to allow them to publish, subscribe, request and reply between instances of the application or between completely separate applications. Those applications are generally referred to as 'client applications' or sometimes just as 'clients' throughout this manual (since from the point of view of the NATS server, they are clients). ### [](https://docs.nats.io/nats-concepts/what-is-nats#nats-service-infrastructure) NATS Service Infrastructure The NATS services are provided by one or more NATS server processes that are configured to interconnect with each other and provide a _NATS service infrastructure_. The NATS service infrastructure can scale from a single NATS server process running on an end device (the `nats-server` process is less than 20 MB in size!) all the way to a public global super-cluster of many clusters spanning all major cloud providers and all regions of the world such as Synadia's NGS. ### [](https://docs.nats.io/nats-concepts/what-is-nats#connecting-nats-client-applications-to-the-nats-servers) Connecting NATS Client applications to the NATS servers To connect a NATS client application with a NATS service, and then subscribe or publish messages to subjects, it only needs to be configured with: 1. **URL:** A ['NATS URL'](https://docs.nats.io/using-nats/developer/connecting#nats-url) . This is a string (in a URL format) that specifies the IP address and port where the NATS server(s) can be reached, and what kind of connection to establish (plain TCP, TLS, or Websocket). 2. **Authentication** (if needed): [Authentication](https://docs.nats.io/using-nats/developer/connecting#authentication-details) details for the application to identify itself with the NATS server(s). NATS supports multiple authentication schemes (username/password, decentralized JWT, token, TLS certificates and Nkey with challenge). [](https://docs.nats.io/nats-concepts/what-is-nats#simple-messaging-design) Simple messaging design -------------------------------------------------------------------------------------------------------- NATS makes it easy for applications to communicate by sending and receiving messages. These messages are addressed and identified by subject strings, and do not depend on network location. Data is encoded and framed as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers. ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-19a2ced7956b0b0681a8d97c2684d8669120eaec%252Fintro.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=4f21bd4d&sv=2) With this simple design, NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume, whether those are service requests or stream data. ### [](https://docs.nats.io/nats-concepts/what-is-nats#nats-quality-of-service-qos) NATS Quality of service (QoS) NATS offers multiple qualities of service, depending on whether the application uses just the _Core NATS_ functionality or also leverages the added functionalities enabled by _NATS JetStream_ (JetStream is built into `nats-server` but may not be enabled on all service infrastructures). * **At most once QoS:** _Core NATS_ offers an **at most once** quality of service. If a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. _Core NATS_ is a fire-and-forget messaging system. It will only hold messages in memory and will never write messages directly to disk. * **At-least / exactly once QoS:** If you need higher qualities of service (**at least once** and **exactly once**), or functionalities such as persistent streaming, de-coupled flow control, and Key/Value Store, you can use [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) , which is built in to the NATS server (but needs to be enabled). Of course, you can also always build additional reliability into your client applications yourself with proven and scalable reference designs such as acks and sequence numbers. [PreviousCompare NATS](https://docs.nats.io/nats-concepts/overview/compare-nats) [NextWalkthrough Setup](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup) Last updated 3 years ago Was this helpful? --- # Walkthrough Setup | NATS Docs We have provided Walkthroughs for you to try NATS (and JetStream) on your own. In order to follow along with the walkthroughs, you could choose one of these options: * The `nats` CLI tool must be installed, and a local NATS server must be installed (or you can use a remote server you have access to). * You can use Synadia's NGS. * You could even use the demo server from where you installed NATS. This is accessible via `nats://demo.nats.io` (this is a NATS connection URL; not a browser URL. You pass it to a NATS client application). [](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup#installing-the-nats-cli-tool) Installing the [`nats`](https://github.com/nats-io/nats.docs/blob/master/using-nats/nats-tools/nats_cli/README.md) CLI Tool ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Please refer to the [installation section in the readme](https://github.com/nats-io/natscli?tab=readme-ov-file#installation) . [](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup#installing-the-nats-server-locally-if-needed) Installing the NATS server locally (if needed) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you are going to run a server locally you need to first install it and start it. Please refer to the [nats server installation doc](https://docs.nats.io/running-a-nats-service/introduction/installation) Alternatively if you already know how to use NATS on a remote server, you only need to pass the server URL to `nats` using the `-s` option or preferably create a context using `nats context add`, to specify the server URL(s) and credentials file containing your user JWT. ### [](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup#start-the-nats-server-if-needed) Start the NATS server (if needed) To start a simple demonstration server locally, simply run: Copy nats-server (or `nats-server -m 8222` if you want to enable the HTTP monitoring functionality) When the server starts successfully, you will see the following messages: Copy [14524] 2021/10/25 22:53:53.525530 [INF] Starting nats-server [14524] 2021/10/25 22:53:53.525640 [INF] Version: 2.6.1 [14524] 2021/10/25 22:53:53.525643 [INF] Git: [not set] [14524] 2021/10/25 22:53:53.525647 [INF] Name: NDAUZCA4GR3FPBX4IFLBS4VLAETC5Y4PJQCF6APTYXXUZ3KAPBYXLACC [14524] 2021/10/25 22:53:53.525650 [INF] ID: NDAUZCA4GR3FPBX4IFLBS4VLAETC5Y4PJQCF6APTYXXUZ3KAPBYXLACC [14524] 2021/10/25 22:53:53.526392 [INF] Starting http monitor on 0.0.0.0:8222 [14524] 2021/10/25 22:53:53.526445 [INF] Listening for client connections on 0.0.0.0:4222 [14524] 2021/10/25 22:53:53.526684 [INF] Server is ready The NATS server listens for client connections on TCP Port 4222. [PreviousWhat is NATS](https://docs.nats.io/nats-concepts/what-is-nats) [NextSubject-Based Messaging](https://docs.nats.io/nats-concepts/subjects) Last updated 11 months ago Was this helpful? --- # Request-Reply | NATS Docs Request-Reply is a common pattern in modern distributed systems. A request is sent, and the application either waits on the response with a certain timeout, or receives a response asynchronously. The increased complexity of modern systems necessitates features like [location transparency](https://en.wikipedia.org/wiki/Location_transparency) , scale-up and scale-down, observability (measuring a system's state based on the data it generates) and more. In order to implement this feature-set, various other technologies needed to incorporate additional components, sidecars (processes or services that support the primary application) and proxies. NATS on the other hand, implemented Request-Reply much more easily. ### [](https://docs.nats.io/nats-concepts/core-nats/reqreply#nats-makes-request-reply-simple-and-powerful) NATS makes Request-Reply simple and powerful * NATS supports the Request-Reply pattern using its core communication mechanism — publish and subscribe. A request is published on a given subject using a reply subject. Responders listen on that subject and send responses to the reply subject. Reply subjects are called "**inbox**". These are unique subjects that are dynamically directed back to the requester, regardless of the location of either party. * Multiple NATS responders can form dynamic queue groups. Therefore, it's not necessary to manually add or remove subscribers from the group for them to start or stop being distributed messages. It’s done automatically. This allows responders to scale up or down as per demand. * NATS applications "drain before exiting" (processing buffered messages before closing the connection). This allows the applications to scale down without dropping requests. * Since NATS is based on publish-subscribe, observability is as simple as running another application that can view requests and responses to measure latency, watch for anomalies, direct scalability and more. * The power of NATS even allows multiple responses, where the first response is utilized and the system efficiently discards the additional ones. This allows for a sophisticated pattern to have multiple responders, reduce response latency and jitter. ### [](https://docs.nats.io/nats-concepts/core-nats/reqreply#the-pattern) The pattern ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-dc10798d4afca301adba55c1e85c599b25a2ae24%252Freqrepl.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=4fdca5ce&sv=2) Try NATS request-reply on your own, using a live server by walking through the [request-reply walkthrough.](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough) ### [](https://docs.nats.io/nats-concepts/core-nats/reqreply#no-responders) No responders When a request is sent to a subject that has no subscribers, it can be convenient to know about it right away. For this use-case, a NATS client can [opt-into no\_responder messages](https://docs.nats.io/reference/reference-protocols/nats-protocol#syntax-1) . This requires a server and client that support headers. When enabled, a request sent to a subject with no subscribers will immediately receive a reply that has no body, and a `503` status. Most clients will represent this case by raising or returning an error. For example: Copy m, err := nc.Request("foo", nil, time.Second); # err == nats.ErrNoResponders [PreviousPub/Sub Walkthrough](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough) [NextRequest-Reply Walkthrough](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough) Last updated 2 years ago Was this helpful? --- # Subject-Based Messaging | NATS Docs NATS is a system for publishing and listening for messages on named communication channels we call `Subjects`. Fundamentally, NATS is an `interest-based` messaging system, where the listener has to `subscribe` to a subset of `subjects`. In other middleware systems subjects may be called `topics`, `channels`, `streams` (Note that in NATS the term `stream` is used for a [JetStream](https://docs.nats.io/nats-concepts/jetstream) message storage). **What is a subject?** At its simplest, a subject is just a string of characters that form a name the publisher and subscriber can use to find each other. More commonly [subject hierarchies](https://docs.nats.io/nats-concepts/subjects#subject-hierarchies) are used to scope messages into semantic namespaces. Please check the [constraint and conventions](https://docs.nats.io/nats-concepts/subjects#characters-allowed-and-recommended-for-subject-names) on naming for subjects here. **Location transparency** Through subject-based addressing, NATS provides location transparency across a (large) cloud of routed NATS servers. * Subject subscriptions are automatically propagated within the server cloud. * Messages will be automatically routed to all interested subscribers, independent of location. * Messages with no subscribers to their subject are automatically discarded (Please see the [JetStream](https://docs.nats.io/nats-concepts/jetstream) feature for message persistence). ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-dc7b8771a8a77c9042d216ca3868ec0fa7b05fff%252Fsubjects1.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5c9ce746&sv=2) [](https://docs.nats.io/nats-concepts/subjects#wildcards) Wildcards ------------------------------------------------------------------------ NATS provides two _wildcards_ that can take the place of one or more elements in a dot-separated subject. Publishers will always send a message to a fully specified subject, without the wildcard. While subscribers can use these wildcards to listen to multiple subjects with a single subscription. [](https://docs.nats.io/nats-concepts/subjects#subject-hierarchies) Subject hierarchies -------------------------------------------------------------------------------------------- The `.` character is used to create a subject hierarchy. For example, a world clock application might define the following to logically group related subjects: Copy time.us time.us.east time.us.east.atlanta time.eu.east time.eu.east.warsaw [](https://docs.nats.io/nats-concepts/subjects#subject-usage-best-practices) Subject usage best practices -------------------------------------------------------------------------------------------------------------- There is no hard limit to subject size, but it is recommended to keep the maximum number of tokens in your subjects to a reasonable value. E.g. a maximum of 16 tokens and the subject length to less than 256 characters. ### [](https://docs.nats.io/nats-concepts/subjects#number-of-subjects) Number of subjects NATS can manage 10s of millions of subjects efficiently, therefore, you can use fine-grained addressing for your business entities. Subjects are ephemeral resources, which will disappear when no longer subscribed to. Still, subject subscriptions need to be cached by the server in memory. Consider when increasing your subscribed subject count to more than one million you will need more than 1GB of server memory and it will grow linearly from there. ### [](https://docs.nats.io/nats-concepts/subjects#subject-based-filtering-and-security) Subject-based filtering and security The message subject can be filtered with various means and through various configuration elements in your NATS server cluster. For example, but not limited to: * Security - allow/deny per user * Import/export between accounts * Automatic transformations * When inserting messages into JetStream streams * When sourcing/mirroring JetStream streams * When connecting leaf nodes (NATS edge servers) * ... A well-designed subject hierarchy will make the job a lot easier for those tasks. ### [](https://docs.nats.io/nats-concepts/subjects#naming-things) Naming things There are only two hard problems in computer science: cache invalidation, naming things, and off-by-one errors. -- Unknown author A subject hierarchy is a powerful tool for addressing your application resources. Most NATS users therefore encode business semantics into the subject name. You are free to choose a structure fit for your purpose, but you should refrain from over-complicating your subject design at the start of the project. **Some guidelines:** * Use the first token(s) to establish a general namespace. Copy factory1.tools.group42.unit17 * Use the final token(s)for identifiers Copy service.deploy.server-acme.app123 * A subject _should_ be used for more than one message. * Subscriptions _should_ be stable (exist for receiving more than one message). * Use wildcard subscriptions over subscribing to individual subjects whenever feasible. * Name business or physical entities. Refrain from encoding too much data into the subject. * Encode (business) intent into the subject, not technical details. Pragmatic: Copy orders.online.store123.order171711 Maybe not so useful: Copy orders.online.us.server42.ccpayment.premium.store123.electronics.deliver-dhl.order171711.create * NATS messages support headers. These can be used for additional metadata. There are subscription modes, which deliver headers only, allowing for efficient scanning of metadata in the message flow. ### [](https://docs.nats.io/nats-concepts/subjects#matching-a-single-token) Matching a single token The first wildcard is `*` which will match a single token. For example, if an application wanted to listen for eastern time zones, they could subscribe to `time.*.east`, which would match `time.us.east` and `time.eu.east`. Note that `*` can not match a substring within a token `time.New*.east`. ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-b70adb26feafc88e119d7455639c57bb82bba9a4%252Fsubjects2.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=f92028e1&sv=2) ### [](https://docs.nats.io/nats-concepts/subjects#matching-multiple-tokens) Matching multiple tokens The second wildcard is `>` which will match one or more tokens, and can only appear at the end of the subject. For example, `time.us.>` will match `time.us.east` and `time.us.east.atlanta`, while `time.us.*` would only match `time.us.east` since it can't match more than one token. ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-e73c731e2444069e3aedf8e14a6cd6bb8aced13d%252Fsubjects3.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=15c7c40a&sv=2) ### [](https://docs.nats.io/nats-concepts/subjects#monitoring-and-wire-taps) Monitoring and wire taps Subject to your security configuration, wildcards can be used for monitoring by creating something called a _wire tap_. In the simplest case, you can create a subscriber for `>`. This application will receive all messages -- again, subject to security settings -- sent on your NATS cluster. ### [](https://docs.nats.io/nats-concepts/subjects#mixing-wildcards) Mixing wildcards The wildcard `*` can appear multiple times in the same subject. Both types can be used as well. For example, `*.*.east.>` will receive `time.us.east.atlanta`. [](https://docs.nats.io/nats-concepts/subjects#characters-allowed-and-recommended-for-subject-names) Characters allowed and recommended for subject names -------------------------------------------------------------------------------------------------------------------------------------------------------------- For compatibility across clients and ease of maintaining configuration files, we recommend using alphanumeric characters, `-` (dash) and `_` (underscore) ASCII characters for subject and other entity names created by the user. UTF-8 (UTF8) characters are supported in subjects. Please use UTF-8 characters at your own risk. Using multilingual names for technical entities can create many issues for editing, configuration files, display, and cross-border collaboration. The rules and recommendations here apply to ALL system names, subjects, streams, durables, buckets, keys (in key-value stores), as NATS will create API subjects that contain those names. NATS will enforce these constraints in most cases, but we recommend not relying on this. * **Allowed characters**: Any Unicode character except `null`, space, `.`, `*` and `>` * **Recommended characters:** (`a` - `z`), (`A` - `Z`), (`0` - `9`), `-` and `_` (names are case sensitive, and cannot contain whitespace). * **Naming Conventions** If you want to delimit words, use either PascalCase as in `MyServiceOrderCreate` or `-` and `_` as in `my-service-order-create` * **Special characters:** The period `.` (which is used to separate the tokens in the subject) and `*` and also `>` (the `*` and `>` are used as wildcards) are reserved and cannot be used. * **Reserved names:** By convention subject names starting with a `$` are reserved for system use (e.g. subject names starting with `$SYS` or `$JS` or `$KV`, etc...). Many system subjects also use `_` (underscore) (e.g. \_INBOX , KV\_ABC, OBJ\_XYZ etc.) Good names Copy time.us time.us2.east1 time.new-york time.SanFrancisco Deprecated subject names Copy location.Malmö $location.Stockholm _Subjects_.mysubject Forbidden stream names Copy all*data service.stream.1 ### [](https://docs.nats.io/nats-concepts/subjects#pedantic-mode) Pedantic mode By default, for the sake of efficiency, subject names are not verified during message publishing. In particular, when generating subjects programmatically, this will result in illegal subjects which cannot be subscribed to. E.g. subjects containing wildcards may be ignored. To enable subject name verification, activate `pedantic` mode in the client connection options. Copy //Java Options options = Options.builder() .server("nats://127.0.0.1:4222") .pedantic() .build(); Connection nc = Nats.connect(options) [PreviousWalkthrough Setup](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup) [NextCore NATS](https://docs.nats.io/nats-concepts/core-nats) Last updated 1 month ago Was this helpful? --- # Queueing Walkthrough | NATS Docs NATS supports a form of load balancing using [queue groups](https://docs.nats.io/nats-concepts/core-nats/queue) . Subscribers register a queue group name. A single subscriber in the group is randomly selected to receive the message. [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#walkthrough-prerequisites) Walkthrough prerequisites ---------------------------------------------------------------------------------------------------------------------------------- If you have not already done so, you need to [install](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup) the `nats` CLI Tool and optionally the nats-server on your machine. ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-1.-start-the-first-member-of-the-queue-group) 1\. Start the first member of the queue group The `nats reply` instances don't just subscribe to the subject but also automatically join a queue group (`"NATS-RPLY-22"` by default) Copy nats reply foo "service instance A Reply# {{Count}}" ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-2.-start-a-second-member-of-the-queue-group) 2\. Start a second member of the queue-group In a new window Copy nats reply foo "service instance B Reply# {{Count}}" ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-3.-start-a-third-member-of-the-queue-group) 3\. Start a third member of the queue-group In a new window Copy nats reply foo "service instance C Reply# {{Count}}" ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-4.-publish-a-nats-message) 4\. Publish a NATS message Copy nats request foo "Simple request" ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-5.-verify-message-publication-and-receipt) 5\. Verify message publication and receipt You should see that only one of the my-queue group subscribers receives the message and replies it, and you can also see which one of the available queue-group subscribers processed the request from the reply message received (i.e. service instance A, B or C) ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-6.-publish-another-message) 6\. Publish another message Copy nats request foo "Another simple request" You should see that a different queue group subscriber receives the message this time, chosen at random among the 3 queue group members. You can also send any number of requests back-to-back. From the received messages, you'll see the distribution of those requests amongst the members of the queue-group. For example: `nats request foo --count 10 "Request {{Count}}"` ### [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#id-7.-stop-start-queue-group-members) 7\. Stop/start queue-group members You can at any time start yet another service instance, or kill one and see how the queue-group automatically takes care of adding/removing those instances from the group. [](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough#see-also) See Also ------------------------------------------------------------------------------------------------ Queue groups using the NATS CLI Queue Groups NATS CLI [PreviousQueue Groups](https://docs.nats.io/nats-concepts/core-nats/queue) [NextJetStream](https://docs.nats.io/nats-concepts/jetstream) Last updated 3 years ago Was this helpful? --- # Overview | NATS Docs **What is NATS?** NATS is a connective technology that powers modern distributed systems. A connective technology is responsible for addressing, discovery and exchanging of messages that drive the common patterns in distributed systems; asking and answering questions, aka services/microservices, and making and processing statements, or stream processing. **Challenges faced by modern distributed systems** Modern distributed systems are defined by an ever increasing number of hyper-connected moving parts and the additional data they generate. They employ both services and streams to drive business value. They are also being defined by location independence and mobility, and not just for things we would typically recognize as front end technologies. Today’s systems and the backend processes, microservices and stream processing are being asked to be location independent and mobile as well, all while being secure. These modern systems present challenges to technologies that have been used to connect mobile front ends to fairly static backends. These incumbent technologies typically manage addressing and discovery via hostname (DNS) or IP and port, utilize a 1:1 communication pattern, and have multiple different security patterns for authentication and authorization. Although not perfect, incumbent technologies have been good enough in many situations, but times are changing quickly. As microservices, functions, and stream processing are being asked to move to the edge, these technologies and the assumptions they make are being challenged. [](https://docs.nats.io/nats-concepts/overview#what-makes-the-nats-connective-technology-unique-for-these-modern-systems) What makes the NATS connective technology unique for these modern systems? --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Effortless M:N connectivity:** NATS manages addressing and discovery based on subjects and not hostname and ports. Defaulting to M:N communications, which is a superset of 1:1, meaning it can do 1:1 but can also do so much more. If you have a 1:1 system that is successful in development, ask how many other moving parts are required for production to work around the assumption of 1:1? Things like load balancers, log systems, and network security models, as well as proxies and sidecars. If your production system requires all of these things just to get around the fact that the connective technology being used, e.g. HTTP or gRPC, is 1:1, it’s time to give NATS.io a look. **Deploy anywhere:** NATS can be deployed nearly anywhere; on bare metal, in a VM, as a container, inside K8S, on a device, or whichever environment you choose. NATS runs well within deployment frameworks or without. **Secure:** Similarly, NATS is secure by default and makes no requirements on network perimeter security models. When you start considering mobilizing your backend microservices and stream processors, many times the biggest roadblock is security. ### [](https://docs.nats.io/nats-concepts/overview#scalable-future-proof-deployments) Scalable, Future-Proof Deployments NATS infrastructure and clients communicate all topology changes in real-time. This means that NATS clients do not need to change when NATS deployments change. Having to change clients with deployments would be like having to reboot your phone every time your cell provider added or changed a cell tower. This sounds ridiculous of course, but think about how many systems today have their front ends tied so closely to the backend, that any change requires a complete front end reboot or at least a reconfiguration. NATS clients and applications need no such change when backend servers are added and removed and changed. Even DNS is only used to bootstrap first contact, after that, NATS handles endpoint locations transparently. ### [](https://docs.nats.io/nats-concepts/overview#hybrid-deployments) Hybrid Deployments Another advantage to utilizing a NATS is that it allows a hybrid mix of SaaS/Utility computing with separately owned and operated systems. Meaning you can have a shared NATS service with core microservices, streams and stream processing be extended by groups or individuals who have a need to run their own NATS infrastructure. You are not forced to choose one or the other. ### [](https://docs.nats.io/nats-concepts/overview#adaptability) Adaptability Today’s systems will fall short with new demands. As modern systems continue to evolve and utilize more components and process more data, supporting patterns beyond 1:1 communications, with addressing and discovery tied to DNS is critical. Foundational technologies like NATS promise the most return on investment. Incumbent technologies will not work as modern systems unify cloud, Edge, IoT and beyond. NATS does. ### [](https://docs.nats.io/nats-concepts/overview#use-cases) Use Cases NATS can run anywhere, from large servers and cloud instances, through edge gateways and even IoT devices. Use cases for NATS include: * Cloud Messaging * Services (microservices, service mesh) * Event/Data Streaming (observability, analytics, ML/AI) * Command and Control * IoT and Edge * Telemetry / Sensor Data / Command and Control * Augmenting or Replacing Legacy Messaging Systems [PreviousNATS 2.0](https://docs.nats.io/release-notes/whats_new/whats_new_20) [NextCompare NATS](https://docs.nats.io/nats-concepts/overview/compare-nats) Last updated 3 years ago Was this helpful? --- # Pub/Sub Walkthrough | NATS Docs NATS is a [publish subscribe](https://docs.nats.io/nats-concepts/core-nats/pubsub) messaging system [based on subjects](https://docs.nats.io/nats-concepts/subjects) . Subscribers listening on a subject receive messages published on that subject. If the subscriber is not actively listening on the subject, the message is not received. Subscribers can use the wildcard tokens such as `*` and `>` to match a single token or to match the tail of a subject. [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#nats-pub-sub-walkthrough) NATS Pub/Sub Walkthrough --------------------------------------------------------------------------------------------------------------------------------- This simple walkthrough demonstrates some ways in which subscribers listen on subjects, and publishers send messages on specific subjects. ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-a0d442c25fbeedf8400da6e26a2894e78df505ed%252Fpubsubtut.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5bdcb362&sv=2) ### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#walkthrough-prerequisites) Walkthrough prerequisites If you have not already done so, you need to [install](https://docs.nats.io/nats-concepts/what-is-nats/walkthrough_setup) the `nats` CLI Tool and optionally the nats-server on your machine. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-1.-create-subscriber-1) 1\. Create Subscriber 1 In a shell or command prompt session, start a client subscriber program. Copy nats sub Here, `` is a subject to listen on. It helps to use unique and well thought-through subject strings because you need to ensure that messages reach the correct subscribers even when wildcards are used. For example: Copy nats sub msg.test You should see the message: _Listening on \[msg.test\]_ #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-2.-create-a-publisher-and-publish-a-message) 2\. Create a Publisher and publish a message In another shell or command prompt, create a NATS publisher and send a message. Copy nats pub Where `` is the subject name and `` is the text to publish. For example: Copy nats pub msg.test "NATS MESSAGE" #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-3.-verify-message-publication-and-receipt) 3\. Verify message publication and receipt You'll notice that the publisher sends the message and prints: _Published \[msg.test\] : 'NATS MESSAGE'_. The subscriber receives the message and prints: _\[#1\] Received on \[msg.test\]: 'NATS MESSAGE'_. If the receiver does not get the message, you'll need to check if you are using the same subject name for the publisher and the subscriber. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-4.-try-publishing-another-message) 4\. Try publishing another message Copy nats pub msg.test "NATS MESSAGE 2" You'll notice that the subscriber receives the message. Note that a message count is incremented each time your subscribing client receives a message on that subject. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-5.-create-subscriber-2) 5\. Create Subscriber 2 In a new shell or command prompt, start a new NATS subscriber. Copy nats sub msg.test #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-6.-publish-another-message-using-the-publisher-client) 6\. Publish another message using the publisher client Copy nats pub msg.test "NATS MESSAGE 3" Verify that both subscribing clients receive the message. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-7.-create-subscriber-3) 7\. Create Subscriber 3 In a new shell or command prompt session, create a new subscriber that listens on a different subject. Copy nats sub msg.test.new #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-8.-publish-another-message) 8\. Publish another message Copy nats pub msg.test "NATS MESSAGE 4" Subscriber 1 and Subscriber 2 receive the message, but Subscriber 3 does not. Why? Because Subscriber 3 is not listening on the message subject used by the publisher. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-9.-alter-subscriber-3-to-use-a-wildcard) 9\. Alter Subscriber 3 to use a wildcard Change the last subscriber to listen on msg.\* and run it: Copy nats sub msg.* Note: NATS supports the use of wildcard characters for message subscribers only. You cannot publish a message using a wildcard subject. #### [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#id-10.-publish-another-message) 10\. Publish another message Copy nats pub msg.test "NATS MESSAGE 5" This time, all three subscribing clients should receive the message. Do try out a few more variations of substrings and wildcards to test your understanding. [](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough#see-also) See Also ------------------------------------------------------------------------------------------------- Publish-subscribe pattern with the NATS CLI Publish-subscribe pattern - NATS CLI [PreviousPublish-Subscribe](https://docs.nats.io/nats-concepts/core-nats/pubsub) [NextRequest-Reply](https://docs.nats.io/nats-concepts/core-nats/reqreply) Last updated 1 year ago Was this helpful? --- # Example | NATS Docs Consider this architecture ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-dedcc17f082fa1e39497c54ed8191b6424ee7792%252Fstreams-and-consumers-75p%2520%281%29.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5e657119&sv=2) Orders While it is an incomplete architecture it does show a number of key points: * Many related subjects are stored in a Stream * Consumers can have different modes of operation and receive just subsets of the messages * Multiple Acknowledgement modes are supported A new order arrives on `ORDERS.received`, gets sent to the `NEW` Consumer who, on success, will create a new message on `ORDERS.processed`. The `ORDERS.processed` message again enters the Stream where a `DISPATCH` Consumer receives it and once processed it will create an `ORDERS.completed` message which will again enter the Stream. These operations are all `pull` based meaning they are work queues and can scale horizontally. All require acknowledged delivery ensuring no order is missed. All messages are delivered to a `MONITOR` Consumer without any acknowledgement and using Pub/Sub semantics - they are pushed to the monitor. As messages are acknowledged to the `NEW` and `DISPATCH` Consumers, a percentage of them are Sampled and messages indicating redelivery counts, ack delays and more, are delivered to the monitoring system. [](https://docs.nats.io/nats-concepts/jetstream/consumers/example_configuration#example-configuration) Example Configuration --------------------------------------------------------------------------------------------------------------------------------- [Additional documentation](https://docs.nats.io/running-a-nats-service/configuration/clustering/jetstream_clustering/administration) introduces the `nats` utility and how you can use it to create, monitor, and manage streams and consumers, but for completeness and reference this is how you'd create the ORDERS scenario. We'll configure a 1 year retention for order related messages: Copy nats stream add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard=old nats consumer add ORDERS NEW --filter ORDERS.received --ack explicit --pull --deliver all --max-deliver=-1 --sample 100 nats consumer add ORDERS DISPATCH --filter ORDERS.processed --ack explicit --pull --deliver all --max-deliver=-1 --sample 100 nats consumer add ORDERS MONITOR --filter '' --ack none --target monitor.ORDERS --deliver last --replay instant [PreviousConsumers](https://docs.nats.io/nats-concepts/jetstream/consumers) [NextJetStream Walkthrough](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough) Last updated 3 years ago Was this helpful? --- # Example | NATS Docs Streams with source and mirror configurations are best managed through a client API. If you intend to create such a configuration from command line with NATS CLI you should use a JSON configuration. Copy nats stream add --config stream_with_sources.json [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror/source_and_mirror_example#example-stream-configuration-with-two-sources) Example stream configuration with two sources --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Minimal example** Copy { "name": "SOURCE_TARGET", "subjects": [\ "foo1.ext.*",\ "foo2.ext.*"\ ], "discard": "old", "duplicate_window": 120000000000, "sources": [\ {\ "name": "SOURCE1_ORIGIN",\ },\ ], "deny_delete": false, "sealed": false, "max_msg_size": -1, "allow_rollup_hdrs": false, "max_bytes": -1, "storage": "file", "allow_direct": false, "max_age": 0, "max_consumers": -1, "max_msgs_per_subject": -1, "num_replicas": 1, "name": "SOURCE_TARGET", "deny_purge": false, "compression": "none", "max_msgs": -1, "retention": "limits", "mirror_direct": false } **With additional options** Copy { "name": "SOURCE_TARGET", "subjects": [\ "foo1.ext.*",\ "foo2.ext.*"\ ], "discard": "old", "duplicate_window": 120000000000, "sources": [\ {\ "name": "SOURCE1_ORIGIN",\ "filter_subject": "foo1.bar",\ "opt_start_seq": 42,\ "external": {\ "deliver": "",\ "api": "$JS.domainA.API"\ }\ },\ {\ "name": "SOURCE2_ORIGIN",\ "filter_subject": "foo2.bar"\ }\ ], "consumer_limits": { }, "deny_delete": false, "sealed": false, "max_msg_size": -1, "allow_rollup_hdrs": false, "max_bytes": -1, "storage": "file", "allow_direct": false, "max_age": 0, "max_consumers": -1, "max_msgs_per_subject": -1, "num_replicas": 1, "name": "SOURCE_TARGET", "deny_purge": false, "compression": "none", "max_msgs": -1, "retention": "limits", "mirror_direct": false } [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror/source_and_mirror_example#example-stream-configuration-with-mirror) Example stream configuration with mirror ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Minimal example** Copy { "name": "MIRROR_TARGET" "discard": "old", "mirror": { "name": "MIRROR_ORIGIN" }, "deny_delete": false, "sealed": false, "max_msg_size": -1, "allow_rollup_hdrs": false, "max_bytes": -1, "storage": "file", "allow_direct": false, "max_age": 0, "max_consumers": -1, "max_msgs_per_subject": -1, "num_replicas": 1, "name": "MIRROR_TARGET", "deny_purge": false, "compression": "none", "max_msgs": -1, "retention": "limits", "mirror_direct": false } **With additional options** Copy { "name": "MIRROR_TARGET" "discard": "old", "mirror": { "opt_start_time": "2024-07-11T08:57:20.4441646Z", "external": { "deliver": "", "api": "$JS.domainB.API" }, "name": "MIRROR_ORIGIN" }, "consumer_limits": { }, "deny_delete": false, "sealed": false, "max_msg_size": -1, "allow_rollup_hdrs": false, "max_bytes": -1, "storage": "file", "allow_direct": false, "max_age": 0, "max_consumers": -1, "max_msgs_per_subject": -1, "num_replicas": 1, "name": "MIRROR_TARGET", "deny_purge": false, "compression": "none", "max_msgs": -1, "retention": "limits", "mirror_direct": false } [PreviousSource and Mirror Streams](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror) [NextConsumers](https://docs.nats.io/nats-concepts/jetstream/consumers) Last updated 5 months ago Was this helpful? --- # Compare NATS | NATS Docs This feature comparison is a summary of a few of the major components in several of the popular messaging technologies of today. This is by no means an exhaustive list and each technology should be investigated thoroughly to decide which will work best for your implementation. In this comparison, we will be featuring NATS, Apache Kafka, RabbitMQ, Apache Pulsar, and gRPC. [](https://docs.nats.io/nats-concepts/overview/compare-nats#language-and-platform-coverage) Language and Platform Coverage ------------------------------------------------------------------------------------------------------------------------------- Project Client Languages and Platforms **NATS** Core NATS: 48 known client types, 11 supported by maintainers, 18 contributed by the community. NATS Streaming: 7 client types supported by maintainers, 4 contributed by the community. NATS servers can be compiled on architectures supported by Golang. NATS provides binary distributions. **gRPC** 13 client languages. **Kafka** 18 client types supported across the community and by Confluent. Kafka servers can run on platforms supporting java; very wide support. **Pulsar** 7 client languages, 5 third-party clients - tested on macOS and Linux. **Rabbit** At least 10 client platforms that are maintainer-supported with over 50 community supported client types. Servers are supported on the following platforms: Linux, Windows NT. [](https://docs.nats.io/nats-concepts/overview/compare-nats#built-in-patterns) Built-in Patterns ----------------------------------------------------------------------------------------------------- Project Supported Patterns **NATS** Streams and Services through built-in publish/subscribe, request-reply, and load-balanced queue subscriber patterns. Dynamic request permissioning and request subject obfuscation is supported. **gRPC** One service, which may have streaming semantics, per channel. Load Balancing for a service can be done either client-side or by using a proxy. **Kafka** Streams through publish/subscribe. Load balancing can be achieved with consumer groups. Application code must correlate requests with replies over multiple topics for a service (request-reply) pattern. **Pulsar** Streams through publish/subscribe. Multiple competing consumer patterns support load balancing. Application code must correlate requests with replies over multiple topics for a service (request-reply) pattern. **Rabbit** Streams through publish/subscribe, and services with a direct reply-to feature. Load balancing can be achieved with a Work Queue. Applications must correlate requests with replies over multiple topics for a service (request-reply) pattern. [](https://docs.nats.io/nats-concepts/overview/compare-nats#delivery-guarantees) Delivery Guarantees --------------------------------------------------------------------------------------------------------- Project Quality of Service / Guarantees **NATS** At most once, at least once, and exactly once is available in JetStream. **gRPC** At most once. **Kafka** At least once, exactly once. **Pulsar** At most once, at least once, and exactly once. **Rabbit** At most once, at least once. [](https://docs.nats.io/nats-concepts/overview/compare-nats#multi-tenancy-and-sharing) Multi-tenancy and Sharing --------------------------------------------------------------------------------------------------------------------- Project Multi-tenancy Support **NATS** NATS supports true multi-tenancy and decentralized security through accounts and defining shared streams and services. **gRPC** N/A **Kafka** Multi-tenancy is not supported. **Pulsar** Multi-tenancy is implemented through tenants; built-in data sharing across tenants is not supported. Each tenant can have its own authentication and authorization scheme. **Rabbit** Multi-tenancy is supported with vhosts; data sharing is not supported. [](https://docs.nats.io/nats-concepts/overview/compare-nats#authn) AuthN ----------------------------------------------------------------------------- Project Authentication **NATS** NATS supports TLS, NATS credentials, NKEYS (NATS ED25519 keys), username and password, or simple token. **gRPC** TLS, ALT, Token, channel and call credentials, and a plug-in mechanism. **Kafka** Supports Kerberos and TLS. Supports JAAS and an out-of-box authorizer implementation that uses ZooKeeper to store connection and subject. **Pulsar** TLS Authentication, Athenz, Kerberos, JSON Web Token Authentication. **Rabbit** TLS, SASL, username and password, and pluggable authorization. [](https://docs.nats.io/nats-concepts/overview/compare-nats#authz) AuthZ ----------------------------------------------------------------------------- Project Authorization **NATS** Account limits including number of connections, message size, number of imports and exports. User-level publish and subscribe permissions, connection restrictions, CIDR address restrictions, and time of day restrictions. **gRPC** Users can configure call credentials to authorize fine-grained individual calls on a service. **Kafka** Supports JAAS, ACLs for a rich set of Kafka resources including topics, clusters, groups, and others. **Pulsar** Permissions may be granted to specific roles for lists of operations such as produce and consume. **Rabbit** ACLs dictate permissions for configure, write, and read operations on resources like exchanges, queues, transactions, and others. Authentication is pluggable. [](https://docs.nats.io/nats-concepts/overview/compare-nats#message-retention-and-persistence) Message Retention and Persistence ------------------------------------------------------------------------------------------------------------------------------------- Project Message Retention and Persistence Support **NATS** Supports memory and file persistence. Messages can be replayed by time, count, or sequence number, and durable subscriptions are supported. With NATS streaming, scripts can archive old log segments to cold storage. **gRPC** N/A **Kafka** Supports file-based persistence. Messages can be replayed by specifying an offset, and durable subscriptions are supported. Log compaction is supported as well as KSQL. **Pulsar** Supports tiered storage including file, Amazon S3 or Google Cloud Storage (GCS). Pulsar can replay messages from a specific position and supports durable subscriptions. Pulsar SQL and topic compaction is supported, as well as Pulsar functions. **Rabbit** Supports file-based persistence. Rabbit supported queue-based semantics (vs log), so no message replay is available. [](https://docs.nats.io/nats-concepts/overview/compare-nats#high-availability-and-fault-tolerance) High Availability and Fault Tolerance --------------------------------------------------------------------------------------------------------------------------------------------- Project HA and FT Support **NATS** Core NATS supports full mesh clustering with self-healing features to provide high availability to clients. NATS streaming has warm failover backup servers with two modes (FT and full clustering). JetStream supports horizontal scalability with built-in mirroring. **gRPC** N/A. gRPC relies on external resources for HA/FT. **Kafka** Fully replicated cluster members are coordinated via Zookeeper. **Pulsar** Pulsar supports clustered brokers with geo-replication. **Rabbit** Clustering Support with full data replication via federation plugins. Clusters require low-latency networks where network partitions are rare. [](https://docs.nats.io/nats-concepts/overview/compare-nats#deployment) Deployment --------------------------------------------------------------------------------------- Project Supported Deployment Models **NATS** The NATS network element (server) is a small static binary that can be deployed anywhere from large instances in the cloud to resource constrained devices like a Raspberry PI. NATS supports the Adaptive Edge architecture which allows for large, flexible deployments. Single servers, leaf nodes, clusters, and superclusters (cluster of clusters) can be combined in any fashion for an extremely flexible deployment amenable to cloud, on-premise, edge and IoT. Clients are unaware of topology and can connect to any NATS server in a deployment. **gRPC** gRPC is point to point and does not have a server or broker to deploy or manage, but always requires additional pieces for production deployments. **Kafka** Kafka supports clustering with mirroring to loosely coupled remote clusters. Clients are tied to partitions defined within clusters. Kafka servers require a JVM, eight cores, 64 GB to128 GB of RAM, two or more 8-TB SAS/SSD disks, and a 10-Gig NIC. [_(1)_](https://docs.nats.io/nats-concepts/overview/compare-nats#references) \_\_ **Pulsar** Pulsar supports clustering and built-in geo-replication between clusters. Clients may connect to any cluster with an appropriately configured tenant and namespace. Pulsar requires a JVM and requires at least 6 Linux machines or VMs. 3 running ZooKeeper. 3 running a Pulsar broker and a BookKeeper bookie. [_(2)_](https://docs.nats.io/nats-concepts/overview/compare-nats#references) \_\_ **Rabbit** Rabbit supports clusters and cross-cluster message propagation through a federation plugin. Clients are unaware of topology and may connect to any cluster. The server requires the Erlang VM and dependencies. [](https://docs.nats.io/nats-concepts/overview/compare-nats#monitoring) Monitoring --------------------------------------------------------------------------------------- Project Monitoring Tooling **NATS** NATS supports exporting monitoring data to Prometheus and has Grafana dashboards to monitor and configure alerts. There are also development monitoring tools such as nats-top. Robust side car deployment or a simple connect-and-view model with NATS surveyor is supported. **gRPC** External components such as a service mesh are required to monitor gRPC. **Kafka** Kafka has a number of management tools and consoles including Confluent Control Center, Kafka, Kafka Web Console, Kafka Offset Monitor. **Pulsar** CLI tools, per-topic dashboards, and third-party tools. **Rabbit** CLI tools, a plugin-based management system with dashboards and third-party tools. [](https://docs.nats.io/nats-concepts/overview/compare-nats#management) Management --------------------------------------------------------------------------------------- Project Management Tooling **NATS** NATS separates operations from security. User and Account management in a deployment may be decentralized and managed through a CLI. Server (network element) configuration is separated from security with a command line and configuration file which can be reloaded with changes at runtime. **gRPC** External components such as a service mesh are required to manage gRPC. **Kafka** Kafka has a number of management tools and consoles including Confluent Control Center, Kafka, Kafka Web Console, Kafka Offset Monitor. **Pulsar** CLI tools, per-topic dashboards, and third-party tools. **Rabbit** CLI tools, a plugin-based management system with dashboards and third-party tools. [](https://docs.nats.io/nats-concepts/overview/compare-nats#integrations) Integrations ------------------------------------------------------------------------------------------- Project Built-in and Third Party Integrations **NATS** NATS supports WebSockets, a Kafka bridge, an IBM MQ Bridge, a Redis Connector, Apache Spark, Apache Flink, CoreOS, Elastic, Elasticsearch, Prometheus, Telegraf, Logrus, Fluent Bit, Fluentd, OpenFAAS, HTTP, and MQTT, and [more](https://nats.io/download/#connectors-and-utilities) . **gRPC** There are a number of third party integrations including HTTP, JSON, Prometheus, Grift and others. [_(3)_](https://docs.nats.io/nats-concepts/overview/compare-nats#references) \_\_ **Kafka** Kafka has a large number of integrations in its ecosystem, including stream processing (Storm, Samza, Flink), Hadoop, database (JDBC, Oracle Golden Gate), Search and Query (ElasticSearch, Hive), and a variety of logging and other integrations. **Pulsar** Pulsar has many integrations, including ActiveMQ, Cassandra, Debezium, Flume, Elasticsearch, Kafka, Redis, and others. **Rabbit** RabbitMQ has many plugins, including protocols (MQTT, STOMP), WebSockets, and various authorization and authentication plugins. [](https://docs.nats.io/nats-concepts/overview/compare-nats#references) References --------------------------------------------------------------------------------------- 1. [https://docs.cloudera.com/HDPDocuments/HDF3/HDF-3.1.0/bk\_planning-your-deployment/content/ch\_hardware-sizing.html](https://docs.cloudera.com/HDPDocuments/HDF3/HDF-3.1.0/bk_planning-your-deployment/content/ch_hardware-sizing.html) 2. [https://pulsar.apache.org/docs/4.0.x/deploy-bare-metal/](https://pulsar.apache.org/docs/4.0.x/deploy-bare-metal/) 3. [https://github.com/grpc-ecosystem](https://github.com/grpc-ecosystem) [PreviousOverview](https://docs.nats.io/nats-concepts/overview) [NextWhat is NATS](https://docs.nats.io/nats-concepts/what-is-nats) Last updated 3 months ago Was this helpful? --- # NATS 2.10 | NATS Docs This guide is tailored for existing NATS users upgrading from NATS version 2.9.x. This will read as a summary with links to specific documentation pages to learn more about the feature or improvement. [](https://docs.nats.io/release-notes/whats_new/whats_new_210#upgrade-considerations) Upgrade considerations ----------------------------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#client-versions) Client versions Although all existing client versions will work, new client versions will expose additional options used to leverage new features. The minimum client versions that have full 2.10.0 support include: * CLI - [v0.1.0](https://github.com/nats-io/natscli/releases/tag/v0.1.0) * nats.go - [v1.30.0](https://github.com/nats-io/nats.go/releases/tag/v1.30.0) * nats.rs - [v0.32.0](https://github.com/nats-io/nats.rs/releases/tag/async-nats%2Fv0.32.0) * nats.deno - [v1.17.0](https://github.com/nats-io/nats.deno/releases/tag/v1.17.0) * nats.js - [v2.17.0](https://github.com/nats-io/nats.js/releases/tag/v2.17.0) * nats.ws - [v1.18.0](https://github.com/nats-io/nats.ws/releases/tag/v1.18.0) * nats.java - [v2.17.0](https://github.com/nats-io/nats.java/releases/tag/2.17.0) * nats.net - [v1.1.0](https://github.com/nats-io/nats.net/releases/tag/1.1.0) * nats.net.v2 - Coming soon! * nats.py - Coming soon! * nats.c - Coming soon! ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#helm-charts) Helm charts * k8s/nats - [v1.1.0](https://github.com/nats-io/k8s/releases/tag/nats-1.1.0) * k8s/nack - [v0.24.0](https://github.com/nats-io/k8s/releases/tag/nack-0.24.0) ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#downgrade-warnings) Downgrade warnings For critical infrastructure like NATS, zero downtime upgrades are table stakes. Although the best practice for all infrastructure like this is for users to thoroughly test a new release against your specific workloads, inevitably there are cases where an upgrade occurs in production followed by a decision to downgrade. This is never recommended and can cause more harm than good for most infrastructure and data systems. Below are a few important considerations if downgrading is required. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#storage-format-changes) Storage format changes 2.10.0 brings on-disk storage changes which bring significant performance improvements. These are not compatible with previous versions of the NATS Server. If an upgrade is performed to a server with existing stream data on disk, followed by a downgrade, the older version server will not understand the stream data in the new format. However, being mindful of the possibility of the need to downgrade, a special version of the 2.9.x series was released with awareness of key changes in the new storage format, allowing it to startup properly. The takeaway is that if a downgrade is the only resort, it must be to 2.9.22 or later to ensure storage format changes are handled appropriately. #### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#stream-and-consumer-config-options) Stream and consumer config options There are new stream and consumer configuration options that could be problematic if a downgrade occurs since previous versions of the server have no awareness of them. Examples include: * Multi-filter consumers - Downgrading would result in no filter being applied since the new field is configured as a list rather than a single string. * Subject-transform on streams - Downgrading would result in the subject transform not being applied since the server has no awareness of it. * Compression on streams - Downgrading when compression is enabled on streams will cause those streams to become unloadable since the older server versions will not understand the compression being used. [](https://docs.nats.io/release-notes/whats_new/whats_new_210#features) Features ------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#platforms) Platforms * Experimental support for [IBM z/OS](https://docs.nats.io/running-a-nats-service/introduction/installation#supported-operating-systems-and-architectures) * Experimental support for [NetBSD](https://docs.nats.io/running-a-nats-service/introduction/installation#supported-operating-systems-and-architectures) ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#reload) Reload * A server reload can now be performed by sending a message on [`$SYS.REQ.SERVER..RELOAD`](https://docs.nats.io/running-a-nats-service/configuration#configuration-reloading) by a client authenticated in the system account. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#jetstream) JetStream * A new [`sync_interval` server config option](https://docs.nats.io/running-a-nats-service/configuration#jetstream) has been added to change the default sync interval of stream data when written to disk, including allowing all writes to be flushed immediately. This option is only relevant if you need to modify durability guarantees. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#subject-mapping) Subject mapping * Subject mappings can now be [cluster-scoped](https://docs.nats.io/nats-concepts/subject_mapping#cluster-scoped-mappings) and weighted, enabling the ability to have different mappings or weights on a per cluster basis. * The requirement to use all wildcard tokens in subject mapping or transforms has been relaxed. This can be applied to config or account-based subject mapping, stream subject transforms, and stream republishing, but not on subject mappings that are associated with stream and service import/export between accounts. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#streams) Streams * A [`subject_transform` field](https://docs.nats.io/nats-concepts/jetstream/streams#subjecttransforms) has been added enabling per-stream subject transforms. This applies to standard streams, mirrors, and sourced streams. * A [`metadata` field](https://docs.nats.io/nats-concepts/jetstream/streams#configuration) has been added to stream configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the `description` field. * A [`first_seq` field](https://docs.nats.io/nats-concepts/jetstream/streams#configuration) has been added to stream configuration enabling explicitly setting the initial sequence on stream creation. * A [`compression` field](https://docs.nats.io/nats-concepts/jetstream/streams#configuration) has been added to stream configuration enabling on-disk compression for file-based streams. * The ability to edit the [`republish` config option](https://docs.nats.io/nats-concepts/jetstream/streams#republish) on a stream after stream creation was added. * A [`Nats-Time-Stamp` header](https://docs.nats.io/nats-concepts/jetstream/headers#republish) is now included in republished messages containing the original message's timestamp. * A `ts` field has been added to stream info responses indicating the server time of the snapshot. This was added to allow for local time calculations relying on the local clock. * An array of subject-transforms (subject filter + subject transform destination) can be added to a mirror or source configuration (can not use the single subject filter/subject transform destination fields at the same time as the array). * A stream configured with `sources` can source from the same stream multiple times when distinct filter+transform options are used, allowing for some messages of a stream to be sourced more than once. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#consumers) Consumers * A [`filter_subjects` field](https://docs.nats.io/nats-concepts/jetstream/consumers#filtersubjects) has been added which enables applying server-side filtering against multiple disjoint subjects, rather than only one. * A [`metadata` field](https://docs.nats.io/nats-concepts/jetstream/consumers#configuration) has been added to consumer configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the `description` field. * A `ts` field has been added to consumer info responses indicating the server time of the snapshot. This was added to allow for local time calculations without relying on the local clock. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#key-value) Key-value * A [`metadata` field](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/jetstream/key-value-store.md#configuration) has been added to key-value configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the `description` field. * A bucket configured as a mirror or sourcing from other buckets ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#object-store) Object store * A [`metadata` field](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/jetstream/object-store.md#configuration) has been added to object store configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the `description` field. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#authn-authz) Authn/Authz * A pluggable server extension, referred to as [auth callout](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_callout) , has been added. This provides a mechanism for delegating authentication checks against a bring-your-own (BYO) provider and, optionally, dynamically declaring permissions for the authenticated user. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#monitoring) Monitoring * A `unique_tag` field has been added to the [`/varz`](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring#general-information) and [`/jsz`](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring#jetstream-information) HTTP endpoint responses, corresponding to the value of `unique_tag` defined in the server config. * A `slow_consumer_stats` field has been added to the [`/varz`](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring#general-information) HTTP endpoint providing a count of slow consumers for clients, routes, gateways, and leafnodes. * A `raft=1` query parameter has been added to the [`/jsz`](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring#jetstream-information) HTTP endpoint which adds `stream_raft_group` and `consumer_raft_groups` fields to the response. * A `num_subscriptions` field has been added to the [`$SYS.REQ.SERVER.PING.STATZ`](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts/sys_accounts#usdsys.req.server.less-than-id-greater-than.statsz-requesting-server-stats-summary) NATS endpoint responses. * A system account responder for [`$SYS.REQ.SERVER.PING.IDZ`](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts/sys_accounts#usdsys.req.server.ping.idz-discovering-servers) has been added which returns info for the server that the client is connected to. * A system account responder for [`$SYS.REQ.SERVER.PING.PROFILEZ`](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts/sys_accounts#usdsys.req.server.less-than-id-greater-than.profilez-request-profiling-information) has been added and works even if a profiling port is not enabled in the server configuration. * A user account responder for [`$SYS.REQ.USER.INFO`](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts/sys_accounts#usdsys.req.user.info-request-connected-user-information) has been added which allows a connected user to query for the account they are in and permissions they have. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#mqtt) MQTT * Support for [QoS2](https://docs.nats.io/running-a-nats-service/configuration/mqtt) has been added. Check out the new [MQTT implementation details](https://github.com/nats-io/nats-server/blob/main/server/README-MQTT.md) overview. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#clustering) Clustering * When defining routes between servers, a handful of optimizations have been introduced including a pool of TCP connections between servers, optional pinning of accounts to connections, and optional compression of traffic. There is quite a bit to dig into, so check out the [v2 routes](https://docs.nats.io/running-a-nats-service/configuration/clustering/v2_routes) page for details. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#leafnodes) Leafnodes * A [`handshake_first` config option](https://docs.nats.io/running-a-nats-service/configuration/leafnodes#tls-first-handshake) has been added enabling TLS-first handshakes for leafnode connections. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#windows) Windows * The [`NATS_STARTUP_DELAY` environment variable](https://docs.nats.io/running-a-nats-service/introduction/windows_srv#nats_startup_delay-environment-variable) has been added to allow changing the default startup for the server of 10 seconds [](https://docs.nats.io/release-notes/whats_new/whats_new_210#improvements) Improvements --------------------------------------------------------------------------------------------- ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#reload-1) Reload * The [`nats-server --signal` command](https://docs.nats.io/running-a-nats-service/nats_admin/signals#multiple-processes) now supports a glob expression on the `` argument which would match a subset of all `nats-server` instances running on the host. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#streams-1) Streams * Prior to 2.10, setting [`republish` configuration](https://docs.nats.io/nats-concepts/jetstream/streams#republish) on mirrors would result in an error. On sourcing streams, only messages that were actively between stored matching configured `subjects` would be republished. The behavior has been relaxed to allow republishing on mirrors and includes all messages on sourcing streams. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#consumers-1) Consumers * A new header has been added on a fetch response that indicates to clients the fetch has been fulfilled without requiring clients to rely on heartbeats. It avoids some conditions in which the client would issue fetch requests that could go over limits or have more fetch requests pending than required. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#leafnodes-1) Leafnodes * Previously, a leafnode configured with two or more remotes binding to the same hub account would be rejected. This restriction has been relaxed since each remote could be binding to a different local account. ### [](https://docs.nats.io/release-notes/whats_new/whats_new_210#mqtt-1) MQTT * Previously a dot `.` in an MQTT topic was not supported, however now it is! Check out the [topic-subject conversion table](https://docs.nats.io/running-a-nats-service/configuration/mqtt) for details. [PreviousNATS 2.11](https://docs.nats.io/release-notes/whats_new/whats_new_211) [NextNATS 2.2](https://docs.nats.io/release-notes/whats_new/whats_new_22) Last updated 2 years ago Was this helpful? --- # JetStream Walkthrough | NATS Docs The following is a small walkthrough on creating a stream and a consumer and interacting with the stream using the [nats cli](https://github.com/nats-io/natscli) . [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#prerequisite-enabling-jetstream) Prerequisite: enabling JetStream ------------------------------------------------------------------------------------------------------------------------------------- If you are running a local `nats-server` stop it and restart it with JetStream enabled using `nats-server -js` (if that's not already done) You can then check that JetStream is enabled by using Copy nats account info Copy Account Information User: Account: $G Expires: never Client ID: 5 Client IP: 127.0.0.1 RTT: 128µs Headers Supported: true Maximum Payload: 1.0 MiB Connected URL: nats://127.0.0.1:4222 Connected Address: 127.0.0.1:4222 Connected Server ID: NAMR7YBNZA3U2MXG2JH3FNGKBDVBG2QTMWVO6OT7XUSKRINKTRFBRZEC Connected Server Version: 2.11.0-dev TLS Connection: no JetStream Account Information: Account Usage: Storage: 0 B Memory: 0 B Streams: 0 Consumers: 0 Account Limits: Max Message Payload: 1.0 MiB Tier: Default: Configuration Requirements: Stream Requires Max Bytes Set: false Consumer Maximum Ack Pending: Unlimited Stream Resource Usage Limits: Memory: 0 B of Unlimited Memory Per Stream: Unlimited Storage: 0 B of Unlimited Storage Per Stream: Unlimited Streams: 0 of Unlimited Consumers: 0 of Unlimited If you see the below then JetStream is _not_ enabled Copy JetStream Account Information: JetStream is not supported in this account [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#id-1.-creating-a-stream) 1\. Creating a stream ------------------------------------------------------------------------------------------------------------------ Let's start by creating a stream to capture and store the messages published on the subject "foo". Enter `nats stream add ` (in the examples below we will name the stream "my\_stream"), then enter "foo" as the subject name and hit return to use the defaults for all the other stream attributes: Copy nats stream add my_stream Copy ? Subjects foo ? Storage file ? Replication 1 ? Retention Policy Limits ? Discard Policy Old ? Stream Messages Limit -1 ? Per Subject Messages Limit -1 ? Total Stream Size -1 ? Message TTL -1 ? Max Message Size -1 ? Duplicate tracking time window 2m0s ? Allow message Roll-ups No ? Allow message deletion Yes ? Allow purging subjects or the entire stream Yes Stream my_stream was created Information for Stream my_stream created 2024-06-07 12:29:36 Subjects: foo Replicas: 1 Storage: File Options: Retention: Limits Acknowledgments: true Discard Policy: Old Duplicate Window: 2m0s Direct Get: true Allows Msg Delete: true Allows Purge: true Allows Rollups: false Limits: Maximum Messages: unlimited Maximum Per Subject: unlimited Maximum Bytes: unlimited Maximum Age: unlimited Maximum Message Size: unlimited Maximum Consumers: unlimited State: Messages: 0 Bytes: 0 B First Sequence: 0 Last Sequence: 0 Active Consumers: 0 You can then check the information about the stream you just created: Copy nats stream info my_stream Copy Information for Stream my_stream created 2024-06-07 12:29:36 Subjects: foo Replicas: 1 Storage: File Options: Retention: Limits Acknowledgments: true Discard Policy: Old Duplicate Window: 2m0s Direct Get: true Allows Msg Delete: true Allows Purge: true Allows Rollups: false Limits: Maximum Messages: unlimited Maximum Per Subject: unlimited Maximum Bytes: unlimited Maximum Age: unlimited Maximum Message Size: unlimited Maximum Consumers: unlimited State: Messages: 0 Bytes: 0 B First Sequence: 0 Last Sequence: 0 Active Consumers: 0 [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#id-2.-publish-some-messages-into-the-stream) 2\. Publish some messages into the stream ---------------------------------------------------------------------------------------------------------------------------------------------------------- Let's now start a publisher Copy nats pub foo --count=1000 --sleep 1s "publication #{{.Count}} @ {{.TimeStamp}}" As messages are being published on the subject "foo" they are also captured and stored in the stream, you can check that by using `nats stream info my_stream` and even look at the messages themselves using `nats stream view my_stream` or `nats stream get my_stream` [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#id-3.-creating-a-consumer) 3\. Creating a consumer ---------------------------------------------------------------------------------------------------------------------- Now at this point if you create a 'Core NATS' (i.e. non-streaming) subscriber to listen for messages on the subject 'foo', you will _only_ receive the messages being published after the subscriber was started, this is normal and expected for the basic 'Core NATS' messaging. In order to receive a 'replay' of all the messages contained in the stream (including those that were published in the past) we will now create a 'consumer' We can administratively create a consumer using the 'nats consumer add ' command, in this example we will name the consumer "pull\_consumer", and we will leave the delivery subject to 'nothing' (i.e. just hit return at the prompt) because we are creating a 'pull consumer' and select `all` for the start policy, you can then just use the defaults and hit return for all the other prompts. The stream the consumer is created on should be the stream 'my\_stream' we just created above. Copy nats consumer add Copy ? Consumer name pull_consumer ? Delivery target (empty for Pull Consumers) ? Start policy (all, new, last, subject, 1h, msg sequence) all ? Acknowledgment policy explicit ? Replay policy instant ? Filter Stream by subjects (blank for all) ? Maximum Allowed Deliveries -1 ? Maximum Acknowledgments Pending 0 ? Deliver headers only without bodies No ? Add a Retry Backoff Policy No ? Select a Stream my_stream Information for Consumer my_stream > pull_consumer created 2024-06-07T12:32:09-05:00 Configuration: Name: pull_consumer Pull Mode: true Deliver Policy: All Ack Policy: Explicit Ack Wait: 30.00s Replay Policy: Instant Max Ack Pending: 1,000 Max Waiting Pulls: 512 State: Last Delivered Message: Consumer sequence: 0 Stream sequence: 0 Acknowledgment Floor: Consumer sequence: 0 Stream sequence: 0 Outstanding Acks: 0 out of maximum 1,000 Redelivered Messages: 0 Unprocessed Messages: 74 Waiting Pulls: 0 of maximum 512 You can check on the status of any consumer at any time using `nats consumer info` or view the messages in the stream using `nats stream view my_stream` or `nats stream get my_stream`, or even remove individual messages from the stream using `nats stream rmm` [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#id-3.-subscribing-from-the-consumer) 3\. Subscribing from the consumer ------------------------------------------------------------------------------------------------------------------------------------------ Now that the consumer has been created and since there are messages in the stream we can now start subscribing to the consumer: Copy nats consumer next my_stream pull_consumer --count 1000 This will print out all the messages in the stream starting with the first message (which was published in the past) and continuing with new messages as they are published until the count is reached. Note that in this example we are creating a pull consumer with a 'durable' name, this means that the consumer can be shared between as many consuming processes as you want. For example instead of running a single `nats consumer next` with a count of 1000 messages you could have started two instances of `nats consumer` each with a message count of 500 and you would see the consumption of the messages from the consumer distributed between those instances of `nats` #### [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#replaying-the-messages-again) Replaying the messages again Once you have iterated over all the messages in the stream with the consumer, you can get them again by simply creating a new consumer or by deleting that consumer (`nats consumer rm`) and re-creating it (`nats consumer add`). [](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough#id-4.-cleaning-up) 4\. Cleaning up ------------------------------------------------------------------------------------------------------ You can clean up a stream (and release the resources associated with it (e.g. the messages stored in the stream)) using `nats stream purge` You can also delete a stream (which will also automatically delete all of the consumers that may be defined on that stream) using `nats stream rm` [PreviousExample](https://docs.nats.io/nats-concepts/jetstream/consumers/example_configuration) [NextKey/Value Store](https://docs.nats.io/nats-concepts/jetstream/key-value-store) Last updated 6 months ago Was this helpful? --- # Queue Groups | NATS Docs When subscribers register themselves to receive messages from a publisher, the 1:N fan-out pattern of messaging ensures that any message sent by a publisher, reaches all subscribers that have registered. NATS provides an additional feature named "queue", which allows subscribers to register themselves as part of a queue. Subscribers that are part of a queue, form the "queue group". [](https://docs.nats.io/nats-concepts/core-nats/queue#how-queue-groups-function) How queue groups function --------------------------------------------------------------------------------------------------------------- As an example, consider message delivery occurring in the 1:N pattern to all subscribers based on the subject name (delivery happens even to subscribers that are not part of a queue group). If a subscriber is registered based on a queue name, it will always receive messages it is subscribed to, based on the subject name. However, if more subscribers are added to the same queue name, they become a queue group, and only one randomly chosen subscriber of the queue group will consume a message each time a message is received by the queue group. Such distributed queues are a built-in load balancing feature that NATS provides. **Advantages** * Ensures application fault tolerance * Workload processing can be scaled up or down * Scale your consumers up or down without duplicate messages * No extra configuration required * Queue groups are defined by the application and their queue subscribers, rather than the server configuration Queue group names follow the same naming rules as [subjects](https://docs.nats.io/nats-concepts/subjects) . Foremost, they are case sensitive and cannot contain whitespace. Consider structuring queue groups hierarchically using a period `.`. Some server functionalities like [queue permissions](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/authorization#queue-permissions) can use [wildcard matching](https://docs.nats.io/nats-concepts/subjects#wildcards) on them. Queue subscribers are ideal for scaling services. Scale up is as simple as running another application, scale down is terminating the application with a signal that drains the in flight requests. This flexibility and lack of any configuration changes makes NATS an excellent service communication technology that can work with all platform technologies. ### [](https://docs.nats.io/nats-concepts/core-nats/queue#no-responder) No responder When a request is made to a service (request/reply) and the NATS Server knows there are no services available (since there are no client applications currently subscribing to the subject in a queue-group) the server will send a “no-responders” protocol message back to the requesting client which will break from blocking API calls. This allows applications to react immediately. This further enables building a highly responsive system at scale, even in the face of application failures and network partitions. [](https://docs.nats.io/nats-concepts/core-nats/queue#stream-as-a-queue) Stream as a queue ----------------------------------------------------------------------------------------------- With [JetStream](https://github.com/nats-io/nats.docs/blob/master/nats-concepts/jetstream/README.md) a stream can also be used as a queue by setting the retention policy to `WorkQueuePolicy` and leveraging [`pull` consumers](https://docs.nats.io/nats-concepts/jetstream/consumers) to get easy horizontal scalability of the processing (or using an explicit ack push consumer with a queue group of subscribers). ![](https://docs.nats.io/~gitbook/image?url=https%3A%2F%2F1487470910-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LqMYcZML1bsXrN3Ezg0%252Fuploads%252Fgit-blob-62652b3e6dd556e3cb1c3bb474ec10038334c600%252Fqueue.svg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=ab76b046&sv=2) ### [](https://docs.nats.io/nats-concepts/core-nats/queue#queuing-geo-affinity) Queuing geo-affinity When connecting to a globally distributed NATS super-cluster, there is an automatic service geo-affinity due to the fact that a service request message will only be routed to another cluster (i.e. another region) if there are no listeners on the cluster available to handle the request locally. ### [](https://docs.nats.io/nats-concepts/core-nats/queue#tutorial) Tutorial Try NATS queue subscriptions on your own, using a live server by walking through the [queueing walkthrough](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough) . [PreviousRequest-Reply Walkthrough](https://docs.nats.io/nats-concepts/core-nats/reqreply/reqreply_walkthrough) [NextQueueing Walkthrough](https://docs.nats.io/nats-concepts/core-nats/queue/queues_walkthrough) Last updated 11 months ago Was this helpful? --- # Key/Value Store | NATS Docs JetStream, the persistence layer of NATS, not only allows for the higher qualities of service and features associated with 'streaming', but it also enables some functionalities not found in messaging systems. One such feature is the Key/Value store functionality, which allows client applications to create `buckets` and use them as immediately (as opposed to eventually) consistent, persistent [associative arrays](https://en.wikipedia.org/wiki/Associative_array) (or maps). Note that this is an abstraction on top of the Stream functionality. Buckets are materialized as Streams (with a name starting with `KV_`), everything you can do with a bucket you can do with a Stream, but you ultimately have more functionality and flexibility and control when using the Stream functionality directly. Do note, while we do guarantee immediate consistency when it comes to [monotonic writes](https://jepsen.io/consistency/models/monotonic-writes) and [monotonic reads](https://jepsen.io/consistency/models/monotonic-reads) . We don't guarantee [read your writes](https://jepsen.io/consistency/models/read-your-writes) at this time, as reads through _direct get_ requests may be served by followers or mirrors. More consistent results can be achieved by sending get requests to the underlying stream leader of the Key/Value store. * [Walkthrough](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough) * [Details](https://docs.nats.io/using-nats/developer/develop_jetstream/kv) [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#managing-a-key-value-store) Managing a Key Value store --------------------------------------------------------------------------------------------------------------------------- 1. Create a bucket, which corresponds to a stream in the underlying storage. Define KV/Stream limits as appropriate 2. Use the operation below. [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#map-style-operations) Map style operations --------------------------------------------------------------------------------------------------------------- You can use KV buckets to perform the typical operations you would expect from an immediately consistent key/value store: * put: associate a value with a key * get: retrieve the value associated with a key * delete: clear any value associated with a key * purge: clear all the values associated with all keys * keys: get a copy of all of the keys (with a value or operation associated with it) [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#atomic-operations-used-for-locking-and-concurrency-control) Atomic operations used for locking and concurrency control ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * create: associate the value with a key only if there is currently no value associated with that key (i.e. compare to null and set) * update: compare and set (aka compare and swap) the value for a key [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#limiting-size-ttl-etc) Limiting size, TTL etc. ------------------------------------------------------------------------------------------------------------------- You can set limits for your buckets, such as: * the maximum size of the bucket * the maximum size for any single value * a TTL: how long the store will keep values for [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#treating-the-key-value-store-as-a-message-stream) Treating the Key Value store as a message stream ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Finally, you can even do things that typically can not be done with a Key/Value Store: * watch: watch for changes happening for a key, which is similar to subscribing (in the publish/subscribe sense) to the key: the watcher receives updates due to put or delete operations on the key pushed to it in real-time as they happen * watch all: watch for all the changes happening on all the keys in the bucket * history: retrieve a history of the values (and delete operations) associated with each key over time (by default the history of buckets is set to 1, meaning that only the latest value/operation is stored) [](https://docs.nats.io/nats-concepts/jetstream/key-value-store#notes) Notes --------------------------------------------------------------------------------- A valid key can contain the following characters: `a-z`, `A-Z`, `0-9`, `_`, `-`, `.`, `=` and `/`, i.e. it can be a dot-separated list of tokens (which means that you can then use wildcards to match hierarchies of keys when watching a bucket). The value can be any byte array. [PreviousJetStream Walkthrough](https://docs.nats.io/nats-concepts/jetstream/js_walkthrough) [NextKey/Value Store Walkthrough](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough) Last updated 19 days ago Was this helpful? --- # Source and Mirror Streams | NATS Docs When a stream is configured with a `source` or `mirror`, it will automatically and asynchronously replicate messages from the origin stream. `source` or `mirror` are designed to be robust and will recover from a loss of connection. They are suitable for geographic distribution over high latency and unreliable connections. E.g. even a leaf node starting and connecting intermittently every few days will still receive or send messages over the source/mirror link. Another use case is when [connecting streams cross-account](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/accounts#exporting-and-importing) . There are several options available when declaring the configuration. * `Name` - Name of the origin stream to source messages from. * `StartSeq` - An optional start sequence of the origin stream to start mirroring from. * `StartTime` - An optional message start time to start mirroring from. Any messages that are equal to or greater than the start time will be included. * `FilterSubject` - An optional filter subject which will include only messages that match the subject, typically including a wildcard. Note, this cannot be used with `SubjectTransforms`. * `SubjectTransforms` - An optional set of [subject transforms](https://docs.nats.io/running-a-nats-service/configuration/configuring_subject_mapping) to apply when sourcing messages from the origin stream. Note, in this context, the `Source` will act as a filter on the origin stream and the `Destination` can optionally be provided to apply a transform. Since multiple subject transforms can be used, disjoint subjects can be sourced from the origin stream while maintaining the order of the messages. Note, this cannot be used with `FilterSubject`. * `Domain` - An optional JetStream domain of where the origin stream exists. This is commonly used in a hub cluster and leafnode topology. The stream using a source or mirror configuration can have its own retention policy, replication, and storage type. * Changes to the stream using source or mirror, e.g. deleting messages or publishing, do not reflect back on the origin stream from which the data was received. * Deletes in the origin stream are NOT replicated through a `source` or `mirror` agreement. `Sources` is a generalization of the `Mirror` and allows for sourcing data from one or more streams concurrently. If you require the target stream to act as a read-only replica: * Configure the stream without listen subjects **or** * Temporarily disable the listen subjects through client authorizations. [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#general-behavior) General behavior --------------------------------------------------------------------------------------------------------- * All configurations are made on the receiving side. The stream from which data is sourced and mirrored does not need to be configured. No cleanup is required on the origin side if the receiver disappears. * A stream can be the origin (source) for multiple streams. This is useful for geographic distribution or for designing "fan out" topologies where data needs to be distributed reliable to a large number (up to millions) of client connections. * Leaf nodes and leaf node domains are explicitly supported through the `API prefix` [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#source-specific) Source specific ------------------------------------------------------------------------------------------------------- A stream defining `Sources` is a generalized replication mechanism and allows for sourcing data from **one or more streams** concurrently. A stream with sources can still act as a regular stream allowing direct write/publish by local clients to the stream. Essentially the source streams and local client writes are aggregated into a single interleaved stream. Combined with subject transformation and filtering sourcing allows to design sophisticated data distribution architectures. Sourcing messages does not retain sequence numbers. But it retain the in stream sequence of messages . Between streams sourced to the same target, the sequence of messages is undefined. [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#mirror-specific) Mirror specific ------------------------------------------------------------------------------------------------------- A mirror can source its messages from **exactly one stream** and a clients can not directly write to the mirror. Although messages cannot be published to a mirror directly by clients, messages can be deleted on-demand (beyond the retention policy), and consumers have all capabilities available on regular streams. * Mirrored messages retains the sequence numbers and timestamps of the origin stream. * Mirrors can be used for for (geographic) load distribution with the `MirrorDirect` stream attribute. See: [https://docs.nats.io/nats-concepts/jetstream/streams#configuration](https://docs.nats.io/nats-concepts/jetstream/streams#configuration) [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#expected-behavior-in-edge-conditions) Expected behavior in edge conditions ------------------------------------------------------------------------------------------------------------------------------------------------- * Source and mirror contracts are designed with one-way (geographic) data replication in mind. Neither configuration provides a full synchronization between streams, which would include deletes or replication of other stream attributes. * The content of the stream from which a source or mirror is drawn needs to be reasonable stable. Quickly deleting messages after publishing them may result in inconsistent replication due to the asynchronous nature of the replication process. * Sources and Mirror try to be be efficient in replicating messages and are lenient towards the source/mirror origin being unreachable (event for extended periods of time), e.g. when using leaf nodes, which are connected intermittently. For sake of efficiency the recovery interval in case of a disconnect is 10-20s. * Mirror and source agreements do not create a visible consumer in the origin stream. ### [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#workqueue-retention) WorkQueue retention Source and mirror works with origin stream with workqueue retention in a limited context. The source/mirror will act as a consumer removing messages from the origin stream. The implementation is not resilient when connecting over intermittent leaf node connections though. Within a cluster where the target stream (with the source/mirror agreement) it will generally work well. Source and mirror for workqueue based streams is only partially supported. It is not resilient against connection loss over leaf nodes. The consumer pulling message from a remote stream is not durable and other clients may be able to consume and remove messages from the workqueue while leaf connection is down. If you try to create additional (conflicting) consumers on the origin workqueue stream the behavior becomes undefined. A workqueue allows only one consumer per subject. If the source/mirror connection is active local clients trying to create additional consumers will fail. In reverse a source/mirror cannot be created when there is already a local consumer for the same subjects. ### [](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror#interest-base-retention) Interest base retention Source and mirror for interest based streams is not supported. Jetstream does not forbid this configuration but the behavior is undefined and may change in the future. [PreviousStreams](https://docs.nats.io/nats-concepts/jetstream/streams) [NextExample](https://docs.nats.io/nats-concepts/jetstream/source_and_mirror/source_and_mirror_example) Last updated 5 months ago Was this helpful? --- # Object Store | NATS Docs JetStream, the persistence layer of NATS, not only allows for the higher qualities of service and features associated with 'streaming', but it also enables some functionalities not found in messaging systems. One such feature is the Object store functionality, which allows client applications to create `buckets` (corresponding to streams) that can store a set of files. Files are stored and transmitted in chunks, allowing files of arbitrary size to be transferred safely over the NATS infrastructure. **Note:** Object store is not a distributed storage system. All files in a bucket will need to fit on the target file system. * [Walkthrough](https://docs.nats.io/nats-concepts/jetstream/obj_store/obj_walkthrough) * [Details](https://docs.nats.io/using-nats/developer/develop_jetstream/object) [](https://docs.nats.io/nats-concepts/jetstream/obj_store#basic-capabilities) Basic Capabilities ----------------------------------------------------------------------------------------------------- The Object Store implements a chunking mechanism, allowing you to for example store and retrieve files (i.e. the object) of any size by associating them with a path or file name as the key. * `add` a `bucket` to hold the files. * `put` Add a file to the bucket * `get` Retrieve the file and store it to a designated location * `del` Delete a file [](https://docs.nats.io/nats-concepts/jetstream/obj_store#advanced-capabilities) Advanced Capabilities ----------------------------------------------------------------------------------------------------------- * `watch` Subscribe to changes in the bucket. Will receive notifications on successful `put` and `del` operations. [PreviousKey/Value Store Walkthrough](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough) [NextObject Store Walkthrough](https://docs.nats.io/nats-concepts/jetstream/obj_store/obj_walkthrough) Last updated 1 year ago Was this helpful? --- # Key/Value Store Walkthrough | NATS Docs The Key/Value Store is a JetStream feature, so we need to verify it is enabled by Copy nats account info which may return Copy JetStream Account Information: JetStream is not supported in this account In this case, you should enable JetStream. [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#prerequisite-enabling-jetstream) Prerequisite: enabling JetStream ----------------------------------------------------------------------------------------------------------------------------------------------------- If you are running a local `nats-server` stop it and restart it with JetStream enabled using `nats-server -js` (if that's not already done) You can then check that JetStream is enabled by using Copy nats account info Copy Connection Information: Client ID: 6 Client IP: 127.0.0.1 RTT: 64.996µs Headers Supported: true Maximum Payload: 1.0 MiB Connected URL: nats://127.0.0.1:4222 Connected Address: 127.0.0.1:4222 Connected Server ID: ND2XVDA4Q363JOIFKJTPZW3ZKZCANH7NJI4EJMFSSPTRXDBFG4M4C34K JetStream Account Information: Memory: 0 B of Unlimited Storage: 0 B of Unlimited Streams: 0 of Unlimited Consumers: 0 of Unlimited [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#creating-a-kv-bucket) Creating a KV bucket ------------------------------------------------------------------------------------------------------------------------------ A 'KV bucket' is like a stream; you need to create it before using it, as in `nats kv add `: Copy nats kv add my-kv Copy my_kv Key-Value Store Status Bucket Name: my-kv History Kept: 1 Values Stored: 0 Compressed: false Backing Store Kind: JetStream Bucket Size: 0 B Maximum Bucket Size: unlimited Maximum Value Size: unlimited Maximum Age: unlimited JetStream Stream: KV_my-kv Storage: File [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#storing-a-value) Storing a value -------------------------------------------------------------------------------------------------------------------- Now that we have a bucket, we can assign, or 'put', a value to a specific key: Copy nats kv put my-kv Key1 Value1 which should return the key's value `Value1` [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#getting-a-value) Getting a value -------------------------------------------------------------------------------------------------------------------- We can fetch, or 'get', the value for a key "Key1": Copy nats kv get my-kv Key1 Copy my-kv > Key1 created @ 12 Oct 21 20:08 UTC Value1 [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#deleting-a-value) Deleting a value ---------------------------------------------------------------------------------------------------------------------- You can always delete a key and its value by using Copy nats kv del my-kv Key1 It is harmless to delete a non-existent key (check this!!). [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#atomic-operations) Atomic operations ------------------------------------------------------------------------------------------------------------------------ K/V Stores can also be used in concurrent design patterns, such as semaphores, by using atomic 'create' and 'update' operations. E.g. a client wanting exclusive use of a file can lock it by creating a key, whose value is the file name, with `create` and deleting this key after completing use of that file. A client can increase the reslience against failure by using a timeout for the `bucket` containing this key. The client can use `update` with a revision number to keep the `bucket` alive. Updates can also be used for more fine-grained concurrency control, sometimes known as `optimistic locking`, where multiple clients can try a task, but only one can successfully complete it. ### [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#create-aka-exclusive-locking) Create (aka exclusive locking) Create a lock/semaphore with the `create` operation. Copy nats kv create my-sem Semaphore1 Value1 Only one `create` can succeed. First come, first serve. All concurrent attempts will result in an error until the key is deleted Copy nats kv create my-sem Semaphore1 Value1 nats: error: nats: wrong last sequence: 1: key exists ### [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#update-with-cas-aka-optimistic-locking) Update with CAS (aka optimistic locking) We can also atomically `update`, sometimes known as a CAS (compare and swap) operation, a key with an additional parameter `revision` Copy nats kv update my-sem Semaphore1 Value2 13 A second attempt with the same revision 13, will fail Copy nats kv update my-sem Semaphore1 Value2 13 nats: error: nats: wrong last sequence: 14 [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#watching-a-k-v-store) Watching a K/V Store ------------------------------------------------------------------------------------------------------------------------------ An unusual functionality of a K/V Store is being able to 'watch' a bucket, or a specific key in that bucket, and receive real-time updates to changes in the store. For the example above, run `nats kv watch my-kv`. This will start a watcher on the bucket we have just created earlier. By default, the KV bucket has a history size of one, and so it only remembers the last change. In our case, the watcher should see a delete of the value associated with the key "Key1": Copy nats kv watch my-kv Copy [2021-10-12 13:15:03] DEL my-kv > Key1 If we now concurrently change the value of 'my-kv' by Copy nats kv put my-kv Key1 Value2 The watcher will see that change: Copy [2021-10-12 13:25:14] PUT my-kv > Key1: Value2 [](https://docs.nats.io/nats-concepts/jetstream/key-value-store/kv_walkthrough#cleaning-up) Cleaning up ------------------------------------------------------------------------------------------------------------ When you are finished using a bucket, you can delete the bucket, and its resources, by using the `rm` operator: Copy nats kv rm my-kv [PreviousKey/Value Store](https://docs.nats.io/nats-concepts/jetstream/key-value-store) [NextObject Store](https://docs.nats.io/nats-concepts/jetstream/obj_store) Last updated 1 year ago Was this helpful? --- # NATS Service Infrastructure | NATS Docs NATS is a client/server system in the fact that you have 'NATS client applications' (applications using one of the NATS client libraries) that connect to 'NATS servers' that provide the NATS service. The NATS servers work together to provide a NATS service infrastructure to their client applications. NATS is extremely flexible and scalable and allows the service infrastructure to be as small as a single process running locally on your local machine and as large as an 'Internet of NATS' of Leaf Nodes, and Leaf Node clusters all interconnected in a secure way over a global shared NATS super-cluster. Regardless of the size and complexity of the NATS service infrastructure being used, the only configuration needed by the client applications being the location (NATS URLs) of one or more NATS servers and depending on the required security, their credentials. Note that if your application is written in Golang then you even have the option of embedding the NATS server functionality into the application itself (however you need to then configure your application instances with nats-server configuration information). You do not actually need to run your NATS service infrastructure, instead you can instead make use of a public NATS infrastructure offered by a NATS Service Provider such as [Synadia Cloud](https://www.synadia.com/cloud?utm_source=nats_docs&utm_medium=nats) , think of Synadia Cloud as being an 'Internet of NATS' (literally an "InterNATS") and of Synadia as being an "InterNATS Service Provider". [](https://docs.nats.io/nats-concepts/service_infrastructure#the-evolution-of-your-nats-service-infrastructure) The Evolution of your NATS service infrastructure ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- You will typically start by running a single instance of nats-server on your local development machine, and have your applications connect to it while you do your application development and local testing. Next you will probably want to start testing and running those applications and servers in a VPC, or a region or in some on-prem location, so you will deploy either single NATS server or clusters of NATS servers in your VPCs/regions/on-prem/etc... locations and in each location have the applications connect their local nats-server or nats-server cluster. You can then connect those local nats-servers or local nats-server clusters together by making them leaf nodes connecting to a 'backbone' cluster or super-cluster, or by connecting them directly together via gateway connections. If you have many client applications (e.g., applications deployed on end-user devices all over the Internet, or for example many IoT devices) or many servers in a lot of locations you will then scale your NATS service infrastructure by deploying clusters of NATS servers in multiple locations and multiple cloud providers and VPCs. You will then need to connect those clusters into a global super-cluster and then devise a scheme to intelligently direct your client applications to the right 'closest' NATS server cluster. [](https://docs.nats.io/nats-concepts/service_infrastructure#running-your-own-nats-service-infrastructure) Running your own NATS service infrastructure ------------------------------------------------------------------------------------------------------------------------------------------------------------ You can deploy and run your own NATS service infrastructure of nats-server instances, composed of servers, clusters of servers, super-cluster and leaf node NATS servers. ### [](https://docs.nats.io/nats-concepts/service_infrastructure#virtualization-and-containerization-considerations) Virtualization and containerization considerations If using Kubernetes we recommend you use the [Helm charts](https://github.com/nats-io/k8s/tree/main/helm/charts/nats) . [PreviousSubject Mapping and Partitioning](https://docs.nats.io/nats-concepts/subject_mapping) [NextNATS Adaptive Deployment Architectures](https://docs.nats.io/nats-concepts/service_infrastructure/adaptive_edge_deployment) Last updated 5 months ago Was this helpful? --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address docs.nats.io -------------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **998f702c397c8275** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) ---