{"id":3528,"library":"kopf","title":"Kubernetes Operator Pythonic Framework (Kopf)","description":"Kopf (Kubernetes Operator Pythonic Framework) is a Python framework designed to simplify the development of Kubernetes operators. It enables developers to write event-driven or state-driven handler functions with minimal boilerplate, focusing on domain logic rather than Kubernetes API infrastructure. The library is production-ready and stable (semantic v1), with current version 1.44.5, and receives regular maintenance for new Python and Kubernetes versions, without active development of new major functionality or imminent breaking changes.","status":"active","version":"1.44.5","language":"en","source_language":"en","source_url":"https://github.com/nolar/kopf","tags":["kubernetes","operator","framework","k8s","python","devops","cloud-native"],"install":[{"cmd":"pip install kopf","lang":"bash","label":"Standard Installation"},{"cmd":"pip install 'kopf[dev]'","lang":"bash","label":"Installation with Development Extras"},{"cmd":"pip install 'kopf[full-auth]'","lang":"bash","label":"Installation with Full Authentication Extras"}],"dependencies":[{"reason":"Required runtime environment.","package":"python","optional":false},{"reason":"Often used for direct Kubernetes API interaction within operator handlers.","package":"kubernetes","optional":true}],"imports":[{"note":"The primary import for accessing all Kopf functionalities, including decorators and settings.","symbol":"kopf","correct":"import kopf"}],"quickstart":{"code":"import kopf\nimport os\n\n@kopf.on.create('kopfexamples')\ndef create_fn(spec, name, logger, **kwargs):\n    message = f\"Hello from Kopf! Created {name} with spec: {spec}\"\n    logger.info(message)\n    return {'message': message}\n\n@kopf.on.update('kopfexamples')\ndef update_fn(old, new, diff, name, logger, **kwargs):\n    logger.info(f\"Updated {name} with changes: {diff}\")\n    return {'message': f\"Updated {name} with changes.\"}\n\n@kopf.on.delete('kopfexamples')\ndef delete_fn(name, logger, **kwargs):\n    logger.info(f\"Deleted {name}. Goodbye!\")\n    return {'message': f\"Deleted {name}.\"}\n\n# To run this operator:\n# 1. Apply the kopfexamples CRD: kubectl apply -f https://github.com/nolar/kopf/raw/main/examples/crd.yaml\n# 2. Run the operator: kopf run your_operator_file.py --verbose\n# 3. Create a custom resource: kubectl apply -f - <<EOF\n# apiVersion: kopf.dev/v1\n# kind: KopfExample\n# metadata:\n#   name: my-example\n# spec:\n#   field: value\n# EOF","lang":"python","description":"This quickstart demonstrates a basic Kopf operator that watches for 'kopfexamples' custom resources. It includes handlers for creation, update, and deletion events, logging relevant information and returning status updates. The code is meant to be saved as a Python file (e.g., `your_operator_file.py`) and run using the `kopf run` CLI command after applying the necessary CRD."},"warnings":[{"fix":"For custom resources, add `x-kubernetes-preserve-unknown-fields: true` to your CRD schema. Alternatively, configure Kopf to use `AnnotationsDiffBaseStorage` for persistence (`settings.persistence.diffbase_storage = kopf.AnnotationsDiffBaseStorage(...)`).","message":"Kubernetes versions 1.16 and later introduce strict structural schemas that prune unknown fields in custom resources. If Kopf's status storage is not configured to use annotations, any status fields written by Kopf might be silently lost unless `x-kubernetes-preserve-unknown-fields: true` is explicitly added to your Custom Resource Definition (CRD) schema.","severity":"breaking","affected_versions":"All versions when running on Kubernetes >= 1.16 without proper CRD configuration."},{"fix":"Upgrade Kopf to version 1.44.0 or newer. This version introduced the use of bookmark events to maintain connection liveness and prevent such freezes.","message":"Prior to Kopf version 1.44.0, operators could experience connection freezes or silent disconnections when running behind load balancers in Kubernetes clusters, especially during periods of inactivity. This was due to load balancers closing idle connections while the operator remained unaware.","severity":"gotcha","affected_versions":"<1.44.0"},{"fix":"Kopf includes a 'peering' mechanism to coordinate multiple operator instances. Ensure your deployment is configured to leverage Kopf's peering capabilities, which can be done automatically or configured manually via the `peering.yaml` resource. In development, the `kopf run` command can temporarily suppress deployed instances.","message":"Running multiple instances of a Kopf operator for the same resource kind without proper peering configuration can lead to double-processing of events and inconsistent states.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install Kopf with the `dev` extra: `pip install 'kopf[dev]'`. This ensures that necessary development-only dependencies (e.g., for SSL cryptography and certificate generation) are available.","message":"When developing admission webhooks or using features like self-signed certificates and Ngrok tunnels for local development, the `kopf[dev]` extra package is required. Without it, Kopf will raise startup errors if these functionalities are attempted.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}