Skip to main content

​
Overview

NATS is an open-source, high-performance, lightweight messaging system optimized for cloud-native architectures. It supports pub/sub, queueing, and request/reply patterns. This template deploys a NATS super cluster using the official NATS image across multiple regions, with each location running independent replicas. JetStream can be enabled for persistent streams, durable consumers, K-V store, and object store — each replica gets its own dedicated volume. By default it exposes a WebSocket interface on port 443 via Control Plane’s TLS termination.

​
What Gets Created

  • GVC — A dedicated GVC spanning the configured locations.
  • Stateful NATS Workload — A NATS super cluster using the official nats image, with per-location replica counts, exposing the client port (4222), cluster port (6222), gateway port (7222), and optionally the WebSocket port (8080).
  • Volume Set (optional, when JetStream is enabled) — Persistent storage for JetStream data. Each replica gets its own volume, with optional autoscaling.
  • Secrets — An opaque configuration secret containing the full NATS server config, and an opaque extra data secret used for the nats_extra_config block.
  • Identity & Policy — An identity bound to the workload with reveal access to both secrets.
This template creates a GVC. If you plan to deploy multiple instances, you must assign a unique GVC name for each deployment.

​
Installation

This template has no external prerequisites. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations
Pulumi Icon Streamline Icon: https://streamlinehq.com

Pulumi

Declare templates in your Pulumi programs

​
Configuration

The default values.yaml for this template: 
gvc:
  name: nats-gvc
  locations:
    - name: aws-us-east-1
      replicas: 2
    - name: aws-us-west-2
      replicas: 2
    - name: aws-eu-central-1
      replicas: 2

resources:
  cpu: 100m
  memory: 256Mi

image: nats:2.11.6-alpine # official NATS image tag — bump to upgrade NATS version

nats_defaults:
  port: 4222
  cluster:
    listen: "0.0.0.0:6222"
    port: 6222
    noAdvertise: false
  gateway:
    listen: "0.0.0.0:7222"
    port: 7222

  websocket:
    enabled: true
    port: 8080
    compression: false
    noTls: true # Control Plane handles TLS termination
    # allowedOrigins: []  # Uncomment and add origins if needed
    # advertise: "ws://example.com:8080"  # Uncomment if different from default

allowCIDR:
  - 0.0.0.0/0 # Allow all traffic. Change to specific CIDRs to limit exposure.
              # Only applicable to the WebSocket port. Control Plane exposes it on port 443.

jetstream:
  enabled: false # set to true to enable persistent JetStream streaming and storage

volumeset:
  capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  autoscaling:
    enabled: false
    maxCapacity: 100
    minFreePercentage: 10
    scalingFactor: 1.2

# Add any additional valid NATS configuration here — appended to the server config at startup
nats_extra_config: ""

internalAccess: # Sets the internal firewall scope
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

​
Image

  • image — The NATS container image to use. Defaults to the official nats:2.11.6-alpine image. Bump the tag to upgrade the NATS version.

​
GVC and Locations

  • gvc.name — Name of the GVC to create. Must be unique per deployment if running multiple instances.
  • gvc.locations — List of locations where NATS replicas will run. Each entry requires:
    • name — The location identifier (e.g. aws-us-east-1).
    • replicas — Number of NATS replicas in that location. Set to 0 to suspend a location without removing it.

​
Resources

  • resources.cpu / resources.memory — CPU and memory allocated to each NATS replica.

​
JetStream

  • jetstream.enabled — When true, enables NATS’s built-in persistence layer, adding durable streams, consumers, K-V store, and object store on top of the core pub/sub model. Without it, NATS is purely in-memory.
When JetStream is enabled, each replica gets its own dedicated persistent volume (configured via volumeset).
Streams default to num_replicas: 1, meaning stream data lives on a single server. For streams that must survive a location outage, set num_replicas to 2 or higher in your application — this is configured per-stream, not in this template.

​
Volume Set

The volumeset block applies only when jetstream.enabled: true.
  • volumeset.capacity — Initial volume size in GiB per replica (minimum 10).
  • volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
    • maxCapacity — Maximum volume size in GiB.
    • minFreePercentage — Trigger a scale-up when free space drops below this percentage.
    • scalingFactor — Multiply the current capacity by this factor when scaling up.

​
WebSocket

  • nats_defaults.websocket.enabled — When true, exposes a WebSocket endpoint on the configured port. Control Plane handles TLS termination and serves it externally on port 443.
  • nats_defaults.websocket.port — Internal WebSocket port (default: 8080).

​
External Access

  • allowCIDR — CIDR ranges allowed to reach the WebSocket port from the internet. Defaults to 0.0.0.0/0 (open to all). Restrict this to limit exposure.
allowCIDR only applies to the WebSocket port. The NATS client port (4222), cluster port (6222), and gateway port (7222) are only accessible internally.

​
Internal Access

  • internalAccess.type — Controls which workloads can reach NATS on the client (4222), cluster (6222), and gateway (7222) ports:
TypeDescription
noneNo internal access allowed
same-gvcAllow access from all workloads in the same GVC
same-orgAllow access from all workloads in the same organization
workload-listAllow access only from specific workloads listed in workloads
Do not set internalAccess.type to none. NATS replicas must be able to communicate with each other across the cluster and gateway ports for the super cluster to function.

​
Extra NATS Configuration

  • nats_extra_config — Any additional valid NATS server configuration appended to the server config at startup. Use this to set max_payload, configure accounts, or add other NATS server options:
nats_extra_config: |
  max_payload: 8MB

​
Connecting to NATS

Internally (from workloads in the same GVC), connect on the standard NATS client port: 
nats://RELEASE_NAME-nats.GVC_NAME.cpln.local:4222
Externally via WebSocket, connect through the Control Plane endpoint on port 443: 
wss://RELEASE_NAME-nats.GVC_NAME.cpln.app

​
External References

NATS Documentation

Official NATS documentation

JetStream

NATS JetStream persistence and streaming

NATS Template

View the source files, default values, and chart definition