mirror of
https://github.com/Danny-de-bree/fullstaq-operator.git
synced 2026-05-20 15:22:50 +00:00
224 lines
9.3 KiB
Plaintext
224 lines
9.3 KiB
Plaintext
Metadata-Version: 2.1
|
|
Name: kopf
|
|
Version: 1.36.2
|
|
Summary: Kubernetes Operator Pythonic Framework (Kopf)
|
|
Home-page: https://github.com/nolar/kopf
|
|
Author: Sergey Vasilyev
|
|
Author-email: nolar@nolar.info
|
|
Maintainer: Sergey Vasilyev
|
|
Maintainer-email: nolar@nolar.info
|
|
License: MIT
|
|
Project-URL: Documentation, https://kopf.readthedocs.io
|
|
Project-URL: Bug Tracker, https://github.com/nolar/kopf/issues
|
|
Project-URL: Source Code, https://github.com/nolar/kopf
|
|
Keywords: kubernetes,operator,framework,python,k8s
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Operating System :: OS Independent
|
|
Classifier: Programming Language :: Python
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.7
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: 3.9
|
|
Classifier: Programming Language :: Python :: 3.10
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
Classifier: Topic :: Software Development :: Libraries
|
|
Requires-Python: >=3.7
|
|
Description-Content-Type: text/markdown
|
|
License-File: LICENSE
|
|
Requires-Dist: typing-extensions
|
|
Requires-Dist: python-json-logger
|
|
Requires-Dist: iso8601
|
|
Requires-Dist: click
|
|
Requires-Dist: aiohttp (<4.0.0)
|
|
Requires-Dist: pyyaml
|
|
Provides-Extra: dev
|
|
Requires-Dist: pyngrok ; extra == 'dev'
|
|
Requires-Dist: oscrypto ; extra == 'dev'
|
|
Requires-Dist: certbuilder ; extra == 'dev'
|
|
Requires-Dist: certvalidator ; extra == 'dev'
|
|
Provides-Extra: full-auth
|
|
Requires-Dist: pykube-ng ; extra == 'full-auth'
|
|
Requires-Dist: kubernetes ; extra == 'full-auth'
|
|
Provides-Extra: uvloop
|
|
Requires-Dist: uvloop ; extra == 'uvloop'
|
|
|
|
# Kubernetes Operator Pythonic Framework (Kopf)
|
|
|
|
[](https://pypi.org/project/kopf/)
|
|
[](https://github.com/nolar/kopf/actions/workflows/thorough.yaml)
|
|
[](https://codecov.io/gh/nolar/kopf)
|
|
[](https://coveralls.io/github/nolar/kopf?branch=main)
|
|
[](https://lgtm.com/projects/g/nolar/kopf/alerts/)
|
|
[](https://lgtm.com/projects/g/nolar/kopf/context:python)
|
|
[](https://github.com/pre-commit/pre-commit)
|
|
|
|
**Kopf** —Kubernetes Operator Pythonic Framework— is a framework and a library
|
|
to make Kubernetes operators development easier, just in a 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).
|
|
|
|
The project was originally started as `zalando-incubator/kopf` in March 2019,
|
|
and then forked as `nolar/kopf` in August 2020: but it is the same codebase,
|
|
the same packages, the same developer(s).
|
|
|
|
|
|
## Documentation
|
|
|
|
* https://kopf.readthedocs.io/
|
|
|
|
|
|
## Features
|
|
|
|
* Simple, but powerful:
|
|
* A full-featured operator in just 2 files: a `Dockerfile` + a Python file (*).
|
|
* Handling functions registered via decorators with a declarative approach.
|
|
* No infrastructure boilerplate code with K8s API communication.
|
|
* Both sync and async handlers, with sync ones being threaded under the hood.
|
|
* Detailed documentation with examples.
|
|
* Intuitive mapping of Python concepts to Kubernetes concepts and back:
|
|
* Marshalling of resources' data to the handlers' kwargs.
|
|
* Marshalling of handlers' results to the resources' statuses.
|
|
* Publishing of logging messages as Kubernetes events linked to the resources.
|
|
* Support anything that exists in K8s:
|
|
* Custom K8s resources.
|
|
* Builtin K8s resources (pods, namespaces, etc).
|
|
* Multiple resource types in one operator.
|
|
* Both cluster and namespaced operators.
|
|
* All the ways of handling that a developer can wish for:
|
|
* Low-level handlers for events received from K8s APIs "as is" (an equivalent of _informers_).
|
|
* High-level handlers for detected causes of changes (creation, updates with diffs, deletion).
|
|
* Handling of selected fields only instead of the whole objects (if needed).
|
|
* Dynamically generated or conditional sub-handlers (an advanced feature).
|
|
* Timers that tick as long as the resource exists, optionally with a delay since the last change.
|
|
* Daemons that run as long as the resource exists (in threads or asyncio-tasks).
|
|
* Validating and mutating admission webhook (with dev-mode tunneling).
|
|
* Live in-memory indexing of resources or their excerpts.
|
|
* Filtering with stealth mode (no logging): by arbitrary filtering functions,
|
|
by labels/annotations with values, presence/absence, or dynamic callbacks.
|
|
* In-memory all-purpose containers to store non-serializable objects for individual resources.
|
|
* Eventual consistency of handling:
|
|
* Retrying the handlers in case of arbitrary errors until they succeed.
|
|
* Special exceptions to request a special retry or to never retry again.
|
|
* Custom limits for the number of attempts or the time.
|
|
* Implicit persistence of the progress that survives the operator restarts.
|
|
* Tolerance to restarts and lengthy downtimes: handles the changes afterwards.
|
|
* Awareness of other Kopf-based operators:
|
|
* Configurable identities for different Kopf-based operators for the same resource kinds.
|
|
* Avoiding double-processing due to cross-pod awareness of the same operator ("peering").
|
|
* Pausing of a deployed operator when a dev-mode operator runs outside of the cluster.
|
|
* Extra toolkits and integrations:
|
|
* Some limited support for object hierarchies with name/labels propagation.
|
|
* Friendly to any K8s client libraries (and is client agnostic).
|
|
* Startup/cleanup operator-level handlers.
|
|
* Liveness probing endpoints and rudimentary metrics exports.
|
|
* Basic testing toolkit for in-memory per-test operator running.
|
|
* Embeddable into other Python applications.
|
|
* Highly configurable (to some reasonable extent).
|
|
|
|
(*) _Small font: two files of the operator itself, plus some amount of
|
|
deployment files like RBAC roles, bindings, service accounts, network policies
|
|
— everything needed to deploy an application in your specific infrastructure._
|
|
|
|
|
|
## Examples
|
|
|
|
See [examples](https://github.com/nolar/kopf/tree/main/examples)
|
|
for the examples of the typical use-cases.
|
|
|
|
A minimalistic operator can look like this:
|
|
|
|
```python
|
|
import kopf
|
|
|
|
@kopf.on.create('kopfexamples')
|
|
def create_fn(spec, name, meta, status, **kwargs):
|
|
print(f"And here we are! Created {name} with spec: {spec}")
|
|
```
|
|
|
|
Numerous kwargs are available, such as `body`, `meta`, `spec`, `status`,
|
|
`name`, `namespace`, `retry`, `diff`, `old`, `new`, `logger`, etc:
|
|
see [Arguments](https://kopf.readthedocs.io/en/latest/kwargs/)
|
|
|
|
To run a never-exiting function for every resource as long as it exists:
|
|
|
|
```python
|
|
import time
|
|
import kopf
|
|
|
|
@kopf.daemon('kopfexamples')
|
|
def my_daemon(spec, stopped, **kwargs):
|
|
while not stopped:
|
|
print(f"Object's spec: {spec}")
|
|
time.sleep(1)
|
|
```
|
|
|
|
Or the same with the timers:
|
|
|
|
```python
|
|
import kopf
|
|
|
|
@kopf.timer('kopfexamples', interval=1)
|
|
def my_timer(spec, **kwargs):
|
|
print(f"Object's spec: {spec}")
|
|
```
|
|
|
|
That easy! For more features, see the [documentation](https://kopf.readthedocs.io/).
|
|
|
|
|
|
## Usage
|
|
|
|
Python 3.7+ is required:
|
|
[CPython](https://www.python.org/) and [PyPy](https://www.pypy.org/)
|
|
are officially supported and tested; other Python implementations can work too.
|
|
|
|
We assume that when the operator is executed in the cluster, it must be packaged
|
|
into a docker image with a CI/CD tool of your preference.
|
|
|
|
```dockerfile
|
|
FROM python:3.11
|
|
ADD . /src
|
|
RUN pip install kopf
|
|
CMD kopf run /src/handlers.py --verbose
|
|
```
|
|
|
|
Where `handlers.py` is your Python script with the handlers
|
|
(see `examples/*/example.py` for the examples).
|
|
|
|
See `kopf run --help` for other ways of attaching the handlers.
|
|
|
|
|
|
## Contributing
|
|
|
|
Please read [CONTRIBUTING.md](https://github.com/nolar/kopf/blob/main/CONTRIBUTING.md)
|
|
for details on our process for submitting pull requests to us, and please ensure
|
|
you follow the [CODE_OF_CONDUCT.md](https://github.com/nolar/kopf/blob/main/CODE_OF_CONDUCT.md).
|
|
|
|
To install the environment for the local development,
|
|
read [DEVELOPMENT.md](https://github.com/nolar/kopf/blob/main/DEVELOPMENT.md).
|
|
|
|
|
|
## Versioning
|
|
|
|
We use [SemVer](http://semver.org/) for versioning. For the versions available,
|
|
see the [releases on this repository](https://github.com/nolar/kopf/releases).
|
|
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License —
|
|
see the [LICENSE](https://github.com/nolar/kopf/blob/main/LICENSE) file for details.
|
|
|
|
|
|
## Acknowledgments
|
|
|
|
* Thanks to Zalando for starting this project in Zalando's Open-Source Incubator
|
|
in the first place.
|
|
* Thanks to [@side8](https://github.com/side8) and their [k8s-operator](https://github.com/side8/k8s-operator)
|
|
for inspiration.
|