NATS (`nats`)

Messaging system with JetStream persistence for events and work queues. Single server or clustered with routes.

Generated from catalog/services/nats.yaml: do not edit by hand.

Summary


Version	`2.11.17`
Use	install and configure
Layer	infrastructure (shown apart)
Category	Data platforms
Installation methods	`binary`, `podman`
External connection	`nats`
Sandbox only	no

Licence


SPDX identifier	`Apache-2.0`
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	`nats`

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	`docker.io/library/nats`	`2.11.17`	`Apache-2.0`	image key `nats`, used by `server`, digest `sha256:c991221cdddd53a24893cd18a90faf7a42396108496aed076bb982a349e76484`
binary archive	`nats-server-v2.11.17-linux-amd64.tar.gz`	`2.11.17`	`Apache-2.0`	https://github.com/nats-io/nats-server/releases/download/v2.11.17/nats-server-v2.11.17-linux-amd64.tar.gz, x86_64, checksum sha256

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
`binary`	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64 (architecture of the artifacts of the descriptor)
`podman`	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

at least 1024 MB of memory (blocking, memory).

Network and ports

Component	Port name	Port	Opened in the host firewall
`server`	`client`	4222/tcp	yes
`server`	`route`	6222/tcp	yes
`server`	`monitor`	8222/tcp	yes

Services and connections needed

This service has no dependency.

Installation methods and modes

Method	Default	What the method uses
`binary`	yes	the binary archives of the descriptor, unpacked under the service directory
`podman`	-	the container images of the descriptor, run by Podman under systemd

Components

Component	Kind	Installation methods	Ports
NATS server (`server`)	master	`binary`, `podman`	4222/tcp, 6222/tcp, 8222/tcp

Single server (`standalone`) (default)

One NATS server.

What the mode deploys:

Component	Placement
`server`	min 1, max 1

Cluster (`cluster`)

Servers joined by routes; JetStream needs an odd count (3 or 5) for its Raft quorum.

What the mode deploys:

Component	Placement
`server`	min 3, odd number, recommended 3

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
Choose the service. On the Service step, select NATS. The card shows the licence Apache-2.0. Pick the Method among binary, podman (default binary). To register an existing nats service of your organisation instead, turn on Use an existing external service.
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), cluster. Each mode deploys the components listed in Installation methods and modes.
Bindings. This service has no dependency: the Bindings step has nothing to bind.
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Subscribes to a fresh subject, publishes a message on it and waits for its delivery (core NATS protocol).

High availability


Cluster	native (`native`)
High availability	native (`native`)
Failover	client side (`client`)
Replication	native (`native`)
Quorum	Raft (`raft`)
Discovery	static (`static`)
Entry point	client discovery (`client-discovery`)
Official documentation	https://docs.nats.io/learn/clustering/
Peer TLS parameter	`tls_enabled`
Cluster status command	`server_report`

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
`standalone`	standalone (`standalone`)	single (`single`)	-	1	One NATS server.
`cluster`	cluster (`cluster`)	active-active (`active-active`)	`server`	3	Servers joined by routes; JetStream keeps a Raft quorum over an odd number of servers.

Notes

JetStream streams are replicated only when created with 3 (or 5) replicas; clients list several servers and reconnect by themselves.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Client port (`client_port`)	`port`	`4222`	-	no	no	no	Port of the client connections.
Route port (`cluster_port`)	`port`	`6222`	-	no	no	no	Port of the routes between cluster servers.
Monitoring port (`monitor_port`)	`port`	`8222`	-	no	no	no	Port of the HTTP monitoring endpoints (/healthz, /varz).

JetStream

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
JetStream (`jetstream_enabled`)	`bool`	`true`	-	no	no	no	Enable the persistent streams.
JetStream disk (`jetstream_max_file`)	`size`	`10g`	-	no	no	no	Maximum disk used by streams.
JetStream memory (`jetstream_max_memory`)	`size`	`1g`	-	no	no	no	Maximum memory used by memory streams.

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
TLS (`tls_enabled`)	`bool`	`false`	-	no	no	no	Require TLS for clients and routes with the manager CA certificate.
User (`username`)	`string`	`navin`	`^[A-Za-z0-9_-]{1,64}$`	no	no	no	User of the client connections.
Password (`password`)	`password`	generated	-	no	yes	no	Password of the client user.
Route password (`route_password`)	`password`	generated	-	no	yes	no	Credential of the routes between servers.

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
`client`	`nats`	`server`	4222 (`client_port`)	-	`tls_enabled`	`username`	`password`	-

Commands

Command	Component	Target	Description
Server report (`server_report`)	`server`	every host	Reads /varz and /routez of every server (connections, routes, memory).
JetStream report (`jetstream_report`)	`server`	first host	Reads /jsz (streams, consumers, meta leader).

Health checks

Liveness (per instance)

Component	Check	Details
`server`	HTTP `http://{{ host.ip or '127.0.0.1' }}:{{ config.monitor_port }}/healthz`	Expected 200; 30 retries

Readiness (service check)

Check	Details
HTTP `http://{{ host.ip or '127.0.0.1' }}:{{ config.monitor_port }}/healthz?js-enabled-only=true`	Expected 200

Smoke test

Subscribes to a fresh subject, publishes a message on it and waits for its delivery (core NATS protocol). (server: publish_subscribe)

Preflight checks

Check	Type	Meaning	Severity	Components
`memory`	`memory_mb` `{"min": 1024}`	at least 1024 MB of memory	blocking	every component
`client_port_free`	`port_free` `{"param": "client_port"}`	port 4222 free on the host	blocking	every component

Backup and restore

Archive of the JetStream store taken while the server is stopped for a few seconds (streams, consumers and messages).


Format	`nats-jetstream`
Component	`server`
Files	`{{ backup.dir }}/jetstream.tar.gz`
Restore test	no
Instances stopped for the restore	yes

Upgrade


Supported from	`2.11.4`
Stateful	yes
Backup before the upgrade	yes
Rollback	yes

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Quick links

Monitoring: http://{{ host.fqdn }}:{{ config.monitor_port }}/varz

Upstream documentation

Homepage: https://nats.io
Source: https://github.com/nats-io/nats-server
High availability: https://docs.nats.io/learn/clustering/

Summary​

Licence​

Packages and artifacts​

Supported systems and architectures​

Prerequisites​

Host​

Network and ports​

Services and connections needed​

Installation methods and modes​

Components​

Single server (standalone) (default)​

Cluster (cluster)​

Install this service​

High availability​

Topology per mode​

Notes​

Configuration parameters​

Network​

JetStream​

Security​

Endpoints​

Commands​

Health checks​

Liveness (per instance)​

Readiness (service check)​

Smoke test​

Preflight checks​

Backup and restore​

Upgrade​

Uninstall​

Quick links​

Upstream documentation​