v0.22.1

Overview

This is a documentation release, with no code changes. It adds two guidelines for the code that you write around the framework: which controller layer owns a write, a requeue, and a decision, and which signal reports a fact. Both are in the docs site and in the ocf Claude Code plugin skills, so an agent that builds an operator on the framework gets them too. Upgrade if you use the plugin, or read the two pages linked below.

What's new

• Give each controller layer one visible responsibility. Agents wrote helpers that also save the object they change, sub-reconcilers that return their own reconcile.Result, and lower layers that are correct only because of a check in their caller. A reader then had to open the callers and the callees of a function to know why it is correct. A new guideline in docs/guidelines.md has three rules, each with a BAD and GOOD example. A helper does not save what it changes. Only Reconcile decides the requeue, for example with EarliestGraceRemaining. Each layer is correct on its own inputs. The guideline ends with red flags, and the structuring-operators skill lists it in its index. (#224 via #226)
• Choose a signal by its reader. Agents recorded an event or an Info log on every reconcile, recorded an event for an apply that the framework already reported, or logged an error that Reconcile also returned. A new section, "Signals from your own controller", names the four signals (condition, event, log, metric) and their readers. It lists each event that the framework records, including ResourceDeleted and ResourceOrphaned, which were not documented before. Its main rule is that an event marks a transition, never a reconcile. It also explains why an event on every reconcile costs more than noise: depending on whether the owner changed, the events fold into one series that hides changes, or each reconcile creates a new Event object. The building-components skill points to it where it introduces EventRecorder. (#225 via #227)

Fixes

• The "Resource metrics" section of docs/component.md said that client-go's spam filter truncates repeated events. The events.k8s.io recorder that the framework uses has no spam filter. The section now says why only the apply counters show a resource that is rewritten on every reconcile: events concern one owner, expire after one hour by default, and give Prometheus no rate to alert on. (#227)

Changelog

• docs(observability): say when a controller records an event, a log, a condition, or a metric (#227)
• docs(guidelines): say which controller layer owns a write, a requeue, and a decision (#226)

Full changelog: v0.22.0...v0.22.1