kopf-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# kopf conventions

kopf-specific implementation details for Python operators. The
framework-agnostic reconcile principles (always-requeue, idempotency,
finalizers, ownerReferences, field manager) live in
`kubernetes-operator-conventions` — this skill is the kopf wiring that those
principles compile down to, plus the sharp edges that bite in practice.

## Events & posting — the model you must get right

kopf has **two completely separate** ways an event reaches the cluster, gated
by **two different settings**. Confusing them is the #1 cause of "I had errors
but no events showed up on the resource".

1. **Explicit calls** — `kopf.event(body, type=..., reason=..., message=...)`
   posts **iff `settings.posting.enabled` is True** (the default), whatever
   `posting.level`. The shorthands also check the level: `kopf.info` needs
   `level <= INFO`, `kopf.exception` `level <= ERROR`, and `kopf.warn`
   `level <= WARNING` while ignoring `enabled`. Full control over
   `type` / `reason` / `message`.
2. **Log-record posting** — kopf can mirror log lines made on the **object
   logger** (`logger` injected into a handler) as events. This is gated by
   **`settings.posting.loggers`**, which **defaults to `False`**. When off,
   `logger.error(...)` / `logger.warning(...)` are logged but **never posted**.
   `posting.enabled` does **not** turn this on — only `posting.loggers` does.

### The trap

> **`raise kopf.TemporaryError(...)` does NOT, on its own, post a Kubernetes
> event.** The error event you expect only exists if either (a) you post it
> explicitly with `kopf.event`, or (b) `settings.posting.loggers = True` so the
> framework's error log of the failure becomes an event.

Setting only `settings.posting.enabled = True` (a very common operator setup)
buys you nothing for errors raised via `TemporaryError`, because that path
surfaces through the **logger**, not an explicit `kopf.event`. Any docstring or
skill that says "kopf posts a Warning event for free when you raise
TemporaryError, provided posting.enabled is on" is **wrong** — it needs
`posting.loggers`.

kopf's log-to-event handler posts a record only when **all** of these hold: `posting.enabled`, `record.levelno >= posting.level`,
**`posting.loggers`**, and the record carrying a `k8s_ref` (i.e. it was logged
on the *object* logger, not a module-level `logging.getLogger(...)`).

### Surfacing errors as events — post them explicitly

- **Explicit lifecycle events: the failure event.** Post your own events at
  the reconcile level — good `reason`s, one event per outcome, no framework
  duplication. Wrap the handler:

  ```python
  @kopf.on.create(GROUP, VERSION, PLURAL)
  @kopf.on.resume(GROUP, VERSION, PLURAL)
  @kopf.on.update(GROUP, VERSION, PLURAL)
  async def reconcile(spec, body, name, logger, **_):
      try:
          changed = await _reconcile(spec, body, name, logger)
      except Exception as exc:
          logger.error("reconcile failed", extra={"cause": str(exc)})
          kopf.event(body, type="Warning", reason="ReconcileFailed",
                     message=f"Reconcile failed: {exc}")
          if isinstance(exc, kopf.TemporaryError):
              raise
          raise kopf.TemporaryError(f"reconcile failed: {exc}") from exc
      if changed:
          kopf.event(body, type="Normal", reason="Reconciled",
                     message="Desired state applied.")
  ```

  Make the raised `TemporaryError` message carry the failing operation + cause
  (e.g. `"creating the backing database failed: 500 ..."`) so the single
  rolled-up `ReconcileFailed` event still names what broke; anything else is
  wrapped, never re-raised raw, and the requeue holds either way. `_reconcile`
  returns whether it changed anything: `on.resume` runs it for every CR at each
  operator start, and a steady-state pass posts nothing.

- **Log-posted events: extra detail, never the failure event.** To add one
  event per failing operation from the requeue chokepoint without plumbing
  `body` everywhere, set all three in the startup handler:

  ```python
  settings.posting.enabled = True
  settings.posting.loggers = True
  settings.posting.level   = logging.WARNING   # NOT the INFO default
  ```

  Without raising the level off its `logging.INFO` default, **every** info line
  becomes an event and floods the object. That level also silences
  `kopf.info`, so post Normal events with `kopf.event(type="Normal")`, as the
  wrapper above does. Even then the posted events carry
  `reason="Logging"` (less descriptive than an explicit one), and the framework
  may also post its own error log — expect duplicates.

Log posting never replaces the explicit Warning that
`kubernetes-operator-conventions` requires: it hangs on three settings and on
logging through the object logger, so a settings refactor or a module-level
logger drops the event without a sound. Don't half-set it (`enabled` without
`loggers`) and assume errors post — they won't.

### Cluster-scoped objects & other event gotchas

- **Events are namespaced; cluster-scoped CRs are not.** For a cluster-scoped
  object kopf posts the event into the operator's *own* namespace
  (`get_default_namespace()`, falling back to `default`), with `involvedObject`
  pointing at the CR. `kubectl describe <clusterscoped>` still finds it by uid.
- **RBAC.** The operator's (Cluster)Role needs this rule; missing it is
  silent (see next point):

  ```yaml
  - apiGroups:
      - ""
    resources:
      - events
    verbs:
      - create
      - patch
  ```
- **POST failures are swallowed.** `events.post_event` catches API errors and
  only emits `logger.warning("Failed to post an event. ... Code: 403 ...")`.

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude