Skip to content

docs: fix the timeout behavior explanation #41783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: fix the timeout behavior explanation #41783

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a649e9
docs: fix the timeout behavior explanation
agrawroh Oct 30, 2025
06f0ad9
Update docs/root/faq/configuration/timeouts.rst
agrawroh Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 37 additions & 14 deletions docs/root/faq/configuration/timeouts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,15 @@ Connection timeouts apply to the entire HTTP connection and all streams the conn

* The HTTP protocol :ref:`idle_timeout <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.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
:ref:`common_http_protocol_options
cluster HTTP connections. The idle timeout is defined as the period in which there are no active
requests or streams. When the idle timeout is reached, the connection will be closed. For HTTP/2
downstream connections, a drain sequence will occur prior to closing the connection (see
:ref:`drain_timeout <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`
below). For other connection types, the connection terminates directly. Note that idle timeout
only fires when there are no active streams, unlike :ref:`max_connection_duration
<envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_connection_duration>` which can trigger
while streams are active. The default idle timeout if not otherwise specified is *1 hour*. To modify
the idle timeout for downstream connections use the :ref:`common_http_protocol_options
<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options>`
field in the HTTP connection manager configuration. To modify the idle timeout for upstream
connections use the
Expand All @@ -35,20 +40,38 @@ Connection timeouts apply to the entire HTTP connection and all streams the conn
* The HTTP protocol :ref:`max_connection_duration <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_connection_duration>`
is defined in a generic message used by both the HTTP connection manager as well as upstream cluster
HTTP connections. The maximum connection duration is the time after which a downstream or upstream
connection will be drained and/or closed, starting from when it was first established. If there are no
active streams, the connection will be closed. If there are any active streams, the drain sequence will
kick-in, and the connection will be force-closed after the drain period. The default value of max connection
duration is *0* or unlimited, which means that the connections will never be closed due to aging. It could
be helpful in scenarios when you are running a pool of Envoy edge-proxies and would want to close a
downstream connection after some time to prevent stickiness. It could also help to better load balance the
overall traffic among this pool, especially if the size of this pool is dynamically changing. Finally, it
may help with upstream connections when using a DNS name whose resolved addresses may change even if the
upstreams stay healthly. Forcing a maximum upstream lifetime in this scenario prevents holding onto healthy
connections even after they would otherwise be undiscoverable. To modify the max connection duration for downstream connections use the
connection will be drained and/or closed, starting from when it was first established. When max connection
duration is reached, the drain sequence will kick in (see :ref:`drain_timeout
<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`
below for details). After the drain timeout period elapses, if there are no active streams at that moment,
the connection will be closed immediately. If active streams still exist at that moment, the connection
remains open until all streams complete naturally, and then closes. The drain sequence does not forcefully
terminate active streams. The default value of max connection duration is *0* or unlimited, which means that
the connections will never be closed due to aging. It could be helpful in scenarios when you are running a
pool of Envoy edge-proxies and would want to close a downstream connection after some time to prevent
stickiness. It could also help to better load balance the overall traffic among this pool, especially if the
size of this pool is dynamically changing. Finally, it may help with upstream connections when using a DNS
name whose resolved addresses may change even if the upstreams stay healthy. Forcing a maximum upstream
lifetime in this scenario prevents holding onto healthy connections even after they would otherwise be
undiscoverable. To modify the max connection duration for downstream connections use the
:ref:`common_http_protocol_options <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options>`
field in the HTTP connection manager configuration. To modify the max connection duration for upstream connections use the
:ref:`common_http_protocol_options <envoy_v3_api_field_config.cluster.v3.Cluster.common_http_protocol_options>` field in the cluster configuration.

* The HTTP connection manager :ref:`drain_timeout
<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`
is the time that Envoy will wait between sending an initial HTTP/2 "shutdown notification" (``GOAWAY`` frame
with max stream ID) and a final GOAWAY frame. This grace period allows in-flight requests to be assigned
stream IDs and prevents a race with the final GOAWAY frame. During this grace period, Envoy will continue
to accept new streams. After the grace period elapses, a final GOAWAY frame is sent and Envoy will start
refusing new streams. At that moment, if no active streams exist, the connection closes immediately. If
active streams still exist, the connection remains open indefinitely until all streams complete naturally,
then closes. The drain sequence never forcefully terminates active streams. Draining occurs either when a
connection hits the :ref:`idle_timeout <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.idle_timeout>`,
when :ref:`max_connection_duration <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_connection_duration>`
is reached, or during general server draining. The default grace period is *5000 milliseconds (5 seconds)*
if this option is not specified.

See :ref:`below <faq_configuration_timeouts_transport_socket>` for other connection timeouts.

Stream timeouts
Expand Down