repository·main·Indexed 18 days ago
https://github.com/nats-io/k8sHelm 3 charts and deployment examples for running NATS, NATS Streaming, and ecosystem tools on Kubernetes. Includes documentation for the NATS JetStream Controller (NACK) for managing Streams, Consumers, Key/Value, and Object Stores via CRDs; the NATS Account Server for JWT authentication; the nats-kafka connector for bridging NATS and Kafka; and the NATS Operator for automated cluster administration.
This repository provides Helm charts for various components in the NATS ecosystem. The primary charts available are:
NACK enables the management of JetStream resources through Kubernetes native objects.
Important Constraint: Resources managed by NACK are expected to be managed exclusively by the controller. If configuration state is mutated by an external client (e.g., via the NATS CLI directly), NACK will enforce the state defined in the Kubernetes CRD.
Managed Resources:
The NATS Helm chart allows you to override NATS configurations and Kubernetes resources using two mechanisms: merge and patch. This prevents you from having to redefine the entire configuration block when you only want to add or change specific fields.
Merging uses the Helm merge function. It is used to inject new keys or values into existing configuration blocks. For example, you can use merge to add NATS accounts or update natsBox contexts.
Patching uses JSON Patch. This is useful for precise operations like adding an item to the end of an array (e.g., adding a new route to a cluster) without overwriting the entire list.
# Example: Using merge to add accounts
config:
merge:
accounts:
A:
users:
- {user: a, password: a}
# Example: Using patch to add a route to the end of a list
config:
cluster:
enabled: true
patch:
- op: add
path: /routes/-
value: nats://demo.nats.io:6222The Helm chart provides two primary services:
service: Intended for NATS Clients. By default, it is a ClusterIP, but can be changed to LoadBalancer via service.merge.spec.type. It exposes nats, websocket, leafnodes, and mqtt ports.
service.headlessService: Used for NATS Server discovery within the StatefulSet. It is primarily used for Cluster Route connections.
headlessService (defaults to *.<headless-service-name>).The NATS Account Server is an HTTP server used to host account JWTs for NATS Server 2.0 account authentication. This enables secure multi-tenancy by allowing the NATS server to fetch account configurations from an external HTTP source.
To install the chart, add the NATS Helm repository and run the install command:
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install my-nats-account-server nats/nats-account-serverTo remove the local testing environment and all associated volumes, use the docker compose down command with the -v flag.
# destroy docker compose stack
docker compose down -vThe NATS Operator automates the creation and administration of NATS clusters on Kubernetes. You can install it using Helm. By default, this deploys both NATS and the NATS Operator with default configurations.
Prerequisites:
$ helm install --name my-release .The development stack is managed via Docker Compose. It spins up a k3s instance. After starting the stack, you must extract the kubeconfig from the container to interact with the cluster locally.
Steps:
k3s to initialize.k3s.yaml configuration from the container to your local directory.KUBECONFIG environment variable.kine directory.# start docker compose stack
docker compose up -d --build
# wait until k3s has started
# then copy the kubeconfig to current directory
docker compose cp k3s:/etc/rancher/k3s/k3s.yaml ./k3s.yaml
export KUBECONFIG="$(pwd)/k3s.yaml"
# run load test
./kine/scripts/test-loadNATS uses a preStop hook to enter lame duck mode during pod shutdown. To ensure clients are evicted gracefully, the podTemplate.terminationGracePeriodSeconds must be large enough to accommodate:
config.lameDuckGracePeriod (time before eviction starts)config.lameDuckDuration (time spent spreading evictions)Health probes (startupProbe, readinessProbe, livenessProbe) are automatically applied if config.monitor is enabled (the default).
config:
lameDuckGracePeriod: 10s
lameDuckDuration: 2m
container:
livenessProbe:
periodSeconds: 60
podTemplate:
# 10s grace period + 2m duration + 20s overhead
terminationGracePeriodSeconds: 150To install the nats-kafka connector, add the NATS Helm repository and install the chart using a custom values file.
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install -f my-values.yaml my-nats-kafka nats/nats-kafkaTo develop or test the controller locally, you can build and run the binary manually.
1. Build the controller:
make jetstream-controller2. Run the controller: Point the controller to your local kubeconfig and your NATS server URL:
./jetstream-controller -kubeconfig ~/.kube/config -s nats://localhost:4222Tips:
klog. Use the -v flag to adjust verbosity. For example, ./jetstream-controller -v=10 will print raw HTTP requests and responses.nats-server -DV -js./jetstream-controller -kubeconfig ~/.kube/config -s nats://localhost:4222To install NATS on Kubernetes, use the Helm 3 charts provided in this repository. You must first add the NATS Helm repository to your local Helm client and update your local chart cache before installing.
# Add the NATS Helm repository
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
# Update your local helm repositories
helm repo update
# Install NATS with the release name 'my-nats'
helm install my-nats nats/nats