The framework is organized into several layers, and the layers are layered too. The higher-level layers and modules can import the lower-level ones, but not vice versa. The layering is checked and enforced by import-linter.
At the topmost level, the framework consists of cogs, core, and kits, and user-facing modules.
kopf.testing are the public interface that can be
imported by operator developers. Only these public modules contain all public
promises on names and signatures. Everything else is an implementation detail.
The internal modules are intentionally hidden (by underscore-naming) to protect against introducing the dependencies on the implementation details that can change without warnings.
cogs are utilities used throughout the framework in nearly all modules.
They do not represent the main functionality of operators but are needed
to make them work. Generally, the cogs are fully independent of each other
and of anything in the framework — to the point that they can be extracted
as separate libraries (in theory; if anyone needs it).
core is the main functionality used by a Kopf-based operator.
It brings the operators into motion. The core is the essence of the framework,
it cannot be extracted or replaced without redefining the framework.
kits are utilities and specialised tools provided to operator developers
for some scenarios and/or settings. The framework itself does not use them.
helpers are system-level or language-enhancing adapters. E.g., hostname
identification, dynamic Python module importing, integrations with 3rd-party
libraries (such as pykube-ng or the official Kubernetes Python client).
aiokits are asynchronous primitives and enhancements for
sufficiently abstracted from the framework and the Kubernetes/operator domains.
structs are data structures and type declarations for Kubernetes models:
such as resource kinds, selectors, bodies or their parts (specs, statuses, etc),
admission reviews, so on. Besides, this includes some specialised structures,
such as authentication credentials – also abstracted for the framework even
in case the clients and their authentication are replaced.
configs are the settings mostly, and everything needed to define them:
e.g. persistence storage classes (for handling progress and diff bases).
clients are the asynchronous adapters and wrappers for the Kubernetes API.
They abstract away how the framework communicates with the API to achieve
its goals (such as patching a resource or watching for its changes).
Currently, it is based on aiohttp; previously, it was the official Kubernetes
client library and pykube-ng. Over time, the whole clients’ implementation
can be replaced with another one — while keeping the signatures for the rest
of the framework. Only the clients are allowed to talk to the Kubernetes API.
actions is the lowest level in the core (but not in the framework).
It defines how the functions and handlers are invoked, which ones specifically,
how their errors are handled and retried (if at all), how the function results
and the patches are applied to the cluster, so on.
intents are mostly data structures that store the declared handlers
of the operators, but also some logic to select/filter them when a reaction
engines are specialised aspects of the framework, i.e. its functionality.
Engines are usually independent of each other (though, this is not a rule).
For example, daemons and timers, validating/mutating admission requests,
in-memory indexing, operator activities (authentication, probing, etc),
kind: Event delayed posting, etc.
reactor is the topmost layer in the framework. It defines the entry points
for the CLI and operator embedding (see Embedding) and implements
the task orchestration for all the engines and internal machinery.
Besides, the reactor observes the cluster for resources and namespaces,
and dynamically spawns/stops the tasks to serve them.
hierarchies are helper functions to manage the hierarchies of Kubernetes
objects, such as labelling them, adding/removing the owner references,
name generation, so on. They support raw Python dicts so as some selected
libraries: pykube-ng and the official Kubernetes client for Python
webhooks are helper servers and tunnels to accept admission requests
from a Kubernetes cluster even if running locally on a developer’s machines
(see Admission control).
runner is a helper to run an operator in a Python context manager,
mostly useful for testing (see Operator testing).