Skip to main content

Create a NATS Cluster

Deploy a fully managed NATS cluster for your messaging needs.

Prerequisites​

Before creating a NATS cluster, ensure you have:

  • An active SailOps account
  • A project created in your organization
  • Appropriate permissions (Owner, Maintainer, or Developer role)

Creating a Cluster​

Step 1: Navigate to Services​

  1. Log in to your SailOps dashboard
  2. Select your project from the sidebar
  3. Click Services in the navigation

Step 2: Create a NATS Cluster​

Click Create Service and select NATS to open the creation form.

Step 3: Configure Basic Settings​

Cluster Name​

Enter a unique name for your cluster:

  • Must start with a lowercase letter
  • Can contain lowercase letters, numbers, and hyphens
  • Must end with a letter or number
  • Cannot be changed after creation
Examples: my-nats, production-mq, events-cluster

NATS Version​

Select the NATS version:

VersionRecommendation
2.10Stable, well-tested
2.11Latest stable
2.12Newest features

Step 4: Configure Resources​

Compute Class​

Choose based on your workload:

ClassBest For
EcoDevelopment, testing, low-traffic
StandardProduction workloads
ProductionCritical systems, guaranteed resources

Flavor​

Select the resource allocation. Resources vary by compute class:

Eco Class (1:2 ratio)​
FlavorCPUMemoryRecommended For
Small0.51 GiDevelopment
Medium12 GiTesting
Large24 GiLow-traffic production
XLarge36 GiMedium workloads
Standard Class (1:4 ratio)​
FlavorCPUMemoryRecommended For
Small14 GiDevelopment
Medium28 GiProduction
Large416 GiHigh throughput
XLarge1558 GiEnterprise scale
Production Class (1:4 ratio)​
FlavorCPUMemoryRecommended For
Small14 GiCritical development
Medium28 GiProduction
Large416 GiHigh throughput
XLarge628 GiMission critical

Replicas​

Configure cluster size:

ReplicasDescription
1Single node, development only
3High availability (recommended)
5Enhanced fault tolerance
7Maximum fault tolerance
Production

Always use 3 or more replicas for production deployments to ensure high availability.

Step 5: Enable JetStream​

JetStream provides persistence capabilities:

  • Streams - Persistent message storage
  • Key-Value - Distributed configuration
  • Object Store - Large file storage
tip

JetStream is disabled by default. Enable it if you need persistent messaging, key-value stores, or object storage. For pure pub/sub without persistence, you can leave it disabled.

Step 6: Review and Create​

  1. Review your configuration
  2. Click Create Cluster
  3. Wait for the cluster to become ready (typically 1-2 minutes)

Cluster Detail Tabs​

Once created, your NATS cluster detail view has the following tabs:

TabDescription
OverviewStatus, connection information, configuration summary
UsersCreate and manage NATS users and their permissions
JetStreamManage streams, consumers, key-value stores, and object stores (visible when JetStream is enabled)
LogsReal-time and historical cluster logs
ObservabilityConnection, message, and resource usage metrics

Connection Information​

Once your cluster is ready, you'll see connection details:

Internal Connection​

For containers in the same project:

nats://{cluster-name}.{namespace}:4222

Example:

nats://my-nats.my-project-abc123:4222

Connection Code Examples​

Node.js​

import { connect } from 'nats';

const nc = await connect({
servers: 'nats://my-nats.my-project-abc123:4222'
});

// Publish a message
await nc.publish('events.user.signup', JSON.stringify({ userId: '123' }));

// Subscribe to messages
const sub = nc.subscribe('events.user.*');
for await (const msg of sub) {
console.log(`Received: ${msg.data}`);
}

Go​

import "github.com/nats-io/nats.go"

nc, err := nats.Connect("nats://my-nats.my-project-abc123:4222")
if err != nil {
log.Fatal(err)
}
defer nc.Close()

// Publish a message
nc.Publish("events.user.signup", []byte(`{"userId":"123"}`))

// Subscribe to messages
nc.Subscribe("events.user.*", func(m *nats.Msg) {
fmt.Printf("Received: %s\n", string(m.Data))
})

Python​

import asyncio
import nats

async def main():
nc = await nats.connect("nats://my-nats.my-project-abc123:4222")

# Publish a message
await nc.publish("events.user.signup", b'{"userId":"123"}')

# Subscribe to messages
async def message_handler(msg):
print(f"Received: {msg.data.decode()}")

await nc.subscribe("events.user.*", cb=message_handler)

asyncio.run(main())

Post-Creation Tasks​

After creating your cluster, consider:

1. Create Streams​

If using JetStream, create streams for persistent messaging:

  1. Go to your cluster details
  2. Click the JetStream tab
  3. Click Create Stream
  4. Configure subjects and retention

2. Set Up Key-Value Stores​

For distributed configuration:

  1. Go to the Key-Value section
  2. Click Create KV Store
  3. Configure storage and history

3. Configure Monitoring​

Set up alerts for:

  • Connection count thresholds
  • Message rate anomalies
  • Consumer lag

4. Update Your Application​

Add the NATS connection string to your application's environment variables.

Scaling Your Cluster​

Vertical Scaling​

Increase resources by:

  1. Go to cluster settings
  2. Click Update
  3. Select a larger flavor
  4. Apply changes (rolling update)

Horizontal Scaling (Replicas)​

Increase replicas for:

  • Higher availability
  • Better fault tolerance
  • Improved performance
caution

Reducing replicas may cause data loss in JetStream. Always increase replicas, don't decrease in production.

Troubleshooting​

Cluster Not Ready​

If the cluster stays in "Creating" state:

  1. Check project resource quotas
  2. Verify network configuration
  3. Contact support if issues persist

Connection Refused​

If clients can't connect:

  1. Verify the connection string
  2. Check if the cluster is running
  3. Ensure containers are in the same project
  4. Check network policies

Authentication Errors​

If authentication fails:

  1. Verify credentials are correct
  2. Check if password was set during creation
  3. Reset password if needed

Next Steps​