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 has been manually health check failed via the healthcheck/fail admin endpoint. See the health check filter architecture overview for more information.
The server is being hot restarted.
Individual listeners are being modified or removed via LDS.
Admin initiated drain via drain_listeners.
Each configured listener has a drain_type setting which controls when draining takes place. The currently supported values are:
Envoy will drain listeners in response to all three cases above (admin drain, 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.