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
Permalink
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
CODE_OF_CONDUCT.md Adding boilerplate files Mar 26, 2019
CONTRIBUTING.md Expand the code contribution conventions & requirements in the docs May 21, 2019
CONTRIBUTORS.md Adding boilerplate files Mar 26, 2019
DEVELOPMENT.md Import the project as it is right now, with the squashed history Mar 27, 2019
LICENSE Adapt README.md to be used outside of GitHub, on PyPI Apr 23, 2019
MAINTAINERS Adding boilerplate files Mar 26, 2019
README.md Add the CI badges to the GitHub front page Jul 8, 2019
SECURITY.md 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
setup.py Add type-hints all over the code Oct 5, 2019

README.md

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).

Documentation

Features

  • 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.

Examples

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

The minimalistic operator can look like this:

import kopf

@kopf.on.create('zalando.org', '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.

Usage

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 handlers.py

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

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

Contributing

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

To install the environment for the local development, read DEVELOPMENT.md.

Versioning

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

License

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

Acknowledgments

You can’t perform that action at this time.