CNCF and Synadia Align on Securing the Future of the NATS.io Project. Read the joint press release.
NATS Docs
NATS.ioNATS by ExampleGitHubSlackTwitter
  • Welcome
  • Release Notes
    • What's New!
      • NATS 2.11
      • NATS 2.10
      • NATS 2.2
      • NATS 2.0
  • NATS Concepts
    • Overview
      • Compare NATS
    • What is NATS
      • Walkthrough Setup
    • Subject-Based Messaging
    • Core NATS
      • Publish-Subscribe
        • Pub/Sub Walkthrough
      • Request-Reply
        • Request-Reply Walkthrough
      • Queue Groups
        • Queueing Walkthrough
    • JetStream
      • Streams
      • Source and Mirror Streams
        • Example
      • Consumers
        • Example
      • JetStream Walkthrough
      • Key/Value Store
        • Key/Value Store Walkthrough
      • Object Store
        • Object Store Walkthrough
      • Headers
    • Subject Mapping and Partitioning
    • NATS Service Infrastructure
      • NATS Adaptive Deployment Architectures
    • Security
    • Connectivity
  • Using NATS
    • NATS Tools
      • nats
        • nats bench
      • nk
      • nsc
        • Basics
        • Streams
        • Services
        • Signing Keys
        • Revocation
        • Managed Operators
      • nats-top
        • Tutorial
    • Developing With NATS
      • Anatomy of a NATS application
      • Connecting
        • Connecting to the Default Server
        • Connecting to a Specific Server
        • Connecting to a Cluster
        • Connection Name
        • Authenticating with a User and Password
        • Authenticating with a Token
        • Authenticating with an NKey
        • Authenticating with a Credentials File
        • Encrypting Connections with TLS
        • Setting a Connect Timeout
        • Ping/Pong Protocol
        • Turning Off Echo'd Messages
        • Miscellaneous functionalities
        • Automatic Reconnections
          • Disabling Reconnect
          • Set the Number of Reconnect Attempts
          • Avoiding the Thundering Herd
          • Pausing Between Reconnect Attempts
          • Listening for Reconnect Events
          • Buffering Messages During Reconnect Attempts
        • Monitoring the Connection
          • Listen for Connection Events
          • Slow Consumers
      • Receiving Messages
        • Synchronous Subscriptions
        • Asynchronous Subscriptions
        • Unsubscribing
        • Unsubscribing After N Messages
        • Replying to a Message
        • Wildcard Subscriptions
        • Queue Subscriptions
        • Draining Messages Before Disconnect
        • Receiving Structured Data
      • Sending Messages
        • Including a Reply Subject
        • Request-Reply Semantics
        • Caches, Flush and Ping
        • Sending Structured Data
      • Building Services
      • JetStream
        • JetStream Model Deep Dive
        • Managing Streams and consumers
        • Consumer Details
        • Publishing to Streams
        • Using the Key/Value Store
        • Using the Object Store
      • Tutorials
        • Advanced Connect and Custom Dialer in Go
    • Running Workloads on NATS
      • Getting Started
        • Installing Nex
        • Building a Service
        • Starting a Node
        • Deploying Services
        • Building a Function
        • Deploying Functions
      • Host Services
        • Javascript | V8
      • Nex Internals
        • Architecture Overview
        • Node Process
        • Nex Agent
        • No Sandbox Mode
        • Root File System
        • Control Interface
      • FAQ
  • Running a NATS service
    • Installing, running and deploying a NATS Server
      • Installing a NATS Server
      • Running and deploying a NATS Server
      • Windows Service
      • Flags
    • Environmental considerations
    • NATS and Docker
      • Tutorial
      • Docker Swarm
      • Python and NGS Running in Docker
      • JetStream
      • NGS Leaf Nodes
    • NATS and Kubernetes
    • NATS Server Clients
    • Configuring NATS Server
      • Configuring JetStream
        • Configuration Management
          • NATS Admin CLI
          • Terraform
          • GitHub Actions
          • Kubernetes Controller
      • Clustering
        • Clustering Configuration
        • v2 Routes
        • JetStream Clustering
          • Administration
          • Troubleshooting
      • Super-cluster with Gateways
        • Configuration
      • Leaf Nodes
        • Configuration
        • JetStream on Leaf Nodes
      • Securing NATS
        • Enabling TLS
        • Authentication
          • Tokens
          • Username/Password
          • TLS Authentication
            • TLS Authentication in clusters
          • NKeys
          • Authentication Timeout
          • Decentralized JWT Authentication/Authorization
            • Account lookup using Resolver
            • Memory Resolver Tutorial
            • Mixed Authentication/Authorization Setup
        • Authorization
        • Multi Tenancy using Accounts
        • OCSP Stapling
        • Auth Callout
      • Logging
      • Enabling Monitoring
      • MQTT
        • Configuration
      • Configuring Subject Mapping
      • System Events
        • System Events & Decentralized JWT Tutorial
      • WebSocket
        • Configuration
    • Managing and Monitoring your NATS Server Infrastructure
      • Monitoring
        • Monitoring JetStream
      • Managing JetStream
        • Account Information
        • Naming Streams, Consumers, and Accounts
        • Streams
        • Consumers
        • Data Replication
        • Disaster Recovery
        • Encryption at Rest
      • Managing JWT Security
        • In Depth JWT Guide
      • Upgrading a Cluster
      • Slow Consumers
      • Signals
      • Lame Duck Mode
      • Profiling
  • Reference
    • FAQ
    • NATS Protocols
      • Protocol Demo
      • Client Protocol
        • Developing a Client
      • NATS Cluster Protocol
      • JetStream wire API Reference
    • Roadmap
    • Contributing
  • Legacy
    • nats-account-server
Powered by GitBook
On this page
  • Upgrade considerations
  • Client versions
  • Helm charts
  • Downgrade warnings
  • Features
  • Platforms
  • Reload
  • JetStream
  • Subject mapping
  • Streams
  • Consumers
  • Key-value
  • Object store
  • Authn/Authz
  • Monitoring
  • MQTT
  • Clustering
  • Leafnodes
  • Windows
  • Improvements
  • Reload
  • Streams
  • Consumers
  • Leafnodes
  • MQTT

Was this helpful?

Edit on GitHub
Export as PDF
  1. Release Notes
  2. What's New!

NATS 2.10

PreviousNATS 2.11NextNATS 2.2

Last updated 1 year ago

Was this helpful?

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.

Upgrade considerations

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 -

  • nats.go -

  • nats.rs -

  • nats.deno -

  • nats.js -

  • nats.ws -

  • nats.java -

  • nats.net -

  • nats.net.v2 - Coming soon!

  • nats.py - Coming soon!

  • nats.c - Coming soon!

Helm charts

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.

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.

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.

Features

Platforms

Reload

JetStream

Subject mapping

  • 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.

Streams

  • 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.

Consumers

  • 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.

Key-value

  • A bucket configured as a mirror or sourcing from other buckets

Object store

Authn/Authz

Monitoring

MQTT

Clustering

Leafnodes

Windows

Improvements

Reload

Streams

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.

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.

MQTT

k8s/nats -

k8s/nack -

Experimental support for

Experimental support for

A server reload can now be performed by sending a message on by a client authenticated in the system account.

A new 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.

Subject mappings can now be and weighted, enabling the ability to have different mappings or weights on a per cluster basis.

A has been added enabling per-stream subject transforms. This applies to standard streams, mirrors, and sourced streams.

A has been added to stream configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the description field.

A has been added to stream configuration enabling explicitly setting the initial sequence on stream creation.

A has been added to stream configuration enabling on-disk compression for file-based streams.

The ability to edit the on a stream after stream creation was added.

A is now included in republished messages containing the original message's timestamp.

A has been added which enables applying server-side filtering against multiple disjoint subjects, rather than only one.

A has been added to consumer configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the description field.

A has been added to key-value configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the description field.

A has been added to object store configuration enabling arbitrary user-defined key-value data. This is to supplant or augment the description field.

A pluggable server extension, referred to as , 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.

A unique_tag field has been added to the and 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 HTTP endpoint providing a count of slow consumers for clients, routes, gateways, and leafnodes.

A raft=1 query parameter has been added to the HTTP endpoint which adds stream_raft_group and consumer_raft_groups fields to the response.

A num_subscriptions field has been added to the NATS endpoint responses.

A system account responder for has been added which returns info for the server that the client is connected to.

A system account responder for has been added and works even if a profiling port is not enabled in the server configuration.

A user account responder for has been added which allows a connected user to query for the account they are in and permissions they have.

Support for has been added. Check out the new overview.

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 page for details.

A has been added enabling TLS-first handshakes for leafnode connections.

The has been added to allow changing the default startup for the server of 10 seconds

The now supports a glob expression on the <pid> argument which would match a subset of all nats-server instances running on the host.

Prior to 2.10, setting 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.

Previously a dot . in an MQTT topic was not supported, however now it is! Check out the for details.

v0.1.0
v1.30.0
v0.32.0
v1.17.0
v2.17.0
v1.18.0
v2.17.0
v1.1.0
v1.1.0
v0.24.0
metadata field
metadata field
auth callout
QoS2
MQTT implementation details
v2 routes
topic-subject conversion table
IBM z/OS
NetBSD
Nats-Time-Stamp header
filter_subjects field
metadata field
subject_transform field
metadata field
first_seq field
compression field
republish config option
republish configuration
$SYS.REQ.SERVER.PING.STATZ
$SYS.REQ.SERVER.PING.IDZ
$SYS.REQ.SERVER.PING.PROFILEZ
$SYS.REQ.USER.INFO
cluster-scoped
handshake_first config option
nats-server --signal command
$SYS.REQ.SERVER.<server-id>.RELOAD
sync_interval server config option
/varz
/jsz
/varz
/jsz
NATS_STARTUP_DELAY environment variable