Draining

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.

Each configured listener has a drain_type setting which controls when draining takes place. The currently supported values are:

default

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.

modify_only

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.