kubernetes-client / python

Streaming Watch Events Using the watch Module

The watch module in the kubernetes-client/python library provides a mechanism for streaming watch events from the Kubernetes API server. This allows you to monitor changes in Kubernetes resources in real-time, without needing to constantly poll the server.

The watch module exposes a Watch class that provides the stream method. This method takes a function pointer that represents the API endpoint you want to watch, along with any necessary parameters, and returns a generator that yields event objects.

Here is an example of how to use the watch module to watch for changes to namespaces:

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
              # ... do something with the event ...
              if should_stop:
                  watch.stop()

This example defines a Watch object and uses it to stream events from the list_namespace API endpoint, starting from resource version 1127. The for loop iterates over the event objects yielded by the stream method. Each event object contains the following keys:

  • type: The type of event, such as “ADDED”, “DELETED”, etc.
  • raw_object: A dictionary representing the watched object.
  • object: A model representation of raw_object. The name of the model will be determined based on the function’s docstring. If it cannot be determined, object value will be the same as raw_object.

The watch module automatically handles retries in case the watch connection is interrupted. If the last watch event is too old, it will raise an ApiException with code 410, indicating that the connection expired. In this case, you need to obtain the latest state of the resource by listing it and then resume the watch from that state.

Here are some important points to consider when using the watch module:

  • The resource_version parameter is used to specify the starting point for the watch. You can use the resource version of the last event to resume the watch.
  • The watch parameter should be set to True when calling the API endpoint function.
  • The stream method returns a generator that yields event objects.
  • The stop method can be used to stop the watch.
  • It is possible to customize the return type of the object field by passing a custom return type to the Watch constructor.

For more information about the watch module, refer to the following resources:


          
          ## Top-Level Directory Explanations
          
          <a class='local-link directory-link' data-ref="doc/" href="#doc/">doc/</a> - This directory contains documentation files for the project.
          
          <a class='local-link directory-link' data-ref="doc/source/" href="#doc/source/">doc/source/</a> - This directory contains the source files for the documentation.
          
          <a class='local-link directory-link' data-ref="examples/" href="#examples/">examples/</a> - This directory contains example usage of the Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="examples/dynamic-client/" href="#examples/dynamic-client/">examples/dynamic-client/</a> - This directory contains examples of using the dynamic client to interact with Kubernetes.
          
          <a class='local-link directory-link' data-ref="examples/watch/" href="#examples/watch/">examples/watch/</a> - This directory contains examples of using the watch function to monitor Kubernetes resources.
          
          <a class='local-link directory-link' data-ref="kubernetes/" href="#kubernetes/">kubernetes/</a> - This directory contains the main Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/" href="#kubernetes/base/">kubernetes/base/</a> - This directory contains the base Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/config/" href="#kubernetes/base/config/">kubernetes/base/config/</a> - This directory contains configuration files for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/dynamic/" href="#kubernetes/base/dynamic/">kubernetes/base/dynamic/</a> - This directory contains the dynamic client implementation for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/hack/" href="#kubernetes/base/hack/">kubernetes/base/hack/</a> - This directory contains hack files for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/leaderelection/" href="#kubernetes/base/leaderelection/">kubernetes/base/leaderelection/</a> - This directory contains the leader election implementation for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/stream/" href="#kubernetes/base/stream/">kubernetes/base/stream/</a> - This directory contains the stream implementation for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/base/watch/" href="#kubernetes/base/watch/">kubernetes/base/watch/</a> - This directory contains the watch implementation for the base library.
          
          <a class='local-link directory-link' data-ref="kubernetes/client/" href="#kubernetes/client/">kubernetes/client/</a> - This directory contains the top-level client for the Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/client/api/" href="#kubernetes/client/api/">kubernetes/client/api/</a> - This directory contains the API definitions for the client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/client/models/" href="#kubernetes/client/models/">kubernetes/client/models/</a> - This directory contains the data models used by the client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/e2e_test/" href="#kubernetes/e2e_test/">kubernetes/e2e_test/</a> - This directory contains end-to-end tests for the Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="kubernetes/utils/" href="#kubernetes/utils/">kubernetes/utils/</a> - This directory contains utility functions for the Kubernetes client library.
          
          <a class='local-link directory-link' data-ref="scripts/" href="#scripts/">scripts/</a> - This directory contains scripts used in the development and build process.