ADR 0002 - AppCat Framework 2.0: Claim Lifecycle and Provisioner (CLAP)

A claim and its composite share a single name that differs only by an X prefix on the composite’s kind. A VSHNPostgreSQL claim maps to an XVSHNPostgreSQL composite, in the same group and version. This convention is the operator’s only way to tell the two apart: anything whose kind starts with X followed by a capital letter is treated as a composite and left alone, everything else is treated as a claim. It assumes no real service is ever named with that same X-then-capital shape.

Nothing upstream creates the claim CRD: Slapper emits the XRD and Crossplane turns it into the composite CRD, but the claim CRD is missing. So CLAP generates it. A watcher observes the Crossplane XRDs in the appslap.io group and, for each one, renders a matching claim CRD.

The claim CRD is the XRD with the composite identity removed: the names have their leading X stripped (XVSHNPostgreSQL → VSHNPostgreSQL), the schema is carried over as-is, and the scope is Namespaced so customers create claims in their own namespace. Writes are idempotent, so a schema change on the XRD flows through to the claim CRD.

CLAP does not clean up these CRDs itself. Each claim CRD points back to its XRD as owner, so Kubernetes deletes it automatically when the XRD goes away. XRDs whose kind is not X-prefixed, or that are malformed, are skipped.

Because services are discovered at runtime, CLAP does not register a controller per service kind ahead of time. Instead, a single CRD watcher observes the CRDs in the appslap.io group and, for each claim kind it sees, spins up a dedicated controller on the fly. Composite kinds are ignored; only claims get a controller. The watcher remembers which kinds it has already started so a given kind is only wired up once, and the controllers it creates are tied to the operator’s lifecycle, shutting down cleanly when the operator stops.

These controllers work against the claims generically rather than through generated Go types, which is what lets a brand-new service be handled without recompiling the operator.

Each claim gets its own namespace, whose name CLAP records on the claim under status.instanceNamespace. The name is derived from the claim’s own name plus a random suffix the API server appends, so two claims with the same name in different customer namespaces never collide.

The tricky case is a crash that happens after the namespace is created but before that name is written back to the claim. Without care, the next reconcile would create a second namespace and orphan the first. To avoid that, CLAP stamps each namespace with the claim’s unique ID, and on every reconcile first looks for a namespace already carrying that ID and re-adopts it. Once the namespace name is recorded on the claim, later reconciles simply make sure it still exists.

The claim’s desired state flows down into the composite, and the composite’s observed state flows up into the claim. On the way down, CLAP copies the claim’s spec onto the composite in the instance namespace, creating it the first time and updating it thereafter. On the way up, it copies the composite’s status back onto the claim (preserving the namespace name CLAP owns there) and only writes when something has actually changed, so an unchanged status does not churn the claim.

So that the claim updates promptly when its composite changes, each composite carries a back-reference to the namespace of the claim that owns it, and the operator watches composites as well as claims, routing any composite change back to the right claim.

Only the claim’s spec flows to the composite. Labels and annotations on the claim are deliberately left behind, so GitOps tools do not mistake the composite for being owned by the same source as the claim. The Crossplane-specific portion of the spec is also dropped on the way down.

CLAP takes no dependency on Crossplane’s code; it treats claims, composites and the XRDs it reads as ordinary Kubernetes objects rather than importing Crossplane’s Go types. It does watch the Crossplane XRD type, so that type has to be installed for CLAP to read XRDs, but the operator still builds without a Crossplane dependency and stays decoupled from the in-progress composition and stdlib work.

When a claim is deleted, CLAP tears down what it provisioned, in reverse order: the composite first, then the instance namespace. A finalizer on the claim holds it in place until that finishes, and the finalizer is added before anything is created, so the operator never provisions something it could not later clean up.

The composite is removed first, and the operator waits until it has fully disappeared before touching the namespace. This gives Crossplane time to tear down the external resources the composite manages, rather than pulling the namespace out from under them. Once the composite is gone the namespace is deleted, and only after it finishes terminating is the finalizer released and the claim allowed to disappear. Because nothing reports when a namespace finishes winding down, the operator re-checks an in-progress teardown on a short timer.