Kubernetes Operator Pythonic Framework (Kopf)

Warnings

• breaking 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.
  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(...)`).
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install kopf Standard Installation
• pip install 'kopf[dev]' Installation with Development Extras
• pip install 'kopf[full-auth]' Installation with Full Authentication Extras

Imports

• kopf

  import kopf

  The primary import for accessing all Kopf functionalities, including decorators and settings.

Quickstart

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.

import kopf
import os

@kopf.on.create('kopfexamples')
def create_fn(spec, name, logger, **kwargs):
    message = f"Hello from Kopf! Created {name} with spec: {spec}"
    logger.info(message)
    return {'message': message}

@kopf.on.update('kopfexamples')
def update_fn(old, new, diff, name, logger, **kwargs):
    logger.info(f"Updated {name} with changes: {diff}")
    return {'message': f"Updated {name} with changes."}

@kopf.on.delete('kopfexamples')
def delete_fn(name, logger, **kwargs):
    logger.info(f"Deleted {name}. Goodbye!")
    return {'message': f"Deleted {name}."}

# To run this operator:
# 1. Apply the kopfexamples CRD: kubectl apply -f https://github.com/nolar/kopf/raw/main/examples/crd.yaml
# 2. Run the operator: kopf run your_operator_file.py --verbose
# 3. Create a custom resource: kubectl apply -f - <<EOF
# apiVersion: kopf.dev/v1
# kind: KopfExample
# metadata:
#   name: my-example
# spec:
#   field: value
# EOF