You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a07dd3e
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: design-proposals/ip-address-claims/README.md
+43-12Lines changed: 43 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,9 +121,10 @@ Phase 1 of *Rollout* exists under the Cozystack organisation:
121
121
(cozystack/address-controller#7).
122
122
-**[metallb-iad](https://github.com/cozystack/metallb-iad)**: the reference driver for
123
123
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.
127
128
-**cozystack/cozystack#3382** packages both as optional system packages, with tenant RBAC
128
129
on claims and a distribution-specific admission policy. The driver's policy is the
129
130
reference; a distribution may disable it and ship its own.
@@ -138,7 +139,8 @@ cozyplane, an address survived delete-and-rebind and stayed reachable.
138
139
This tests the association seam only. The allocation seam, a second provisioner, is
139
140
untested (*Rollout*).
140
141
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
142
144
only the families a Service carries (§2); conditions on `IPAddress` (§2) and the
143
145
`Associated` condition on a claim (§5); per-class conflict adjudication (§8); the
144
146
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
422
424
Service sets the field at creation; a controller that creates the Service and names the
423
425
claim reads the class first.
424
426
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
+
425
435
**Detaching.** When the annotation is removed, the driver withdraws its pin, clears
426
436
`associatedTo`, and holds the address again. The `IPAddress` stays `Bound` to its claim:
427
437
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
470
480
with the Service's name in the Service's namespace, owned by the Service, and writes the
471
481
§5 annotation on the Service. The driver associates as usual. A Service can name a class
472
482
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.
474
488
475
489
Two rules follow:
476
490
@@ -492,7 +506,9 @@ disagree with `status.loadBalancer` briefly. The design accepts eventual consist
492
506
Two gaps remain with holders in place:
493
507
494
508
- **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.
496
512
- **Annotation writers.** With the pool at `autoAssign: false`, a plain Service receives a
497
513
reserved address only by naming the pool or pinning the address. Layer 1 gates that
498
514
write; layer 2 detects it.
@@ -512,6 +528,10 @@ range moved into a class must leave its old pool first.
512
528
not stop a Service from naming the pool (`metallb.io/address-pool`) or pinning an address
513
529
(`metallb.io/loadBalancerIPs`); §8 and *Security* cover that.
514
530
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
+
515
535
### 8. How this rides real allocators
516
536
517
537
No pool layout guarantees a reservation. A Service can name the reserved pool or pin an
@@ -682,8 +702,9 @@ closes the gap:
682
702
683
703
The data belongs in an optional entitlement object in the core: per namespace, per class,
684
704
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
687
708
a claim over the limit with a condition, and the reference admission policy enforces the
688
709
same bound synchronously. The object's shape is open (*Open questions*). The distribution
689
710
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
715
736
- **Backend lacks `Pin`** → the provisioner refuses claims of that class and reports it on
716
737
the claim. There is no capability registry for admission to consult.
717
738
- **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.
719
749
- **Namespace with claims deleted while the core is down** → the claim finalizer holds the
720
750
namespace until the core returns, as PVC protection does. No address leaks; the deletion
721
751
waits.
@@ -748,9 +778,10 @@ chart the renderer; a brokered deployment (*User-facing changes*) uses it to exp
748
778
749
779
Sequencing is open:
750
780
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.
754
785
2. Gateway as an association target (§5), with `Gateway.spec.addresses` fenced. The
755
786
accepted external-database-exposure proposal puts a tenant's database traffic on the
756
787
tenant Gateway's single address, so this is the consumer tenants meet first. Which
0 commit comments