Skip to main content

​
Overview

Cluster options enable multiple NATS servers to communicate and share message routing information, creating a distributed system with high availability and horizontal scalability.

​
Command Line Flags

​
--cluster
string
Cluster URL for solicited routes. Format: nats://host:port
nats-server --cluster nats://0.0.0.0:6222
​
--cluster_listen
string
Cluster URL from which members can solicit routes.
nats-server --cluster_listen nats://0.0.0.0:6222
​
--routes
string
Comma-separated list of routes to solicit and connect to.
nats-server --routes "nats://server1:6222,nats://server2:6222"
​
--cluster_name
string
Cluster name. If not set, one will be dynamically generated.
nats-server --cluster_name "production-cluster"
​
--cluster_advertise
string
Cluster URL to advertise to other servers. Useful when behind NAT.
nats-server --cluster_advertise "nats://public.example.com:6222"
​
--no_advertise
boolean
Do not advertise known cluster information to clients.
nats-server --no_advertise
​
--connect_retries
integer
Number of connect retries for implicit routes.
nats-server --connect_retries 5

​
Configuration File Options

​
Basic Cluster Configuration

​
cluster.name
string
Cluster name identifier.
cluster {
  name: "production-cluster"
}
​
cluster.host
string
default:"0.0.0.0"
Host address to bind for cluster connections.
cluster {
  host: "0.0.0.0"
}
​
cluster.port
integer
default:"6222"
Port for cluster connections. Default is 6222.
cluster {
  port: 6222
}
​
cluster.listen
string
Combined host:port listen specification.
cluster {
  listen: "0.0.0.0:6222"
}

​
Route Configuration

​
cluster.routes
array
Array of route URLs to connect to other cluster members.
cluster {
  routes: [
    "nats://server1.example.com:6222",
    "nats://server2.example.com:6222",
    "nats://server3.example.com:6222"
  ]
}
​
cluster.advertise
string
URL to advertise to other servers in the cluster.
cluster {
  advertise: "nats://public.example.com:6222"
}
​
cluster.no_advertise
boolean
default:"false"
Prevent advertising cluster information to clients.
cluster {
  no_advertise: true
}

​
Authentication

​
cluster.username
string
Username for route authentication.
cluster {
  username: "route_user"
}
​
cluster.password
string
Password for route authentication.
cluster {
  password: "route_password"
}
​
cluster.authorization
object
Route permissions configuration.
cluster {
  authorization {
    user: "route_user"
    password: "route_password"
    timeout: 2
  }
}

​
Advanced Options

​
cluster.connect_retries
integer
default:"0"
Number of times to retry connecting to discovered routes.
cluster {
  connect_retries: 10
}
​
cluster.pool_size
integer
default:"-1"
Number of pooled connections per route. -1 means automatic.
cluster {
  pool_size: 5
}
​
cluster.compression
object
Compression configuration for cluster connections.
cluster {
  compression {
    mode: "s2_auto"
  }
}
Available modes: s2_auto, s2_fast, s2_better, s2_best, disabled
​
cluster.ping_interval
duration
default:"30s"
Interval for pinging route connections.
cluster {
  ping_interval: "30s"
}
​
cluster.write_deadline
duration
Write deadline for route connections.
cluster {
  write_deadline: "5s"
}

​
Configuration Examples

​
Three-Node Cluster

Server 1 Configuration: 
port: 4222
server_name: "nats-1"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-2:6222",
    "nats://nats-3:6222"
  ]
}
Server 2 Configuration: 
port: 4222
server_name: "nats-2"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-1:6222",
    "nats://nats-3:6222"
  ]
}
Server 3 Configuration: 
port: 4222
server_name: "nats-3"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-1:6222",
    "nats://nats-2:6222"
  ]
}

​
Cluster with Authentication

port: 4222
server_name: "nats-secure"

cluster {
  name: "secure-cluster"
  listen: "0.0.0.0:6222"
  
  authorization {
    user: "cluster_route"
    password: "$2a$11$3kIDaCxw.Glsl1.u5nKa6eUnNDLV5HV9tIuUp7EHhMt6Nm9myW1aS"
    timeout: 2
  }
  
  routes: [
    "nats://cluster_route:cluster_password@nats-2:6222",
    "nats://cluster_route:cluster_password@nats-3:6222"
  ]
}

​
Cluster Behind NAT

port: 4222
server_name: "nats-aws-1"

cluster {
  name: "cloud-cluster"
  listen: "0.0.0.0:6222"
  advertise: "nats://public-ip-1.example.com:6222"
  
  routes: [
    "nats://public-ip-2.example.com:6222",
    "nats://public-ip-3.example.com:6222"
  ]
}

​
Cluster with Compression

port: 4222
server_name: "nats-compressed"

cluster {
  name: "compressed-cluster"
  listen: "0.0.0.0:6222"
  
  compression {
    mode: "s2_auto"
  }
  
  routes: [
    "nats://nats-2:6222",
    "nats://nats-3:6222"
  ]
}

​
Cluster Management

​
Verifying Cluster Status

Check cluster status via monitoring endpoint: 
curl http://localhost:8222/routez

​
Dynamic Cluster Growth

New servers can join by configuring routes to existing members: 
cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  # Only need to route to one existing member
  routes: [
    "nats://nats-1:6222"
  ]
}
The new server will discover all other cluster members automatically.

​
Best Practices

  1. Cluster Name: Use consistent cluster names across all servers
  2. Full Mesh: Configure routes to all other cluster members for fastest convergence
  3. Odd Numbers: Use odd numbers of servers (3, 5, 7) for better consensus
  4. Authentication: Always use authentication for route connections in production
  5. Network Isolation: Keep cluster traffic on dedicated network interfaces when possible
  6. Compression: Enable compression for geo-distributed clusters to reduce bandwidth
  7. Monitoring: Monitor route connections through /routez endpoint
  8. DNS/Discovery: Use DNS or service discovery for dynamic cluster membership

​
Troubleshooting

​
Connection Issues

  • Verify firewall rules allow port 6222 (or custom cluster port)
  • Check that routes are using correct URLs and authentication
  • Review server logs for connection errors

​
Split Brain Prevention

  • Ensure consistent cluster names across all servers
  • Configure routes to multiple cluster members
  • Monitor cluster connectivity via /routez

Server Options

Core server configuration

TLS Options

Secure cluster connections with TLS

JetStream Options

Cluster JetStream for distributed persistence

Build docs developers (and LLMs) love

Get started for freeTalk to us