NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #3387 most downloaded on PyPI
Kubernetes Operator Pythonic Framework (Kopf)
Last release 4 months ago
03 Jun 2026
Ships unpredictably
gaps range from 8 days to 7 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
5 versions withdrawn
withdrawn after publishing
8 years old
127 releases · first in 2019
Upgrade CI tools and actions (mypy, pre-commit, docker, etc) by @nolar in #1300
Full Changelog: 1.44.5...1.44.6
One column per quarter.
Fix the transformation functions in timers/daemons patching by @nolar in #1296
Full Changelog: 1.44.4...1.44.5
fix: avoid TypeError when kubernetes_asyncio is unavailable by @saschabuehrle in #1289
Full Changelog: 1.44.3...1.44.4
YANKED: broken types for Python 3.10-3.13 without kubernetes_asyncio (3.14 works). Use 1.44.4.
YANKED: broken types for Python 3.10-3.13 without kubernetes_asyncio (3.14 works). Use 1.44.4.
kubernetes_asyncio as the first-class 3rd-party library by @nolar in #1283Full Changelog: 1.44.2...1.44.3
Ignore the proxy configuration from the env vars leaked through the official client by @nolar in #1278
trust_env setting for proxies from environment variables by @nolar in #1279Full Changelog: 1.44.1...1.44.2
Prevent daemons/timers from spawning precisely when the operator is paused by @nolar in #1272
Full Changelog: 1.44.0...1.44.1
TL;DR: Improvements in overall stability and consistency, in cooperation with other operators, and in reducing the load on clusters.
TL;DR: Improvements in overall stability and consistency, in cooperation with other operators, and in reducing the load on clusters.
clusterwide() with namespace(None)). by @nolar in #1257Full Changelog: 1.43.0...1.44.0
Package Kopf as a Docker image on GHCR by @nolar in #1239 , #1245 , #1246
Full Changelog: 1.42.5...1.43.0
Select resources to handle via a callable selector by @nolar in #1235
Full Changelog: 1.42.4...1.42.5
Require a minimal version of aiohttp for proper SSL support by @nolar in #1233
Full Changelog: 1.42.3...1.42.4
Accept custom aiohttp sessions from login handlers by @nolar in https://github.com/nolar/kopf/pull/1230
Full Changelog: https://github.com/nolar/kopf/compare/1.42.2...1.42.3
Retry on "too many requests" for all requests, obey the server's "retry-after" by @nolar in https://github.com/nolar/kopf/pull/1229
Full Changelog: https://github.com/nolar/kopf/compare/1.42.1...1.42.2
Consider a namespace deleted not earlier than all blockers/finalizers are removed by @nolar in https://github.com/nolar/kopf/pull/1225
Full Changelog: https://github.com/nolar/kopf/compare/1.42.0...1.42.1
BEWARE: the very core logic of Kopf<>Kubernetes communication has changed — test carefully; though the full backwards compatibility and seamless trans
BEWARE: the very core logic of Kopf<>Kubernetes communication has changed — test carefully; though the full backwards compatibility and seamless transition is expected.
@on.event handlers under high load or slow network.Full Changelog: https://github.com/nolar/kopf/compare/1.41.1...1.42.0
Fix the types and token retrieval for kubernetes-asyncio by @nolar in https://github.com/nolar/kopf/pull/1219
Full Changelog: https://github.com/nolar/kopf/compare/1.41.0...1.41.1
Postpone the initial timer/daemon delay by computable (e.g. random) time by @nolar in https://github.com/nolar/kopf/pull/1214
Full Changelog: https://github.com/nolar/kopf/compare/1.40.1...1.41.0
Avoid streaming if stopped at the request handshake by @nolar in https://github.com/nolar/kopf/pull/1209
Full Changelog: https://github.com/nolar/kopf/compare/1.40.0...1.40.1
TL;DR: Mainly refactorings, but some might affect the time-related behaviour (though should not).
TL;DR: Mainly refactorings, but some might affect the time-related behaviour (though should not).
Full Changelog: https://github.com/nolar/kopf/compare/1.39.1...1.40.0
Enable Python 3.14 and use it by default in CI by @nolar in https://github.com/nolar/kopf/pull/1188
Full Changelog: https://github.com/nolar/kopf/compare/1.39.0...1.39.1
Upgrade CI environments & dependencies by @nolar in https://github.com/nolar/kopf/pull/1189
Note: Python 3.14 is not officially supported yet (https://github.com/nolar/kopf/pull/1188), but should be runnable (at your own risk).
Full Changelog: https://github.com/nolar/kopf/compare/1.38.0...1.39.0
Deprecate Python 3.8 & upgrade to Python 3.13 in CI by @nolar in https://github.com/nolar/kopf/pull/1164
Full Changelog: https://github.com/nolar/kopf/compare/1.37.5...1.38.0
Handle event refs with no apiVersion/kind fields at all by @nolar in https://github.com/nolar/kopf/pull/1151
Full Changelog: https://github.com/nolar/kopf/compare/1.37.4...1.37.5
Ensure compatibility with python-json-logger>=3.1.0 by @nolar in https://github.com/nolar/kopf/pull/1149
Full Changelog: https://github.com/nolar/kopf/compare/1.37.3...1.37.4
Fix the SphinxDocs builds by @nolar in https://github.com/nolar/kopf/pull/1136
Full Changelog: https://github.com/nolar/kopf/compare/1.37.2...1.37.3
Close dependent http responses before closing api context by @asteven in https://github.com/nolar/kopf/pull/1109
Full Changelog: https://github.com/nolar/kopf/compare/1.37.1...1.37.2
Refresh the README badges by @nolar in https://github.com/nolar/kopf/pull/1093 (released to update the PyPI intro page).
Full Changelog: https://github.com/nolar/kopf/compare/1.37.0...1.37.1
Satisfy aiohttp's deprecation of shutdown timeout kwargs by @nolar in https://github.com/nolar/kopf/pull/1091
Full Changelog: https://github.com/nolar/kopf/compare/1.36.2...1.37.0
Fix crash when an APIResource has no verbs by @lukasstockner in https://github.com/nolar/kopf/pull/1000
Full Changelog: https://github.com/nolar/kopf/compare/1.36.1...1.36.2
Add retry after receiving too many requests error from kubernetes by @wjsi in https://github.com/nolar/kopf/pull/963
too many requests error from kubernetes by @wjsi in https://github.com/nolar/kopf/pull/963Full Changelog: https://github.com/nolar/kopf/compare/1.36.0...1.36.1
Upgrade to Python 3.11 by @nolar in https://github.com/nolar/kopf/pull/968
Full Changelog: https://github.com/nolar/kopf/compare/1.35.6...1.35.7
Login handlers can now inject graceful expiration time to credentials (i.e. not waiting for HTTP 401s). #933
New features:
Documentation:
Documentation links and grammar fixes. #928
Cease using the deprecated rbac.authorization.k8s.io/v1beta1. #887
Improvements:
Bugfixes:
metrics.k8s.io, v1/componentstatuses, etc). #871Documentation:
rbac.authorization.k8s.io/v1beta1. #887Contributor experience:
old, new, diff, operation kwargs for validation/mutation webhooks. Thanks to @samj1912. #857
Improvements:
old, new, diff, operation kwargs for validation/mutation webhooks. Thanks to @samj1912. #857Bugfixes:
async_timeout as an async context manager only. #859Stop daemons on operator exit (regression since 1.35.0). #853
Bugfixes:
Render the lists properly in ReadTheDocs. #846
Documentation:
Ready for Python 3.10. #828 #837
Improvements:
Bugfixes:
asyncio.TimeoutError during API requests (by @philipp-sontag-by). #841Refactoring:
aiojobs with a self-made fire-and-forget task orchestrator (for Python 3.10). #835Ready for Python 3.10. #828 #837
Improvements:
Bugfixes:
asyncio.TimeoutError during API requests (by @philipp-sontag-by). #841Refactoring:
aiojobs with a self-made fire-and-forget task orchestrator (for Python 3.10). #835Subresources (both specific and "*"-masked) are supported in the validating/mutating admission webhooks. #832
New features:
Bugfixes:
Subresources (both specific and "*"-masked) are supported in the validating/mutating admission webhooks. #832
New features:
Bugfixes:
Configurable timeouts for API operations and TCP connections. #793
New features:
Bugfixes:
Contributor experience:
Generate proper JSONPatch on mutating webhooks when the key is absent. Thanks to @cjbaar. #803.
Bugfixes:
Contributor experience:
Configurable timeouts for API operations and TCP connections. #793
New features:
Bugfixes:
Contributor experience:
Propagate the sub-handling context to sub-sub-handlers. #780
Bugfixes:
Rudimentary authentication from kubeconfig/serviceaccount with no pykube-ng/kubernetes libraries. #771
New features:
Bugfixes:
Improvements:
Union is needed). #747 #753Contributor experience:
Internal refactoring:
<img src="https://user-images.githubusercontent.com/544296/118763139-9f68da00-b877-11eb-8a28-b3c90d7a3c6a.png" height="200"/>
Rudimentary authentication from kubeconfig/serviceaccount with no pykube-ng/kubernetes libraries. #771
New features:
Improvements:
Contributor experience:
Internal refactoring:
Restore specific groups for peering selectors to prevent whole-cluster API group scanning. #741
Bugfixes:
Improvements:
Union is needed). #747 #753Internal refactoring:
Contributor experience:
Validating/mutating admission webhooks: #708 #724 #721 #736
New features:
Improvements:
Bugfix:
Contributor experience:
<img src="https://user-images.githubusercontent.com/544296/116200138-40142000-a738-11eb-9f3c-a56726df558b.png" height="200"/> <img src="https://user-images.githubusercontent.com/544296/116200145-41dde380-a738-11eb-94aa-b945da89dc71.png" height="200"/>
Solved K8s API flooding with endless dummy-patching in certain conditions. Many thanks to @paxbit! #731 #728 #686
Bugfixes:
Fix absent namespaces for cluster-scoped resources in hierarchies. #726 #727
Bugfix:
Validating/mutating admission webhooks: #708 #724 #721
New features:
Improvements:
Contributor experience:
Fix absent namespaces for cluster-scoped resources in hierarchies. #726
Bugfix:
Documentation only (to rebuild ReadTheDocs):
Documentation only (to rebuild ReadTheDocs):
Hotfix an "unexpected kwarg" error for indexing when peering is enabled. #712
Bugfixes:
Contribution workflow:
master branch is renamed to main. #711In-memory indexing & caching for faster lookup/listing of resources from all handlers. #661
New features:
memo with keys available throughout all operator- & resource-level handlers. #667memo= with arbitrary values to be used as a context. #667memo classes for embedded operators instead of the default kopf.Memo. #667Improvements:
pykube-ng & kubernetes) objects/models are now supported for hierarchies. #672forced= flag in all functions, incl. names/namespaces.nested= now accepts a single string too: nested="spec.jobTemplate".adopt() has got forced & strict options (in addition to nested).Bugfixes:
0.0.0.0 for liveness probes in docs. #665 by @brennermContributors experience:
Refactorings:
In-memory indexing & caching for faster lookup/listing of resources from all handlers. #661
New features:
memo with keys available throughout all operator- & resource-level handlers. #667memo= with arbitrary values to be used as a context. #667memo classes for embedded operators instead of the default kopf.Memo. #667Improvements:
pykube-ng & kubernetes) objects/models are now supported for hierarchies. #672forced= flag in all functions, incl. names/namespaces.nested= now accepts a single string too: nested="spec.jobTemplate".adopt() has got forced & strict options (in addition to nested).Bugfixes:
0.0.0.0 for liveness probes in docs. #665 by @brennermContributors experience:
Refactorings:
Nothing published for this version
Slightly BREAKING in cases assumed to be extremely rare (see #674 for details):
Slightly BREAKING in cases assumed to be extremely rare (see #674 for details):
id=.field=) are used on resume/create/update/delete handlers AND the resource is in the handling cycle at the moment of the upgrade, these handlers will be re-executed;
<1.29) are not affected.Bugfixes:
Handlers parametrization with the param option & param kwarg. #659
New features:
param option & param kwarg. #659Bugfixes:
resource kwarg is added to replace cause.resource (forgotten by mistake). #658BREAKING CHANGES! The major version increase (0.x → 1.x) means that there are changes in the public interface with no backwards compatibility. Pay att…
BREAKING CHANGES! The major version increase (0.x → 1.x) means that there are changes in the public interface with no backwards compatibility. Pay attention when upgrading — most of them have quick replacements.
Most of these legacies are extremely old and it is highly unlikely that they were used in any existing operators. The DeprecationWarnings were issued for all these features (except namespaces). See #511.
Dropped features with replacements:
| Removed feature | Replacement feature |
|---|---|
cooldown= option of decorators |
backoff= option |
event kwarg in @kopf.on.event |
reason kwarg |
cause kwarg in handlers |
use all kwargs directly |
kopf.login() sync function |
@kopf.on.login handlers and async activities |
kopf.config module |
settings kwarg of @kopf.on.startup() handlers |
kopf.config.get_pykube_cfg() for patching |
@kopf.on.login() handlers |
kopf.HandlerFatalError |
kopf.PermanentError |
kopf.HandlerRetryError |
kopf.TemporaryError |
kopf.create_tasks() (sync) |
kopf.spawn_tasks() (async) |
kopf.events.event/info/warn/exception() |
the same directly in the kopf module |
None for labels=/annotations= filters |
kopf.PRESENT (None now raises exceptions) |
Positional field in @on.field('group', 'v1', 'plural', 'field') |
kwarg field='field' instead |
| Unversioned keys in storages | generate v1/v2 keys explicitly |
| Storages with unprefixed annotations | prefix is now mandatory; defaults to kopf.zalando.org/… |
@kopf.on.this(…) for sub-handlers |
@kopf.subhandler(…) (for readability) |
Dropped features without replacements:
OperatorRegistry — use it only as an object for the registry= kwarg. #625 #611Resource[Watching|Spawning|Changing]Registry, ActivityRegistry. #625 #611SimpleRegistry, GlobalRegistry, etc. #625Deprecated features:
operator(namespace='…') → operator(namespaces=['…']). #600operator(namespace=None) → operator(clusterwide=True). #600pykube-ng is not installed implicitly as a dependency (install explicitly or via kopf[full-auth]). #655New features:
-n default -n myapp. #500--namespace myapp-*,!*-pr-*. #500@kopf.on.event('kopf.dev', 'kex'). #500@kopf.on.event(kind='Pod'). #500@kopf.on.event('pods'). #500@kopf.on.event(category='all'). #500@kopf.on.event(kopf.EVERYTHING). #500@kopf.on.event(…, field='spec.field', value=kopf.PRESENT). #573@kopf.on.event(…, field='spec.field', value='value'); callbacks are supported. #573@kopf.on.update(…, field='spec.field', old=1, new=2); callbacks are supported. #573Improvements of existing features:
Documentation improvements:
x-kubernetes-preserve-unknown-fields in the docs. #612kopf.zalando.org/v1 to kopf.dev/v1 (but not annotations and finalizers). #643 #644Bugfixes:
kind: Event from EVERYTHING to avoid "resource explosion". #636Contributor experience:
Internal refactorings:
pytest-mock with asynctest. #645Your coding agent can read these notes before it upgrades. Set up the MCP server →