A reload is not a restart
Nginx reloads are described as zero-downtime, and they usually are — which is exactly why the exceptions are confusing. Understanding what a reload actually does makes the difference between a five-second change and a five-minute outage.
What happens on reload
The master process re-reads the configuration, starts new worker processes with it, and asks the old workers to finish their current connections and exit. Listening sockets are inherited, so no connection is refused.
Where “zero downtime” stops being true
- New listen directives. A reload cannot open a port that was not open before if the master did not have it — depending on the setup, new sockets are created, but a firewall change is still needed.
- Upstream DNS. Nginx resolves names in
upstreamblocks at start, not at reload, unless aresolveris configured. A backend that moved addresses will be proxied to the old IP until a real restart. - Long-lived connections. Websockets and gRPC streams keep old workers alive for hours. That is fine, unless you expected the old code to be gone.
- Certificates. A reload does re-read certificate files. A restart is only needed if the path changed and the old path no longer exists.
The check I always run
nginx -t && systemctl reload nginx
sleep 2
ss -tnp | grep nginx | wc -l
ps -o pid,etime,cmd -C nginx
If old workers are still there after a minute with no active connections, something is holding them — and that something is usually a client that never closed a stream.