Draining is the process by which Envoy attempts to gracefully shed connections in response to various events. Draining occurs at the following times:
The server is being hot restarted.
Individual listeners are being modified or removed via LDS.
Envoy will drain listeners in response to all three cases above (admin health fail, hot restart, and LDS update/remove). This is the default setting.
Envoy will drain listeners only in response to the 2nd and 3rd cases above (hot restart and LDS update/remove). This setting is useful if Envoy is hosting both ingress and egress listeners. It may be desirable to set modify_only on egress listeners so they only drain during modifications while relying on ingress listener draining to perform full server draining when attempting to do a controlled shutdown.
Note that although draining is a per-listener concept, it must be supported at the network filter level. Currently the only filters that support graceful draining are HTTP connection manager, Redis, and Mongo.
Listeners can also be stopped via drain_listeners. In this case, they are directly stopped (with out going through the actual draining process) on worker threads, so that they will not accept any new requests.