-
Notifications
You must be signed in to change notification settings - Fork 3.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add documentation for the server & client side timeout
Signed-off-by: Priyanka Saggu <priyankasaggu11929@gmail.com>
- Loading branch information
1 parent
44b2325
commit fc95388
Showing
2 changed files
with
77 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
|
||
**This documentation briefly provides information about the `server side` & `client side` connection timeout settings, in the watch request handler.** | ||
|
||
--- | ||
|
||
There are two inputs available in the client, that could be used to set connection timeouts: | ||
|
||
- `timeout_seconds` | ||
- `_request_timeout` | ||
|
||
--- | ||
|
||
#### 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. It 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` | ||
|
||
- In case, if the `timeout_seconds` value is set, the value `n` would determine the server-side connection timeout duration. | ||
|
||
*For eg.* ~ if `kwargs['timeout_seconds'] = 3600`, then the server-side connection timeout will be equal to 1 hour. | ||
|
||
This timeout duration is determined by the expression ~ `timeout = time.Duration(3600) * time.seconds`, *i.e.* `timeout = 1 hour` | ||
|
||
***Refer:*** | ||
- *[https://github.com/kubernetes/apiserver/blob/release-1.20/pkg/endpoints/handlers/get.go#L254](https://github.com/kubernetes/apiserver/blob/release-1.20/pkg/endpoints/handlers/get.go#L254)* | ||
|
||
- In case, if the `timeout_seconds` value is not set, then the connection timeout will be a randomized value (in seconds) between `minRequestTimeout` and 2*`minRequestTimeout`, to spread out the load. | ||
|
||
It is determined using the 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/release-1.20/pkg/endpoints/handlers/get.go#L257](https://github.com/kubernetes/apiserver/blob/release-1.20/pkg/endpoints/handlers/get.go#L257)* | ||
- *[https://github.com/kubernetes/kubernetes/blob/release-1.20/staging/src/k8s.io/apiserver/pkg/server/config.go#L320](https://github.com/kubernetes/kubernetes/blob/release-1.20/staging/src/k8s.io/apiserver/pkg/server/config.go#L320)* | ||
|
||
- In case of a network outage, this 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). | ||
|
||
--- | ||
|
||
#### 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. | ||
|
||
- In case, if the `_request_timeout` value is set, this argument can accept 2 types of input values ~ | ||
- float, | ||
- a tuple (with a length of 2) | ||
|
||
***Refer*** | ||
- *[https://github.com/kubernetes-client/python/blob/v17.17.0/kubernetes/client/api_client.py#L336-L339](https://github.com/kubernetes-client/python/blob/v17.17.0/kubernetes/client/api_client.py#L336-L339)* | ||
|
||
If it is tuple input type i.e. a pair of values like (connection, read), then 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 eg. ~ | ||
|
||
`urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='localhost', port=6443): Read timed out.` | ||
|
||
- In case, if the `_request_timeout` value is not set, then the default value is **`None`** & socket will have no timeout. | ||
|
||
***Refer:*** | ||
- *[https://docs.python.org/3/library/socket.html#socket.getdefaulttimeout](https://docs.python.org/3/library/socket.html#socket.getdefaulttimeout)* | ||
|
||
- It is recommended to set this timeout value to a lower number (for eg. ~ maybe 60 seconds). | ||
|