NATS

When to Use This Skill

Invoke this skill when the user mentions or asks about:

• Deploying NATS on Kubernetes, Docker, VMs, or bare metal.
• Configuring NATS Server (nats-server, nats.conf, CLI flags).
• JetStream (streams, consumers, Key-Value store, Object Store, persistence, replication).
• Core NATS (pub/sub, request/reply, queue groups, subject hierarchies).
• Clustering / High Availability (NATS clusters, super-clusters, leaf nodes, gateways).
• Security (TLS, JWT, NKEY, username/password, auth callout, authorization).
• Helm charts (nats/nats, nats/nack, nats/surveyor).
• Monitoring / Observability (Prometheus metrics, NATS Surveyor, server statistics).
• Troubleshooting (slow consumers, connection issues, stream lag, RAFT quorum).
• Client SDKs (Go, Rust, Python, Node.js, C#, Java, etc.) — primarily from an infrastructure/operations perspective.

Core Concepts

NATS Server (nats-server)

A single, lightweight binary (< 20 MB) with no external dependencies. It supports:

• Core NATS: At-most-once pub/sub messaging with millions of messages per second.
• Request/Reply: Synchronous or asynchronous RPC over subjects.
• Queue Groups: Load-balance message delivery across a group of subscribers.
• Subject Hierarchies: Dot-separated subjects (e.g., orders.us.east) with wildcard support (*, >).

JetStream (Persistence Layer)

Built into nats-server. Provides at-least-once and exactly-once delivery, temporal decoupling, and distributed storage.

Consistency Model: JetStream uses a NATS-optimized RAFT algorithm. Writes are linearizable; reads are effectively serializable. For the strongest read consistency, send get requests to the stream leader.

Topologies

Deploying on Kubernetes

Quick Start with Helm

The official Helm charts are maintained at nats-io/k8s. See the local reference: references/kubernetes/README.md.

helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update
helm install my-nats nats/nats

Primary Charts

Chart Architecture (nats)

The nats chart uses a unique loadMergePatch pattern:

1. templates/ are thin wrappers calling nats.loadMergePatch.
2. files/ contains the actual YAML definitions, loaded via .Files.Get.
3. Users can customize almost any resource via merge: {} (deep merge) and patch: [] (RFC 6902 JSON Patch) in values.yaml.

Key values structure:

• config.*: NATS server config (maps to nats.conf sections).
  • Sub-keys: nats, cluster, jetstream, leafnodes, websocket, mqtt, gateway, monitor, profiling, resolver.
  • Each protocol has enabled, port, tls.
  • Each section supports merge: {} and patch: [].
• container.*: Server container spec (image, ports, env, resources).
• reloader.*: Config reloader sidecar.
• promExporter.*: Prometheus exporter sidecar.
• statefulSet.*, podTemplate.*, headlessService.*, configMap.*: K8s resource customization.
• natsBox.*: NATS Box deployment (CLI tools with pre-configured contexts).
• extraResources: Arbitrary additional K8s resources.

Config merge special syntax:

• Strings wrapped in << >> are unquoted (for NATS size units like 1GB or env vars like $TOKEN).
• Keys ending in $include become NATS include directives.

NACK (JetStream Controller)

NACK allows managing JetStream resources via Kubernetes CRDs (Stream, Consumer, Account, etc.).

• CRDs are in crds/crds.yml and auto-updated.
• Helper prefix in templates: jsc.*.
• Has useLegacyNames toggle for K8s label compatibility.

Local Development / Validation

Render and lint locally without installing:

# Render templates
helm template my-nats helm/charts/nats
helm template my-nats helm/charts/nats -f custom.yaml

# Lint with chart-testing
ct lint --all --chart-dirs helm/charts \
  --excluded-charts nats-account-server,nats-kafka,nats-operator,surveyor \
  --validate-maintainers=false

# Run Go template tests
cd helm/charts/nats/test && go test

See full commands in references/kubernetes/CLAUDE.md.

Server Configuration

Minimal nats.conf

# Single node with JetStream
jetstream {
  store_dir: "/data/jetstream"
}

Cluster with JetStream

server_name: nats-1
jetstream {
  store_dir: "/data/jetstream"
}
cluster {
  name: my-cluster
  listen: 0.0.0.0:6222
  routes: [
    nats-route://nats-2:6222
    nats-route://nats-3:6222
  ]
}

Protocols and Ports

Security

NATS provides multi-level security with account isolation.

Authentication Methods

Authorization

• The authorization block configures both auth and per-user permissions.
• Each user can have permissions restricting publish/subscribe subjects.
• Accounts provide subject namespace isolation; cross-account traffic uses exports and imports.

TLS

Almost every protocol section (cluster, leafnodes, websocket, mqtt, gateway, monitor) supports tls:

cluster {
  port: 6222
  tls {
    cert_file: "/certs/server.pem"
    key_file: "/certs/server.key"
    ca_file: "/certs/ca.pem"
  }
}

In the Helm chart, TLS is configured via config.*.tls.enabled and secretName.

Operations

Monitoring

• HTTP Monitor (monitor port 8222): /varz, /connz, /routez, /gatewayz, /leafz, /jsz, /healthz, /subsz.
• Prometheus Exporter: Sidecar in Helm chart (promExporter.enabled: true).
• NATS Surveyor: Standalone tool for cluster-wide metrics. See surveyor Helm chart.
• Server Statistics: Via nats server info, nats server report, nats server watch (NATS CLI).

JetStream Operations

# Check stream info
nats stream info ORDERS

# Check consumer info
nats consumer info ORDERS NEW

# Server report for JetStream
nats server report jetstream

# Evacuate a server (drain streams/consumers before maintenance)
nats server evacuate <server-name>

Durability and fsync

JetStream file stores flush to the OS synchronously but do not fsync on every write by default. The sync_interval (default 2 minutes) controls how often fsync runs.

• Default: Balanced performance and risk. Suitable for multi-AZ deployments with R=3.
• sync_interval: always: Strongest durability, slowest performance. Use for critical financial or compliance data.
• Mitigation: Lower sync_interval or use placement tags to route critical streams to a dedicated high-durability cluster.

See JetStream sync documentation for failure scenarios.

Troubleshooting

Scaling

• Horizontal: Add servers to the cluster. JetStream will auto-rebalance RAFT groups over time. For immediate effect, evacuate and restart.
• Vertical: Increase CPU/disk for JetStream nodes. SSD/NVMe is strongly recommended for file stores.
• Placement Tags: Pin streams to specific servers using server_tags and stream placement for topology-aware durability.

Developer Quick Reference

NATS CLI (nats)

The nats CLI is the primary operational tool.

# Pub/Sub
nats pub orders.new "hello"
nats sub orders.new

# Request/Reply
nats req orders.service "request" --wait 5s

# JetStream
nats stream add ORDERS --subjects "orders.*" --storage file --replicas 3
nats consumer add ORDERS PROCESSOR --pull --ack explicit
nats consumer next ORDERS PROCESSOR

# KV
nats kv add CONFIG
nats kv put CONFIG key value
nats kv get CONFIG key

SDKs

Official clients exist for Go, Rust, Python, Node.js, C#, Java, C, Elixir, and more. See NATS Clients.

References

Official Documentation

• Main Docs: https://docs.nats.io/
• JetStream: https://docs.nats.io/nats-concepts/jetstream
• Security / Auth: https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro
• Server Config: https://docs.nats.io/running-a-nats-service/configuration
• NATS by Example: https://natsbyexample.com

Local References

• K8s Helm Charts README: references/kubernetes/README.md
• K8s Chart Development (CLAUDE.md): references/kubernetes/CLAUDE.md — Build commands, architecture, values structure, CI workflows, and conventions.
• Dependencies: references/kubernetes/dependencies.md
• Helm Chart Dir: references/kubernetes/helm/
• Kine + NATS Example: references/kubernetes/kine-nats/

External Projects

• NATS Server: https://github.com/nats-io/nats-server
• K8s Helm Charts: https://github.com/nats-io/k8s
• NACK (JetStream Controller): https://github.com/nats-io/nack
• NATS CLI: https://github.com/nats-io/natscli
• NATS Surveyor: https://github.com/nats-io/nats-surveyor