Skip to main content

Configuration Guide

Customize your NATS cluster configuration for optimal performance and reliability.

Cluster Configuration​

Version Management​

Upgrade your NATS version:

  1. Navigate to your cluster
  2. Click Update
  3. Select the new version
  4. Apply changes
warning

Version upgrades trigger a rolling restart. Plan upgrades during low-traffic periods.

Resource Scaling​

Compute Class​

ClassDescriptionUse Case
EcoShared resources, cost-effectiveDevelopment, testing
StandardBalanced performanceProduction
ProductionDedicated resourcesCritical workloads

Flavor Options​

Flavors vary by compute class. See Create Cluster for detailed specifications.

Compute ClassSmallMediumLargeXLarge
Eco (1:2)0.5 vCPU, 1 Gi1 vCPU, 2 Gi2 vCPU, 4 Gi3 vCPU, 6 Gi
Standard (1:4)1 vCPU, 4 Gi2 vCPU, 8 Gi4 vCPU, 16 Gi15 vCPU, 58 Gi
Production (1:4)1 vCPU, 4 Gi2 vCPU, 8 Gi4 vCPU, 16 Gi6 vCPU, 28 Gi

Scaling Process​

  1. Go to cluster settings
  2. Select new compute class or flavor
  3. Apply changes
  4. Rolling update occurs automatically

Replica Configuration​

ReplicasFault TolerancePerformance
1NoneHighest
31 node failureBalanced
52 node failuresRedundant
73 node failuresMaximum durability
Production

Use 3 replicas for production. This provides fault tolerance while maintaining good performance. Use 5 or 7 replicas for mission-critical systems.

JetStream Configuration​

Enabling/Disabling JetStream​

  1. Navigate to cluster settings
  2. Toggle JetStream on/off
  3. Apply changes
warning

Disabling JetStream will delete all streams, consumers, KV stores, and object stores.

Stream Configuration​

Storage Types​

TypePersistencePerformanceUse Case
FilePersistentGoodProduction
MemoryNon-persistentExcellentCaching, temp data

Retention Settings​

// Limits-based retention
{
retention: 'limits',
max_msgs: 1000000,
max_bytes: 1073741824, // 1GB
max_age: 604800000000000 // 7 days (nanoseconds)
}

// Interest-based retention
{
retention: 'interest'
// Messages deleted when no consumers
}

// Work queue retention
{
retention: 'workqueue'
// Messages deleted after acknowledgment
}

Replication​

SettingDescription
1No replication (development)
3Standard HA
5Maximum durability

Consumer Configuration​

Delivery Policies​

PolicyStart From
allBeginning of stream
newNew messages only
lastLast message
byStartSequenceSpecific sequence number
byStartTimeSpecific timestamp
lastPerSubjectLast message per subject

Acknowledgment Policies​

PolicyDescription
noneNo acknowledgment required
allAck all messages up to sequence
explicitEach message acknowledged individually

Redelivery Settings​

{
max_deliver: 5, // Maximum delivery attempts
ack_wait: 30000000000, // 30 seconds (nanoseconds)
max_ack_pending: 1000 // Maximum unacked messages
}

Key-Value Store Configuration​

SettingDescriptionDefault
HistoryRevisions per key1
TTLEntry expirationNone
Max Value SizeMaximum value bytes-1 (unlimited)
Max BytesTotal storage-1 (unlimited)
ReplicasNumber of copies1

Object Store Configuration​

SettingDescriptionDefault
Max BytesTotal storage-1 (unlimited)
StorageFile or MemoryFile
ReplicasNumber of copies1

Connection Configuration​

Connection String Format​

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

Example:

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

Client Options​

JavaScript/TypeScript​

import { connect } from 'nats';

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

// Connection options
reconnect: true,
maxReconnectAttempts: -1, // Unlimited
reconnectTimeWait: 1000, // 1 second

// Timeouts
timeout: 10000, // 10 seconds
pingInterval: 30000, // 30 seconds

// Buffer settings
maxPingOut: 2,
noEcho: true
});

Go​

nc, err := nats.Connect(
"nats://my-nats.my-project-abc123:4222",
nats.MaxReconnects(-1),
nats.ReconnectWait(time.Second),
nats.Timeout(10*time.Second),
nats.PingInterval(30*time.Second),
nats.MaxPingsOutstanding(2),
)

Python​

nc = await nats.connect(
"nats://my-nats.my-project-abc123:4222",
reconnect_time_wait=1,
max_reconnect_attempts=-1,
connect_timeout=10,
ping_interval=30
)

Connection Best Practices​

  1. Enable Auto-Reconnect: Always configure automatic reconnection
  2. Set Appropriate Timeouts: Balance between responsiveness and reliability
  3. Handle Disconnections: Implement proper error handling
nc.status().subscribe((status) => {
switch (status.type) {
case 'disconnect':
console.log('Disconnected from NATS');
break;
case 'reconnect':
console.log('Reconnected to NATS');
break;
case 'error':
console.error('NATS error:', status.data);
break;
}
});

Environment Variables​

Configure your application with these environment variables:

# Connection
NATS_URL=nats://my-nats.my-project-abc123:4222

# Optional authentication
NATS_USER=admin
NATS_PASSWORD=your-password

# Managed TLS is not available yet; SailOps endpoints currently use nats://.

Performance Tuning​

Message Throughput​

For high throughput:

SettingRecommendation
Batch publishingPublish in batches of 100-1000
Async publishingUse fire-and-forget when durability not needed
Consumer parallelismMultiple consumers with queue groups
// Batch publishing
const js = nc.jetstream();
const promises = messages.map(msg =>
js.publish('events.batch', JSON.stringify(msg))
);
await Promise.all(promises);

Memory Optimization​

SettingRecommendation
Message sizeKeep messages small (under 1MB)
Stream retentionSet appropriate limits
Consumer prefetchLimit max_ack_pending

Latency Optimization​

SettingRecommendation
ReplicasUse 3 for balanced latency/durability
StorageUse Memory for lowest latency
AcknowledgmentUse none policy if durability not critical

Monitoring Configuration​

Metrics to Track​

MetricAlert Threshold
CPU Usage>80%
Memory Usage>85%
Connection CountNear max connections
Message RateUnexpected drops
Consumer Lag>10000 pending

Setting Up Alerts​

  1. Go to Monitoring → Alerts
  2. Create alert rule for NATS metrics
  3. Configure notification channels
  4. Set appropriate thresholds

Backup and Recovery​

Stream Backup​

Export stream data for backup:

const stream = await js.streams.get('ORDERS');

// Export messages
const consumer = await stream.getConsumer('backup-consumer');
const messages = [];

for await (const msg of consumer.consume()) {
messages.push({
subject: msg.subject,
data: msg.data,
headers: msg.headers
});
msg.ack();
}

// Save to file
fs.writeFileSync('backup.json', JSON.stringify(messages));

Stream Recovery​

Import backed up data:

const backup = JSON.parse(fs.readFileSync('backup.json'));
const js = nc.jetstream();

for (const msg of backup) {
await js.publish(msg.subject, msg.data, {
headers: msg.headers
});
}

Troubleshooting​

High Memory Usage​

  1. Check stream storage limits
  2. Review message retention settings
  3. Purge old messages if needed
  4. Consider Memory → File storage

Slow Consumers​

  1. Increase consumer instances
  2. Use queue groups for load distribution
  3. Optimize message processing
  4. Increase max_ack_pending

Connection Issues​

  1. Verify connection string
  2. Check network connectivity
  3. Review firewall rules
  4. Ensure cluster is running

Next Steps​