From 2b40cdff5513242a8cf2e6a0daac9f649fc1136a Mon Sep 17 00:00:00 2001
From: Priyanka Saggu <priyankasaggu11929@gmail.com>
Date: Mon, 31 May 2021 12:11:49 +0530
Subject: [PATCH] add documentation for the server & client side timeout

---
 examples/pod_namespace_watch.py | 41 +++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/examples/pod_namespace_watch.py b/examples/pod_namespace_watch.py
index f09768cf7d..48256595fd 100644
--- a/examples/pod_namespace_watch.py
+++ b/examples/pod_namespace_watch.py
@@ -17,6 +17,47 @@
 The script will wait for 10 events related to namespaces to occur within
 the `timeout_seconds` threshold and then move on to wait for another 10 events
 related to pods to occur within the `timeout_seconds` threshold.
+
+---
+
+[INFO] Timeout settings
+
+There are two inputs available in the client, that could be used to set connection timeouts:
+1. timeout_seconds
+2. _request_timeout
+
+a) Sever-side timeout ("kwargs['timeout_seconds'] = n")
+
+    - The value of the argument `timeout_seconds`, n (which is time duration in seconds) is consumed at the server side, and is included in the request URL to the server. For eg. ~
+      "https://localhost:6443/api/v1/namespaces/default/pods?labelSelector=app%3Ddemo&timeoutSeconds=100&watch=True."
+
+    - If the `timeout_seconds` value is set, for ex: "kwargs['timeout_seconds'] = 3600", then the server timeout will be equal to 1 hour, as determined by the following expression ~
+      "timeout = time.Duration(3600) * time.seconds" -> "timeout = 1 hour"
+
+      Refer: https://github.com/kubernetes/apiserver/blob/92392ef22153d75b3645b0ae339f89c12767fb52/pkg/endpoints/handlers/get.go#L255
+
+    - If the `timeout_seconds` value is not set, then the connection timeout will be a randomized value (in seconds) between 0 and `minRequestTimeout`, to spread out load. It is determined by the following expression ~
+      "timeout = time.Duration(float64(minRequestTimeout) * (rand.Float64() + 1.0))",
+
+      Where `minRequestTimeout` indicates the minimum number of seconds a handler must keep a request open before timing it out. The default value of `minRequestTimeout` is 1800 seconds.
+
+      Refer: https://github.com/kubernetes/apiserver/blob/92392ef22153d75b3645b0ae339f89c12767fb52/pkg/endpoints/handlers/get.go#L258
+             https://github.com/kubernetes/kubernetes/blob/release-1.1/docs/admin/kube-apiserver.md
+
+    - In case of a network outage, the timeout value will have no effect & the client will hang indefinitely without raising any exception. It is recommended to set this timeout value to a higher number such as 3600 seconds (1 hour).
+
+b) Client-side timeout ("kwargs['_request_timeout'] = n")
+
+    - The value of the argument `_request_timeout`, n (which is time duration in seconds) is set to the socket used for the connection.
+
+    - The argument `_request_timeout` can accept 2 types of input values, i.e. either in integer (int) type, or a tuple with a length of 2. In case of the tuple input type, the first value will be ignored. 
+
+    - In case of network outage, leading to dropping all packets with no RST/FIN, the timeout value (in seconds) determined by the `request_timeout` argument, would be the time duration for how long the client will wait before realizing & dropping the connection.
+
+    - When the timeout happens, an exception will be raised, for ex ~
+      "urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='localhost', port=6443): Read timed out."
+
+    - It is recommended to set this timeout value to a low number (for ex ~ maybe 60 seconds)
 """
 
 from kubernetes import client, config, watch