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 across multiple regions, with each location running independent replicas. 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 Workload — A NATS cluster with per-location replica counts, exposing the client port (4222), cluster port (6222), gateway port (7222), and optionally the WebSocket port (8080).
  • Secrets — An opaque configuration secret containing the full NATS values, 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

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: 3
    - name: aws-us-west-2
      replicas: 2
    - name: aws-eu-central-1
      replicas: 4

resources:
  cpu: 100m
  memory: 256Mi

nats_defaults:
  image: controlplanecorporation/mynats:0.1
  port: 4222
  allowNonTls: true
  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

allowCIDR:
  - 0.0.0.0/0 # Restricts inbound access to the WebSocket port only

# You can add any valid NATS configuration under nats_extra_config
nats_extra_config: |
  jetstream: false

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

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

​
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 valid NATS server configuration to merge at runtime. Use this to enable JetStream, set max_payload, configure accounts, or add other NATS server options:
nats_extra_config: |
  jetstream: true
  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