Cluster Options

Configure NATS server clustering for high availability and horizontal scaling

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

Related Configuration

Server Options

Core server configuration

TLS Options

Secure cluster connections with TLS

JetStream Options

Cluster JetStream for distributed persistence