How do I configure timeouts?

Envoy supports a wide range of timeouts that may need to be configured depending on the deployment. This page summarizes the most important timeouts used in various scenarios.

Attention

This is not an exhaustive list of all of the configurable timeouts that Envoy supports. Depending on the deployment additional configuration may be required.

HTTP/gRPC

Connection timeouts

Connection timeouts apply to the entire HTTP connection and all streams the connection carries.

  • The HTTP protocol idle timeout is defined in a generic message used by both the HTTP connection manager as well as upstream cluster HTTP connections. The idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams. The default idle timeout if not otherwise specified is 1 hour. To modify the idle timeout for downstream connections use the common_http_protocol_options field in the HTTP connection manager configuration. To modify the idle timeout for upstream connections use the common_http_protocol_options field in the cluster configuration.

Stream timeouts

Stream timeouts apply to individual streams carried by an HTTP connection. Note that a stream is an HTTP/2 and HTTP/3 concept, however internally Envoy maps HTTP/1 requests to streams so in this context request/stream is interchangeable.

  • The HTTP connection manager request_timeout is the amount of time the connection manager will allow for the entire request stream to be received by the client.

    Attention

    This timeout is not enforced by default as it is not compatible with streaming requests (requests that never end). See the stream idle timeout that follows. However, if using the buffer filter, it is recommended to configure this timeout.

  • The HTTP connection manager stream_idle_timeout is the amount of time that the connection manager will allow a stream to exist with no upstream or downstream activity. The default stream idle timeout is 5 minutes. This timeout is strongly recommended for streaming APIs (requests or responses that never end).

Route timeouts

Envoy supports additional stream timeouts at the route level, as well as overriding some of the stream timeouts already introduced above.

  • A route timeout is the amount of time that Envoy will wait for the upstream to respond with a complete response. This timeout does not start until the entire downstream request stream has been received.

    Attention

    This timeout defaults to 15 seconds, however, it is not compatible with streaming responses (responses that never end), and will need to be disabled. Stream idle timeouts should be used in the case of streaming APIs as described elsewhere on this page.

  • The route idle_timeout allows overriding of the HTTP connection manager stream_idle_timeout and does the same thing.

  • The route per_try_timeout can be configured when using retries so that individual tries using a shorter timeout than the overall request timeout described above. This type of timeout will not work with streaming APIs (in which retries are typically not possible) but is useful for decreasing the tail latency of non-streaming APIs.

TCP

  • The cluster connect_timeout specifies the amount of time Envoy will wait for an upstream TCP connection to be established. This timeout has no default, but is required in the configuration.

    Attention

    For TLS connections, the connect timeout includes the TLS handshake.

  • The TCP proxy idle_timeout is the amount of time that the TCP proxy will allow a connection to exist with no upstream or downstream activity. The default idle timeout if not otherwise specified is 1 hour.