Skip to content
A Python framework to write Kubernetes operators in just few lines of code.
Branch: master
Clone or download
nolar Merge pull request #73 from zalando-incubator/apps-v1-deployment
Docs: use stable Workloads API (apps/v1)
Latest commit 4f98bd5 May 25, 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 stable Workloads API (apps/v1) May 25, 2019
examples Disable Kubernetes 1.10 — CRDs require spec.version, which fails on 1.14 May 22, 2019
kopf Merge pull request #70 from nolar/fix-diff-on-field-removal May 23, 2019
scripts Configure Minikube in Travis for e2e tests May 22, 2019
tests Merge pull request #70 from nolar/fix-diff-on-field-removal May 23, 2019
.gitignore Build the dummy documentation with ReadTheDocs Apr 4, 2019
.travis.yml Test Python 3.8 to be prepared for the release (~Oct'2019) May 22, 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 Adapt README.md to be used outside of GitHub, on PyPI Apr 23, 2019
SECURITY.md Adding boilerplate files Mar 26, 2019
peering.yaml Disable Kubernetes 1.10 — CRDs require spec.version, which fails on 1.14 May 22, 2019
requirements.txt Merge pull request #61 from nolar/tests-progress-structs May 22, 2019
setup.py Adapt README.md to be used outside of GitHub, on PyPI Apr 23, 2019

README.md

Kubernetes Operator Pythonic Framework (Kopf)

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.