diff --git a/SUMMARY.md b/SUMMARY.md index 39a8193..ac9fbae 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -102,6 +102,7 @@ * [Upgrading a Cluster](nats-server/nats_admin/upgrading_cluster.md) * [Slow Consumers](nats-server/nats_admin/slow_consumers.md) * [Signals](nats-server/nats_admin/signals.md) + * [Lame Duck Mode](nats-server/nats_admin/lame_duck_mode.md) * [NATS and Docker](nats-server/nats_docker/README.md) * [Tutorial](nats-server/nats_docker/nats-docker-tutorial.md) * [Docker Swarm](nats-server/nats_docker/docker_swarm.md) diff --git a/nats-server/nats_admin/README.md b/nats-server/nats_admin/README.md index 4fc1a05..ef96055 100644 --- a/nats-server/nats_admin/README.md +++ b/nats-server/nats_admin/README.md @@ -8,4 +8,5 @@ Managing a NATS server is simple, typical lifecycle operations include: * Monitoring the server via: * The monitoring [endpoint](../configuration/monitoring.md) and tools like [nats-top](../../nats-tools/nats_top/) * By subscribing to [system events](../configuration/sys_accounts/) +* Gracefully shut down a server with [Lame Duck Mode](lame_duck_mode.md) diff --git a/nats-server/nats_admin/lame_duck_mode.md b/nats-server/nats_admin/lame_duck_mode.md new file mode 100644 index 0000000..dd9438b --- /dev/null +++ b/nats-server/nats_admin/lame_duck_mode.md @@ -0,0 +1,28 @@ +# Lame Duck Mode + +In production we recommend that a server is shut down with ​lame duck mode​ +as a graceful way to slowly evict clients. With large deployments this +mitigates the "thundering herd" situation that will place CPU pressure on +servers as TLS enabled clients reconnect. + +## Server + +Lame duck mode is initiated by signaling the server: + +```text +nats-server --signal ldm +``` + +After entering lame duck mode, the server will stop accepting new connections, +wait for a 10 second grace period, then begin to evict clients over a period of time +configurable by the [lame_duck_duration](https://docs.nats.io/nats-server/configuration#runtime-configuration) +configuration option. This period defaults to 2 minutes. + +## Clients + +When entering lame duck mode, the server will send a message to clients. Some +maintainer supported clients will invoke an optional callback indicating that +a server is entering lame duck mode. This is used for cases where an application +can benefit from preparing for the short outage between the time it is evicted and +automatically reconnected to another server. +