Skip to content
A Python framework to write Kubernetes operators in just few lines of code.
Python Shell
Branch: master
Clone or download
nolar Merge pull request #203 from nolar/implicit-owners
Assume the current object as an implicit owner for hierarchies
Latest commit 267e23b Oct 8, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Cleanup the boilerplate files Mar 26, 2019
docs Use the currently handled object as the default adoption target Oct 7, 2019
examples Use the currently handled object as the default adoption target Oct 7, 2019
kopf Fix the type annotation for the contextvars' context manager Oct 7, 2019
tests Test implicit owner guessing from the current handler's context Oct 7, 2019
tools Test with the latest Kubernetes (auto-upgrades over time) Sep 26, 2019
.codecov.yml Disable CodeCov's PR spamming Aug 6, 2019
.gitignore Configure mypy strict checks on CI Oct 5, 2019
.travis.yml Configure mypy strict checks on CI Oct 5, 2019
.zappr.yml Update .zappr.yml Mar 26, 2019 Adding boilerplate files Mar 26, 2019 Expand the code contribution conventions & requirements in the docs May 21, 2019 Adding boilerplate files Mar 26, 2019 Import the project as it is right now, with the squashed history Mar 27, 2019
LICENSE Adapt to be used outside of GitHub, on PyPI Apr 23, 2019
MAINTAINERS Adding boilerplate files Mar 26, 2019 Add the CI badges to the GitHub front page Jul 8, 2019 Adding boilerplate files Mar 26, 2019
mypy.ini Configure mypy strict checks on CI Oct 5, 2019
peering.yaml Disable Kubernetes 1.10 — CRDs require spec.version, which fails on 1.14 May 22, 2019
requirements.txt Merge branch 'master' into typehints-everywhere Oct 5, 2019 Add type-hints all over the code Oct 5, 2019

Kubernetes Operator Pythonic Framework (Kopf)

Build Status codecov Coverage Status

Kopf —Kubernetes Operator Pythonic Framework— is a framework and a library to make Kubernetes operators development easier, just in few lines of Python code.

The main goal is to bring the Domain-Driven Design to the infrastructure level, with Kubernetes being an orchestrator/database of the domain objects (custom resources), and the operators containing the domain logic (with no or minimal infrastructure logic).



  • A full-featured operator in just 2 files: Dockerfile + a Python module.
  • Implicit object's status updates, as returned from the Python functions.
  • Multiple creation/update/deletion handlers to track the object handling process.
  • Update handlers for the selected fields with automatic value diffs.
  • Dynamically generated sub-handlers using the same handling tracking feature.
  • Retries of the handlers in case of failures or exceptions.
  • Easy object hierarchy building with the labels/naming propagation.
  • Built-in events for the objects to reflect their state (as seen in kubectl describe).
  • Automatic logging/reporting of the handling process (as logs + events).
  • Handling of multiple CRDs in one process.
  • The development instance temporarily suppresses the deployed ones.


See examples for the examples of the typical use-cases.

The minimalistic operator can look like this:

import kopf

@kopf.on.create('', 'v1', 'kopfexamples')
def create_fn(spec, meta, status, **kwargs):
    print(f"And here we are! Creating: {spec}")

The keyword arguments available to the handlers:

  • body for the whole body of the handled objects.
  • spec as an alias for body['spec'].
  • meta as an alias for body['metadata'].
  • status as an alias for body['status'].
  • patch is a dict with the object changes to applied after the handler.
  • retry (int) is the sequential number of retry of this handler.
  • started (datetime.datetime) is the start time of the handler, in case of retries & errors.
  • runtime (datetime.timedelay) is the duration of the handler run, in case of retries & errors.
  • diff is a list of changes of the object (only for the update events).
  • old is the old state of the object or a field (only for the update events).
  • new is the new state of the object or a field (only for the update events).
  • logger is a per-object logger, with the messages prefixed with the object's namespace/name.
  • event is the raw event as received from the Kubernetes API.
  • cause is the processed cause of the handler as detected by the framework (create/update/delete).

**kwargs (or **_ to stop lint warnings) is required for the forward compatibility: the framework can add new keyword arguments in the future, and the existing handlers should accept them.


We assume that when the operator is executed in the cluster, it must be packaged into a docker image with CI/CD tool of your preference.

FROM python:3.7
ADD . /src
RUN pip install kopf
CMD kopf run

Where is your Python script with the handlers (see examples/*/ for the examples).

See kopf run --help for others ways of attaching the handlers.


Please read for details on our process for submitting pull requests to us, and please ensure you follow the

To install the environment for the local development, read


We use SemVer for versioning. For the versions available, see the releases on this repository.


This project is licensed under the MIT License — see the LICENSE file for details.


You can’t perform that action at this time.