Watch API

The Kubernetes Watch API allows you to monitor changes to resources in real-time. This client library provides a Watch class for interacting with the Watch API.

The Watch class provides two main methods:

• stream(func, *args, **kwargs): This method takes an API function pointer and returns a generator that yields events as they occur.
• stop(): This method stops the watch loop.

Timeout Settings

There are two ways to set timeouts for watch requests:

• timeout_seconds: This parameter is passed to the Kubernetes API server, and it limits the duration of the watch request, regardless of activity.

“Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.”
Source: kubernetes/scripts/swagger.json

• _request_timeout: This parameter is passed to the underlying HTTP client, and it limits the duration of the entire request, including the initial connection and the response time.

Client-side Timeout:

“In case, if the _request_timeout value is not set, then the default value is None & socket will have no timeout.”
Source: examples/watch/timeout-settings.md

“It is recommended to set this timeout value to a lower number (for eg. ~ maybe 60 seconds).” Source: examples/watch/timeout-settings.md

Server-side Timeout:

“In case of a network outage, the server side timeout value will have no effect & the client will hang indefinitely without raising any exception. Note, that this is the case provided when there is no other client-side timeout (i.e., _request_timeout) value specified.” Source: examples/watch/timeout-settings.md

“It is recommended to set this timeout value to a higher number such as 3600 seconds (1 hour).” Source: examples/watch/timeout-settings.md

Example

from kubernetes import client, watch
          
          v1 = client.CoreV1Api()
          watch = watch.Watch()
          for event in watch.stream(v1.list_namespace, resource_version="1127"):
              type = event['type']
              object = event['object']  # object is one of type return_type
              raw_object = event['raw_object']  # raw_object is a dict
              ...
              if should_stop:
                  watch.stop()
          

### Additional Notes
          
          - The `resourceVersion` parameter can be used to specify a starting point for the watch. 
          - The `stream` method automatically retries if the watch expires (HTTP status code 410). 
          - If the watch expires and the `resourceVersion` is not set, you will need to manually re-list the resources and start a new watch. 
          - The `Watch` class uses a `threading.Thread` to handle the watch loop. 
          
          > "Note that watching an API resource can expire. The method tries to resume automatically once from the last result, but if that last result is too old as well, an `ApiException` exception will be thrown with ``code`` 410."
          [Source: kubernetes/base/watch/watch.py](https://github.com/kubernetes-client/python/blob/master/kubernetes/base/watch/watch.py)
          
          > "In that case you have to recover yourself, probably by listing the API resource to obtain the latest state and then watching from that state on by setting ``resource_version`` to one returned from listing."
          [Source: kubernetes/base/watch/watch.py](https://github.com/kubernetes-client/python/blob/master/kubernetes/base/watch/watch.py)
          

Top-Level Directory Explanations

doc/ - This directory contains documentation files for the project.

doc/source/ - This directory contains the source files for the documentation.

examples/ - This directory contains example usage of the Kubernetes client library.

examples/dynamic-client/ - This directory contains examples of using the dynamic client to interact with Kubernetes.

examples/watch/ - This directory contains examples of using the watch function to monitor Kubernetes resources.

kubernetes/ - This directory contains the main Kubernetes client library.

kubernetes/base/ - This directory contains the base Kubernetes client library.

kubernetes/base/config/ - This directory contains configuration files for the base library.

kubernetes/base/dynamic/ - This directory contains the dynamic client implementation for the base library.

kubernetes/base/stream/ - This directory contains the stream implementation for the base library.

kubernetes/base/watch/ - This directory contains the watch implementation for the base library.

kubernetes/client/ - This directory contains the top-level client for the Kubernetes client library.

kubernetes/client/api/ - This directory contains the API definitions for the client library.

kubernetes/client/models/ - This directory contains the data models used by the client library.

kubernetes/e2e_test/ - This directory contains end-to-end tests for the Kubernetes client library.

kubernetes/test/ - This directory contains unit tests for the Kubernetes client library.

kubernetes/utils/ - This directory contains utility functions for the Kubernetes client library.

scripts/ - This directory contains scripts used in the development and build process.

scripts/util/ - This directory contains utility scripts.