I speak here {^_^}

Notes: documenting server side & client side connection timeout settings, for the watch request handler #20

May 31, 2021

Quick notes from today:

documenting server side & client side connection timeout settings, for the watch request handler!

  • Re-started working on this long pending PR ~ add documentation for the server & client side timeout #1467, on the kubernetes-client/python project. The documentation provides information for the server-side & client-side connection timeout settings for the client’s watch request handler method. There were review comments on the PR, pointing to a few links explaining the process in more details, & ultimately requesting changes on my previous attempt.
  • I read through all of the links in the review comments on the PR & quite nicely managed to understand the concept. Putting all what I learnt & understood below (& the same is exactly what I have put in the documentation for the PR)
  • And rather than adding the entire documentation as inline docstrings in the python script, I just added a small section with a link to the markdown documentation file in there.
    • The reason for not including the entire doc-string was because the python linter (pycodestyle) used in the project pre-submit PR tests threw errors for the length of the documentation I added in the doc-strings section.

There are two inputs available in the client, that could be used to set connection timeouts:

  1. timeout_seconds
  2. _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:

  • In case, 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 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:

  • 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 ~
    • integer (int),
    • a tuple (with a length of 2)

    If it is 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 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:

That’s all for the day!

PS: Find here, the links to all the kubernetes-contributions for the month of May, 2021.

Other posts