# nats-operator

> Three Kubernetes controllers that deploy NATS clusters, own their auth plane, and manage and balance JetStream.

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.

## Controllers

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

Kinds: `NatsCluster`.

Story: [A NATS cluster with JetStream](https://nats-operator.io/docs/stories/01-quickstart/index.md)

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

Kinds: `NatsOperator`, `NatsSystemAccount`, `NatsAccount`, `NatsUser`.

Story: [Put a NATS cluster under a NATS operator](https://nats-operator.io/docs/stories/02-auth-plane/index.md)

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

Kinds: `NatsStream`, `NatsConsumer`, `NatsKeyValue`, `NatsObjectStore`, `NatsBalancer`, `NatsSystemBalancer`, `NatsClusterEvacuation`.

Story: [Manage JetStream on a NATS cluster that you did not deploy](https://nats-operator.io/docs/stories/03-unmanaged/index.md)


## 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:

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

Then follow [the quickstart](https://nats-operator.io/docs/stories/01-quickstart/index.md) to deploy a NATS cluster with JetStream.

[Install](https://nats-operator.io/docs/install/index.md) shows how to install a subset of the controllers, upgrade and uninstall.
[Chart and controller flags](https://nats-operator.io/docs/reference/chart/index.md) 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](https://github.com/mikluko/nats-operator/blob/main/SECURITY.md#verifying-a-release) has the commands that check both.


## Documentation

- [Install](https://nats-operator.io/docs/install/index.md): How to install the chart with all three controllers or a subset, upgrade it and uninstall it.
- [Stories](https://nats-operator.io/docs/stories/index.md): 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](https://nats-operator.io/docs/reference/api/index.md): Every kind, field and value of the four API groups.
- [NATS permissions](https://nats-operator.io/docs/reference/nats-permissions/index.md): The nats-server subjects each controller requests, and the presets that grant them.
- [Telemetry](https://nats-operator.io/docs/reference/telemetry/index.md): The OpenTelemetry metrics and traces each controller exports, and the Kubernetes events the controllers record.
- [Chart and controller flags](https://nats-operator.io/docs/reference/chart/index.md): The chart's values, the controllers' flags, their metrics endpoints and the RBAC each controller is granted.
- [nats-operator v1 design](https://nats-operator.io/docs/design/v1/index.md): The scope, the architecture, the resource API and how each controller works.
- [Architecture decision records](https://nats-operator.io/docs/adr/index.md): The design decisions that are hard to reverse, one record each.

## Stories

1. [A NATS cluster with JetStream](https://nats-operator.io/docs/stories/01-quickstart/index.md)
1. [Put a NATS cluster under a NATS operator](https://nats-operator.io/docs/stories/02-auth-plane/index.md)
1. [Manage JetStream on a NATS cluster that you did not deploy](https://nats-operator.io/docs/stories/03-unmanaged/index.md)
1. [Let a team declare its own users and streams](https://nats-operator.io/docs/stories/04-team-self-service/index.md)
1. [Share a stream and a service between accounts](https://nats-operator.io/docs/stories/05-account-wiring/index.md)
1. [Build a supercluster across Kubernetes clusters](https://nats-operator.io/docs/stories/06-supercluster/index.md)
1. [Balance JetStream leaders and copies](https://nats-operator.io/docs/stories/07-balancing/index.md)
1. [Move a stream to another NATS cluster](https://nats-operator.io/docs/stories/08-stream-transfer/index.md)
1. [Deploy a production supercluster of three NATS clusters](https://nats-operator.io/docs/stories/09-acceptance/index.md)
1. [Join a NATS cluster to a hub as a leaf](https://nats-operator.io/docs/stories/10-leafnodes/index.md)
1. [Retire a NATS cluster](https://nats-operator.io/docs/stories/11-evacuation/index.md)
1. [Scrape the controllers' metrics over verified TLS](https://nats-operator.io/docs/stories/12-metrics/index.md)
1. [Add a NATS cluster to a supercluster that you did not deploy](https://nats-operator.io/docs/stories/13-join-supercluster/index.md)
1. [Adopt a NATS operator and accounts made with nsc](https://nats-operator.io/docs/stories/14-nsc-adoption/index.md)
