Three controllers · Four API groups · v1beta1

NATS on Kubernetes,
declared as resources.

nats-operator is three Kubernetes controllers that deploy NATS clusters, own their auth plane, and manage and balance JetStream. It is for platform engineers who run NATS on Kubernetes. You can install all three controllers or only the ones you need.

$ kubectl -n nats-system get natscluster demo -o yaml live
status:
  version: 2.15.0
  replicas: 3
  readyReplicas: 3
  conditions:
    - type: Ready        status: "True"
    - type: Settled      status: "True"
    - type: Progressing  status: "False"
  endpoints:
    client: nats://demo.nats-system.svc:4222
  jetstream:
    metaLeader: demo-1
  servers:
    - demo-0   ready: true   rev: 3f9a1c
    - demo-1   ready: true   rev: 3f9a1c
    - demo-2   ready: true   rev: 3f9a1c

Controllers

01

Cluster controller

Deploys a NATS cluster from one NatsCluster and restarts it one server at a time. It also joins NATS clusters into a supercluster, or to a hub as leaves.

  • NatsCluster
02

Auth controller

Creates the JWT auth plane, which is a NATS operator with its accounts and users. It distributes the auth plane to the servers and writes each user’s credentials to a Secret.

  • NatsOperator
  • NatsSystemAccount
  • NatsAccount
  • NatsUser
03

JetStream controller

Manages streams, consumers, key-value buckets and object stores, and balances JetStream leadership and placement. It works through a NatsConnection, so the NATS cluster can be one that the cluster controller did not deploy.

  • NatsStream
  • NatsConsumer
  • NatsKeyValue
  • NatsObjectStore
  • NatsBalancer
  • NatsSystemBalancer
  • NatsClusterEvacuation

Install#

You need Kubernetes 1.33, Helm 3.14 and nats-server 2.15.0, or later.

To install all three controllers, run this command with <version> replaced by a release version:

helm install nats-operator oci://ghcr.io/mikluko/nats-operator/charts/nats-operator \
  --version <version> \
  --namespace nats-operator --create-namespace

Then follow the quickstart to deploy a NATS cluster with JetStream.

Install shows how to install a subset of the controllers, upgrade and uninstall. Chart and controller flags lists the chart’s values and the RBAC of each controller. The images and the chart are signed keylessly with cosign and carry a GitHub build provenance attestation. Verifying a release has the commands that check both.

Documentation

Install
How to install the chart with all three controllers or a subset, upgrade it and uninstall it.
Stories
The quickstart tutorial, then one guide per task, with the manifests to apply and the status to expect. The end-to-end harness applies the same manifests to kind clusters and waits for the same statuses.
API reference
Every kind, field and value of the four API groups.
NATS permissions
The nats-server subjects each controller requests, and the presets that grant them.
Telemetry
The OpenTelemetry metrics and traces each controller exports, and the Kubernetes events the controllers record.
Chart and controller flags
The chart’s values, the controllers’ flags, their metrics endpoints and the RBAC each controller is granted.
nats-operator v1 design
The scope, the architecture, the resource API and how each controller works.
ADR
The design decisions that are hard to reverse, one record each.
Esc
↓ ↑ Navigate Enter Select Esc Close