From 08f11cd07f5da300d26759c479dc818725995be4 Mon Sep 17 00:00:00 2001
From: Keerthan Ekbote <keerthan.ekbote@solo.io>
Date: Thu, 27 May 2021 12:00:04 -0400
Subject: [PATCH] add scaled timeout docs faq (#16271)

Signed-off-by: Keerthan Ekbote <saiskee@gmail.com>
---
 docs/root/faq/configuration/timeouts.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/root/faq/configuration/timeouts.rst b/docs/root/faq/configuration/timeouts.rst
index 43a228e0c27a..72c090aac266 100644
--- a/docs/root/faq/configuration/timeouts.rst
+++ b/docs/root/faq/configuration/timeouts.rst
@@ -100,6 +100,20 @@ stream timeouts already introduced above.
   :ref:`max_stream_duration <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_stream_duration>`
   for individual routes as well as setting both limits and a fixed time offset on grpc-timeout headers.
 
+Scaled timeouts
+^^^^^^^^^^^^^^^
+
+In situations where envoy is under high load, Envoy can dynamically configure timeouts using scaled timeouts.
+Envoy supports scaled timeouts through the :ref:`Overload Manager <envoy_v3_api_msg_config.overload.v3.OverloadManager>`, configured
+in envoy :ref:`bootstrap configuration <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.overload_manager>`.
+Using a :ref:`reduce timeouts <config_overload_manager_reducing_timeouts>` overload action,
+the Overload Manager can be configured to monitor :ref:`resources <envoy_v3_api_msg_config.overload.v3.ResourceMonitor>`
+and scale timeouts accordingly. For example, a common use case may be to monitor the Envoy :ref:`heap size <envoy_v3_api_msg_extensions.resource_monitors.fixed_heap.v3.FixedHeapConfig>`
+and set the scaled TimerType to :ref:`HTTP_DOWNSTREAM_CONNECTION_IDLE <envoy_v3_api_enum_value_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType.HTTP_DOWNSTREAM_CONNECTION_IDLE>`.
+The overload manager will scale down the :ref:`idle timeout <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.idle_timeout>` once the :ref:`scaling_threshold <envoy_v3_api_field_config.overload.v3.ScaledTrigger.scaling_threshold>` has been met
+and will set the timeout to the :ref:`min timeout <envoy_v3_api_field_config.overload.v3.ScaleTimersOverloadActionConfig.ScaleTimer.min_timeout>` once the :ref:`scaling_threshold <envoy_v3_api_field_config.overload.v3.ScaledTrigger.scaling_threshold>` is met.
+The full list of supported timers that can be scaled is available in the overload manager :ref:`docs <envoy_v3_api_enum_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType>`.
+
 TCP
 ---