Core controller for IPAddressClass/IPAddressClaim/IPAddress (local.sdn.cozystack.io)

[lllamnyp]

Implements the core, class-agnostic controller for IP addresses as a first-class resource, per the design proposal in cozystack/community#35 — the analog of the generic PVC/PV binding controller in the storage subsystem. Per-class drivers (the CSI analogue) are a separate project and are out of scope here; this PR defines the contract they plug into.

Resource model

All kinds live in local.sdn.cozystack.io/v1alpha1 (the design doc sketches ipam.cozystack.io; this repo was pointed at the local.sdn group deliberately).

• IPAddressClass (cluster-scoped): provisioner (immutable, names the driver), reclaimPolicy (Retain|Delete, default Retain), opaque parameters (preserved-unknown-fields object, never parsed by the core). The annotation ipaddressclass.local.sdn.cozystack.io/is-default-class: "true" marks the default class.
• IPAddress (cluster-scoped): the inventory object — address (immutable), className, reclaimPolicy, claimRef (namespace/name/uid), and the source union (fromClass: {} vs providerRef: {id}, exactly-one enforced by CEL). Phases: Pending, Available, Bound, Released, Conflict, Lost. status.associatedTo names the workload the address is announced for; nil means reserved but inert.
• IPAddressClaim (namespaced, the whole tenant-facing API): className (empty ⇒ default class), family (IPv4|IPv6|Dual), optional addressName pre-binding. status.addresses is a list so a Dual claim reports both families. Phases: Pending, Bound, Lost.

What the core controller does

Claim reconciler — resolves the class (spec → sticky status record → single default-annotated class; zero or multiple defaults surface as conditions and events), stamps the local.sdn.cozystack.io/provisioner annotation for drivers, accepts driver pre-bound addresses (completing the claimRef UID), matches Available addresses by class and family, and reports Bound/Pending/Lost with ClassResolved and Bound conditions. On deletion, a protection finalizer runs the reclaim flow: Retain marks the address Released (keeping claimRef until an admin clears it), Delete deletes the IPAddress so the driver's finalizer can tear down the backend.

Address reconciler — phase bookkeeping (Available ↔ Bound ↔ Released, with Released + cleared claimRef ⇒ Available again), deletion protection while a live claim holds the address, and a safety-net reclaim when the bound claim vanished without the claim-side flow running (including UID-mismatch stale bindings). Conflict and Lost are treated as driver-owned sticky states.

Per-class driver extension contract

1. Driver watches claims stamped with its name in the local.sdn.cozystack.io/provisioner annotation and not yet Bound.
2. It allocates (source.fromClass) or adopts (source.providerRef), interpreting class.spec.parameters, and creates the IPAddress with claimRef pre-set (UID optional — the core completes it), reclaimPolicy copied from the class, and its own finalizer for backend teardown.
3. The core completes binding on both sides.
4. On Delete reclaim the core deletes the IPAddress; the driver's finalizer deallocates before the object goes away.
5. Association is driver territory: resolving the Service annotation local.sdn.cozystack.io/ip-address-claim, writing the backend pin annotation, maintaining status.associatedTo, and setting Conflict/Lost.

Decisions where the design is tentative (it is explicitly a stub on controller mechanics)

• Provisioner signalling: PV-style annotation stamp (volume.kubernetes.io/storage-provisioner analog) rather than a driver-registration CRD. The design leaves in-tree vs out-of-tree open; the annotation contract works for both and doesn't foreclose a CRD-based capability registry later.
• Provisioner capabilities (Allocate/Adopt/Pin from design §4) are not modeled in v1alpha1 — with no capability registry object there is nowhere to declare them yet. A class over a Pin-less backend must be rejected by its driver; revisit when the driver contract gets its own CRD.
• parameters is an opaque object (preserve-unknown-fields), not StorageClass-style map[string]string, so the design's addresses: ["203.0.113.0/24"] example is valid as written.
• Default-class conflicts (multiple annotated defaults) leave the claim Pending with a MultipleDefaultClasses condition instead of silently picking one (Kubernetes' newest-wins StorageClass behaviour felt too magical for an alpha API).
• Dual-stack is two IPAddress objects bound to one claim — the direction open question 4 leans toward; the status list makes it representable either way.
• spec.addressName on the claim (PVC volumeName analog) for pinning a specific Available address — implied by the "give me this one" discussion and the Released-address reuse flow, not spelled out in the design.
• Claim resolution is sticky via status.className, since without an admission webhook the controller can't default spec.className at create time the way the PV admission plugin does.
• UID-mismatched claimRef (claim deleted and recreated under the same name) is treated as a stale binding and reclaimed, never adopted by the new claim.
• Association, Service watching, and conflict detection (design §§5–8) are left entirely to drivers: the backend pin annotation is per-backend by nature, and the core never touches Services. The API carries the fields (associatedTo, Conflict) so drivers converge on one shape. The ValidatingAdmissionPolicy from the Security section ships with the MetalLB driver, not here.

Testing

Hermetic fake-client unit tests for both reconcilers (class resolution and default handling, pre-bound and matched binding, dual-stack, both reclaim policies, deletion protection, sticky phases, stale-UID reclaim). The scaffolded envtest suite was dropped in favour of these; e2e belongs with the drivers.

🤖 Generated with Claude Code