KubernetesWatcher

class controller.storage.kubernetes.watcher.KubernetesWatcher(*, method, object_type, kind, name=None, namespace=None, group=None, version=None, plural=None, involved_object=None, resource_version=None, timeout, logger)

Bases: Generic[T]

Watch Kubernetes for events.

This wrapper around the watch API of the Kubernetes client implements retries and resource version handling and fixes typing problems when used with the Safir MockKubernetesApi mock. The latter confuses the type detection in the kubernetes_asyncio library, which is handled here by passing in an explicit return type.

This class is not meant to be used directly by code outside of the Kubernetes storage layer. Use one of the kind-specific watcher classes built on top of it instead.

Parameters:

• method (Callable[..., Awaitable[Any]]) – API list method that supports the watch API.

• object_type (type[TypeVar(T)]) – Type of object being watched. This cannot be autodiscovered from the method because of the problems with docstring parsing and therefore must be provided by the caller and must match the type of object returned by the method. For custom objects, this should be a dict type.

• kind (str) – Kubernetes kind of object being watched, for error reporting.

• name (str | None, default: None) – Name of object to watch. Cannot be used with involved_object.

• namespace (str | None, default: None) – Namespace to watch.

• group (str | None, default: None) – Group of custom object.

• version (str | None, default: None) – Version of custom object.

• plural (str | None, default: None) – Plural of custom object.

• involved_object (str | None, default: None) – Involved object to watch (used when watching events). Cannot be used with name.

• resource_version (str | None, default: None) – Resource version at which to start the watch.

• timeout (Timeout | None) – Timeout for the watch. This may be None, in which case the watch continues until cancelled or until the iterator is no longer called.

• logger (BoundLogger) – Logger to use.

Raises:

ValueError – Raised if name and involved_object are both specified.

Methods Summary

close()	Close the internal API client used by the watch API.
stop()	Stop a watch in progress.
watch()	Watch Kubernetes for events.

Methods Documentation

async close()

Close the internal API client used by the watch API.

Return type:

None

stop()

Stop a watch in progress.

Return type:

None

async watch()

Watch Kubernetes for events.

If we started watching with a specific resource version, that resource version may be too old to still be known to Kubernetes, in which case the API call returns a 410 error and we should retry without a resource version. This is handled automatically. Unfortunately, this has a race condition where we may miss events that come in after the error is returned but before we retry the API call.

Yields:

dict – Event as returned by the Kubernetes API, without further parsing.

Raises:

• KubernetesError – Raised for exceptions from the Kubernetes API server during the watch.

• TimeoutError – Raised if the timeout was reached.

Return type:

AsyncIterator[WatchEvent[TypeVar(T)]]