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.

• 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:

default

Envoy will drain listeners in response to all three cases above (admin drain, 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.