Configuration Guide
Customize your NATS cluster configuration for optimal performance and reliability.
Cluster Configuration
Version Management
Upgrade your NATS version:
- Navigate to your cluster
- Click Update
- Select the new version
- Apply changes
warning
Version upgrades trigger a rolling restart. Plan upgrades during low-traffic periods.
Resource Scaling
Compute Class
| Class | Description | Use Case |
|---|---|---|
| Eco | Shared resources, cost-effective | Development, testing |
| Standard | Balanced performance | Production |
| Production | Dedicated resources | Critical workloads |
Flavor Options
Flavors vary by compute class. See Create Cluster for detailed specifications.
| Compute Class | Small | Medium | Large | XLarge |
|---|---|---|---|---|
| Eco (1:2) | 0.5 vCPU, 1 Gi | 1 vCPU, 2 Gi | 2 vCPU, 4 Gi | 3 vCPU, 6 Gi |
| Standard (1:4) | 1 vCPU, 4 Gi | 2 vCPU, 8 Gi | 4 vCPU, 16 Gi | 15 vCPU, 58 Gi |
| Production (1:4) | 1 vCPU, 4 Gi | 2 vCPU, 8 Gi | 4 vCPU, 16 Gi | 6 vCPU, 28 Gi |
Scaling Process
- Go to cluster settings
- Select new compute class or flavor
- Apply changes
- Rolling update occurs automatically
Replica Configuration
| Replicas | Fault Tolerance | Performance |
|---|---|---|
| 1 | None | Highest |
| 3 | 1 node failure | Balanced |
| 5 | 2 node failures | Redundant |
| 7 | 3 node failures | Maximum 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
- Navigate to cluster settings
- Toggle JetStream on/off
- Apply changes
warning
Disabling JetStream will delete all streams, consumers, KV stores, and object stores.
Stream Configuration
Storage Types
| Type | Persistence | Performance | Use Case |
|---|---|---|---|
| File | Persistent | Good | Production |
| Memory | Non-persistent | Excellent | Caching, 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
| Setting | Description |
|---|---|
| 1 | No replication (development) |
| 3 | Standard HA |
| 5 | Maximum durability |
Consumer Configuration
Delivery Policies
| Policy | Start From |
|---|---|
all | Beginning of stream |
new | New messages only |
last | Last message |
byStartSequence | Specific sequence number |
byStartTime | Specific timestamp |
lastPerSubject | Last message per subject |
Acknowledgment Policies
| Policy | Description |
|---|---|
none | No acknowledgment required |
all | Ack all messages up to sequence |
explicit | Each 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
| Setting | Description | Default |
|---|---|---|
| History | Revisions per key | 1 |
| TTL | Entry expiration | None |
| Max Value Size | Maximum value bytes | -1 (unlimited) |
| Max Bytes | Total storage | -1 (unlimited) |
| Replicas | Number of copies | 1 |
Object Store Configuration
| Setting | Description | Default |
|---|---|---|
| Max Bytes | Total storage | -1 (unlimited) |
| Storage | File or Memory | File |
| Replicas | Number of copies | 1 |
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
- Enable Auto-Reconnect: Always configure automatic reconnection
- Set Appropriate Timeouts: Balance between responsiveness and reliability
- 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:
| Setting | Recommendation |
|---|---|
| Batch publishing | Publish in batches of 100-1000 |
| Async publishing | Use fire-and-forget when durability not needed |
| Consumer parallelism | Multiple 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
| Setting | Recommendation |
|---|---|
| Message size | Keep messages small (under 1MB) |
| Stream retention | Set appropriate limits |
| Consumer prefetch | Limit max_ack_pending |
Latency Optimization
| Setting | Recommendation |
|---|---|
| Replicas | Use 3 for balanced latency/durability |
| Storage | Use Memory for lowest latency |
| Acknowledgment | Use none policy if durability not critical |
Monitoring Configuration
Metrics to Track
| Metric | Alert Threshold |
|---|---|
| CPU Usage | >80% |
| Memory Usage | >85% |
| Connection Count | Near max connections |
| Message Rate | Unexpected drops |
| Consumer Lag | >10000 pending |
Setting Up Alerts
- Go to Monitoring → Alerts
- Create alert rule for NATS metrics
- Configure notification channels
- 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
- Check stream storage limits
- Review message retention settings
- Purge old messages if needed
- Consider Memory → File storage
Slow Consumers
- Increase consumer instances
- Use queue groups for load distribution
- Optimize message processing
- Increase max_ack_pending
Connection Issues
- Verify connection string
- Check network connectivity
- Review firewall rules
- Ensure cluster is running