Skip to content

Commit a07dd3e

Browse files
committed
design-proposal(ip-address-claims): require serviceability before the handoff; correct the policy's status
From the architectural review of 2026-11-02. The driver releases the hold on the annotation alone, so a Service that MetalLB will not serve ends up with the address unheld, announced nowhere, and reported as attached. §5 now requires the driver to check type and loadBalancerClass and refuse with an event before it sets associatedTo and deletes the holder. A failure case states the outcome. The admission policy is in an open PR, not in the driver's chart, so Implementation status and Rollout say layer 1 is absent on main. Auto-claim skips any Service carrying a backend pool or pin input, which excludes the driver's placeholders structurally. Duplicate default or auto-claim classes are a stated runtime condition. The handoff window lasts until the first successful pin, not one reconcile interval, in §6 and in record 0001. Record 0001 names the ClusterIP-per-placeholder ceiling. A Lost address keeps its claimRef until an admin acts. One sentence on BGP: reservations do not change route-table growth. Community #99 is cited for the per-class quota shape. Signed-off-by: Timofei Larkin <[email protected]> Assisted-by: LLM
1 parent ee24fb5 commit a07dd3e

2 files changed

Lines changed: 48 additions & 16 deletions

File tree

‎design-proposals/ip-address-claims/README.md‎

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -121,9 +121,10 @@ Phase 1 of *Rollout* exists under the Cozystack organisation:
121121
(cozystack/address-controller#7).
122122
- **[metallb-iad](https://github.com/cozystack/metallb-iad)**: the reference driver for
123123
MetalLB. It holds a reservation as a placeholder Service in its own namespace, so
124-
MetalLB's accounting refuses to assign a held address elsewhere.
125-
cozystack/metallb-iad#6 ships the admission policy of *Security* as an opt-in chart
126-
template; cozystack/metallb-iad#5 opts the placeholders out of auto-claim.
124+
MetalLB's accounting refuses to assign a held address elsewhere. On `main` the chart
125+
has no admission policy, so layer 1 of *Security* is absent as shipped.
126+
cozystack/metallb-iad#6, open, adds the policy as an opt-in chart template;
127+
cozystack/metallb-iad#5, open, opts the placeholders out of auto-claim.
127128
- **cozystack/cozystack#3382** packages both as optional system packages, with tenant RBAC
128129
on claims and a distribution-specific admission policy. The driver's policy is the
129130
reference; a distribution may disable it and ship its own.
@@ -138,7 +139,8 @@ cozyplane, an address survived delete-and-rebind and stayed reachable.
138139
This tests the association seam only. The allocation seam, a second provisioner, is
139140
untested (*Rollout*).
140141

141-
**Specified here and not yet implemented:** the `loadBalancerClass` check of §5; pinning
142+
**Specified here and not yet implemented:** the `loadBalancerClass` check and the
143+
serviceability check of §5; the pool-or-pin exclusion of §6; pinning
142144
only the families a Service carries (§2); conditions on `IPAddress` (§2) and the
143145
`Associated` condition on a claim (§5); per-class conflict adjudication (§8); the
144146
held-before-minted rule of §6; the release delay and the class-deletion guard (*Failure
@@ -422,6 +424,14 @@ Service. A mismatch is a refused association naming both values. Whoever creates
422424
Service sets the field at creation; a controller that creates the Service and names the
423425
claim reads the class first.
424426

427+
**Serviceability before handoff.** The driver checks that it can serve the consumer
428+
before it releases the hold: the Service is `type: LoadBalancer`, its `loadBalancerClass`
429+
matches the class, and the backend will act on the pin. A consumer that fails the check
430+
is refused with an event, `associatedTo` stays unset, and the holder keeps the address.
431+
The order matters. Setting `associatedTo` disarms the hold (§6), so a consumer recorded
432+
before it is checked leaves the address unheld, announced nowhere, and reported as
433+
attached. Specified, not implemented.
434+
425435
**Detaching.** When the annotation is removed, the driver withdraws its pin, clears
426436
`associatedTo`, and holds the address again. The `IPAddress` stays `Bound` to its claim:
427437
reserved and attached to nothing, like an unassociated EIP. MetalLB keeps an assignment
@@ -470,7 +480,11 @@ the `IPAddressClass`: for a LoadBalancer Service with no claim annotation, no
470480
with the Service's name in the Service's namespace, owned by the Service, and writes the
471481
§5 annotation on the Service. The driver associates as usual. A Service can name a class
472482
or opt out through annotations the core defines; cloud-provider-kubevirt copies these
473-
from the guest Service. The auto-claim class is independent of the default class.
483+
from the guest Service. The core also skips any Service that carries a backend pool or pin
484+
input (*Security* lists them): such a Service has chosen its address source. The driver's
485+
placeholders carry the pool annotation, so this rule excludes them without the opt-out
486+
annotation and without knowledge of the driver's namespace. The auto-claim class is
487+
independent of the default class.
474488

475489
Two rules follow:
476490

@@ -492,7 +506,9 @@ disagree with `status.loadBalancer` briefly. The design accepts eventual consist
492506
Two gaps remain with holders in place:
493507

494508
- **The handoff.** Releasing the holder and pinning the workload's Service is not atomic.
495-
During that window the address is unheld. Layer 1 of *Security* covers it.
509+
The address is unheld until the first successful pin; `associatedTo` is already set, so
510+
a failed pin or a driver restart does not re-arm the hold. Layer 1 of *Security* covers
511+
the window.
496512
- **Annotation writers.** With the pool at `autoAssign: false`, a plain Service receives a
497513
reserved address only by naming the pool or pinning the address. Layer 1 gates that
498514
write; layer 2 detects it.
@@ -512,6 +528,10 @@ range moved into a class must leave its old pool first.
512528
not stop a Service from naming the pool (`metallb.io/address-pool`) or pinning an address
513529
(`metallb.io/loadBalancerIPs`); §8 and *Security* cover that.
514530

531+
Under BGP, MetalLB announces each assigned address as a host route whether or not it is
532+
reserved, so scattered reservations within a range do not change route-table growth.
533+
`BGPAdvertisement.aggregationLength` summarises as it does without this proposal.
534+
515535
### 8. How this rides real allocators
516536

517537
No pool layout guarantees a reservation. A Service can name the reserved pool or pin an
@@ -682,8 +702,9 @@ closes the gap:
682702

683703
The data belongs in an optional entitlement object in the core: per namespace, per class,
684704
the number of claims the namespace may hold. Zero means not entitled; absence means
685-
unrestricted. This is the per-class quota scoping Kubernetes applies to storage, and it
686-
gives entitlement and a per-tenant ceiling in one object. When present, the core refuses
705+
unrestricted. This is the per-class quota scoping Kubernetes applies to storage, and the
706+
shape community #99 uses for GPU budgets; it gives entitlement and a per-tenant ceiling
707+
in one object. When present, the core refuses
687708
a claim over the limit with a condition, and the reference admission policy enforces the
688709
same bound synchronously. The object's shape is open (*Open questions*). The distribution
689710
writes it, not the tenant. In Cozystack the `Tenant` object is the source and the tenant
@@ -715,7 +736,16 @@ chart the renderer; a brokered deployment (*User-facing changes*) uses it to exp
715736
- **Backend lacks `Pin`** → the provisioner refuses claims of that class and reports it on
716737
the claim. There is no capability registry for admission to consult.
717738
- **Adopted address released provider-side** → `IPAddress` goes `Lost`. It is not
718-
reallocated.
739+
reallocated. The claim reports `Lost`, and the address keeps its `claimRef` and its
740+
entry in `status.addresses` until an admin deletes the `IPAddress` or restores the
741+
provider-side reservation; the claim then rebinds.
742+
- **Service names a claim but the driver cannot serve it** (not `type: LoadBalancer`, or a
743+
`loadBalancerClass` the backend ignores) → refused with an event before the hold is
744+
released (§5). The address stays held.
745+
- **Two default classes, or two auto-claim classes** → claims with an empty `className`
746+
stay `Pending` with `MultipleDefaultClasses`; auto-claim does nothing and emits a
747+
Warning event on the Service. A CRD schema cannot validate uniqueness across objects;
748+
Kubernetes treats duplicate default `StorageClass`es the same way.
719749
- **Namespace with claims deleted while the core is down** → the claim finalizer holds the
720750
namespace until the core returns, as PVC protection does. No address leaks; the deletion
721751
waits.
@@ -748,9 +778,10 @@ chart the renderer; a brokered deployment (*User-facing changes*) uses it to exp
748778

749779
Sequencing is open:
750780

751-
1. CRDs, core controller, the MetalLB provisioner, and the admission policy. All exist
752-
(*Implementation status*); the policy is the driver's opt-in template. The §5
753-
`loadBalancerClass` check and the held-before-minted rule of §6 complete this phase.
781+
1. CRDs, core controller, the MetalLB provisioner, and the admission policy. The
782+
controllers exist; the policy is in an open PR (*Implementation status*). The §5
783+
`loadBalancerClass` and serviceability checks and the held-before-minted rule of §6
784+
complete this phase.
754785
2. Gateway as an association target (§5), with `Gateway.spec.addresses` fenced. The
755786
accepted external-database-exposure proposal puts a tenant's database traffic on the
756787
tenant Gateway's single address, so this is the consumer tenants meet first. Which

‎design-proposals/ip-address-claims/decisions/0001-the-backend-allocates-and-the-ledger-records.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,11 @@ the placeholder, pin the workload's Service.
5656

5757
- A reserved, unattached address cannot be taken by another Service. Admission and
5858
conflict detection become defence in depth. Proposal §6 is written around this.
59-
- One placeholder Service, with a ClusterIP, per held address.
60-
- The handoff is not atomic. Between deleting the placeholder and pinning the workload's
61-
Service the address is unheld for one reconcile interval. The admission policy covers
62-
that window.
59+
- One placeholder Service per held address, each with a ClusterIP. The number of
60+
reserved addresses is therefore bounded by the Service CIDR, not by the external pool.
61+
- The handoff is not atomic. Between deleting the placeholder and the first successful
62+
pin the address is unheld, and because `associatedTo` is already set, a failed pin or a
63+
driver restart does not re-arm the hold. The admission policy covers that window.
6364
- MetalLB keeps an assignment until the Service is deleted or re-addressed;
6465
`autoAssign: false` gates only new allocation (observed on a live cluster,
6566
[design §5](https://github.com/cozystack/metallb-iad/blob/main/docs/design.md#5-association-the-gap-handoff)).

0 commit comments

Comments
 (0)