Skip to content

Commit 7e24ca1

Browse files
authored
Merge pull request #10 from cozystack/feat/class-deletion-guard
Hold a deleted IPAddressClass until its addresses are gone
2 parents be1aced + db6042e commit 7e24ca1

11 files changed

Lines changed: 299 additions & 31 deletions

File tree

‎api/v1alpha1/well_known.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,12 @@ const (
6060
// bound addresses before the claim disappears.
6161
ClaimProtectionFinalizer = "local.sdn.cozystack.io/claim-protection"
6262

63+
// ClassProtectionFinalizer is placed on every IPAddressClass by the core
64+
// controller. It holds a deleted class until no IPAddress of the class
65+
// is left: drivers resolve their backend configuration through the
66+
// class to hold and pin its addresses.
67+
ClassProtectionFinalizer = "local.sdn.cozystack.io/class-protection"
68+
6369
// AddressProtectionFinalizer is placed on every IPAddress by the core
6470
// controller. It blocks deletion of an address that is still bound to a
6571
// live claim. Drivers add their own finalizer on addresses they
@@ -83,6 +89,10 @@ const (
8389
ReasonWaitingForProvisioning = "WaitingForProvisioning"
8490
ReasonAddressLost = "AddressLost"
8591

92+
// ReasonClassInUse is recorded on a deleted class that still has
93+
// addresses.
94+
ReasonClassInUse = "ClassInUse"
95+
8696
// Event reasons recorded on Services by auto-claim.
8797
ReasonAutoClaimed = "AutoClaimed"
8898
ReasonAutoClaimNameTaken = "AutoClaimNameTaken"

‎chart/address-controller/templates/role.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ rules:
5353
- local.sdn.cozystack.io
5454
resources:
5555
- ipaddressclaims/finalizers
56+
- ipaddressclasses/finalizers
5657
- ipaddresses/finalizers
5758
verbs:
5859
- update
@@ -72,6 +73,8 @@ rules:
7273
verbs:
7374
- get
7475
- list
76+
- patch
77+
- update
7578
- watch
7679
- apiGroups:
7780
- local.sdn.cozystack.io

‎cmd/main.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,14 @@ func main() {
228228
setupLog.Error(err, "unable to create controller", "controller", "IPAddressClaim")
229229
os.Exit(1)
230230
}
231+
if err = (&controller.IPAddressClassReconciler{
232+
Client: mgr.GetClient(),
233+
Scheme: mgr.GetScheme(),
234+
Recorder: mgr.GetEventRecorderFor("ipaddressclass-controller"),
235+
}).SetupWithManager(mgr); err != nil {
236+
setupLog.Error(err, "unable to create controller", "controller", "IPAddressClass")
237+
os.Exit(1)
238+
}
231239
if err = (&controller.ServiceReconciler{
232240
Client: mgr.GetClient(),
233241
Scheme: mgr.GetScheme(),

‎docs/design.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ The contract is largely a discipline about who may write which field.
148148
| `Address.status.associatedTo` | | | never | ✍ |
149149
| `Address` protection finalizer | | | ✍ | |
150150
| `Address` driver finalizer(s) | | | | ✍ |
151-
| `IPAddressClass` | | ✍ | reads | reads (incl. parameters) |
151+
| `IPAddressClass` | | ✍ | reads; ✍ protection finalizer | reads (incl. parameters) |
152152

153153
Two invariants fall out of this table:
154154

@@ -253,16 +253,17 @@ idempotent; the pass re-derives everything from the cluster state.
253253
by object name. `status.className` records the resolution when one
254254
happened this pass and is left untouched otherwise.
255255

256-
**Class deletion.** The class is load-bearing only at two moments:
257-
resolving/stamping an unbound claim, and matching or provisioning *new*
258-
bindings. Everything downstream deliberately avoids depending on it:
259-
satisfied claims skip class resolution entirely (step 5), reclaim reads
260-
the `reclaimPolicy` **copied onto each address** at provisioning time
261-
(§6), and the address reconciler never reads classes at all. So deleting
262-
an `IPAddressClass` — or restarting the controller after its deletion —
263-
leaves every existing binding, every reclaim, and all status upkeep
264-
intact; the only effect is that still-unbound claims of that class stop
265-
progressing, honestly reported as `Pending` with `ClassNotFound`.
256+
**Class deletion.** The core holds a deleted class with the
257+
`local.sdn.cozystack.io/class-protection` finalizer until no `IPAddress`
258+
of the class is left, in any phase, and records a `ClassInUse` event
259+
naming the addresses it waits for. Drivers resolve their backend
260+
configuration through the class to hold and pin its addresses, so a class
261+
must outlive them. The claim side does not depend on this: satisfied
262+
claims skip class resolution entirely (step 5), and reclaim reads the
263+
`reclaimPolicy` **copied onto each address** at provisioning time (§6). A
264+
class removed by force leaves existing bindings, reclaim and status upkeep
265+
intact; still-unbound claims of that class stay `Pending` with
266+
`ClassNotFound`.
266267

267268
## 5. The address reconciliation algorithm
268269

‎internal/controller/indexes.go‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ import (
3030
// "<namespace>/<name>" of their spec.claimRef.
3131
const IPAddressClaimRefIndex = "spec.claimRef"
3232

33+
// IPAddressClassNameIndex indexes IPAddress objects by spec.className.
34+
const IPAddressClassNameIndex = "spec.className"
35+
3336
// ClaimRefIndexKey builds the index key for a claim.
3437
func ClaimRefIndexKey(namespace, name string) string {
3538
return namespace + "/" + name
@@ -38,14 +41,27 @@ func ClaimRefIndexKey(namespace, name string) string {
3841
// SetupIndexes registers the field indexes shared by the controllers. Call
3942
// once, before setting up the controllers.
4043
func SetupIndexes(ctx context.Context, mgr ctrl.Manager) error {
41-
return mgr.GetFieldIndexer().IndexField(ctx, &localv1alpha1.IPAddress{}, IPAddressClaimRefIndex,
42-
func(o client.Object) []string {
43-
addr := o.(*localv1alpha1.IPAddress)
44-
if addr.Spec.ClaimRef == nil {
45-
return nil
46-
}
47-
return []string{ClaimRefIndexKey(addr.Spec.ClaimRef.Namespace, addr.Spec.ClaimRef.Name)}
48-
})
44+
indexer := mgr.GetFieldIndexer()
45+
if err := indexer.IndexField(ctx, &localv1alpha1.IPAddress{}, IPAddressClaimRefIndex, claimRefIndex); err != nil {
46+
return err
47+
}
48+
return indexer.IndexField(ctx, &localv1alpha1.IPAddress{}, IPAddressClassNameIndex, classNameIndex)
49+
}
50+
51+
func claimRefIndex(o client.Object) []string {
52+
addr := o.(*localv1alpha1.IPAddress)
53+
if addr.Spec.ClaimRef == nil {
54+
return nil
55+
}
56+
return []string{ClaimRefIndexKey(addr.Spec.ClaimRef.Namespace, addr.Spec.ClaimRef.Name)}
57+
}
58+
59+
func classNameIndex(o client.Object) []string {
60+
addr := o.(*localv1alpha1.IPAddress)
61+
if addr.Spec.ClassName == "" {
62+
return nil
63+
}
64+
return []string{addr.Spec.ClassName}
4965
}
5066

5167
// familyOf reports the address family of a textual IP, or "" if it does not

‎internal/controller/ipaddressclaim_controller.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,9 @@ func (r *IPAddressClaimReconciler) defaultClassName(ctx context.Context, claim *
236236
if err := r.List(ctx, classes); err != nil {
237237
return "", err
238238
}
239+
// A deleted class is held only until its addresses are gone; drawing
240+
// new claims into it would keep it from draining.
241+
classes.Items = slices.DeleteFunc(classes.Items, classDeleting)
239242
var defaults []string
240243
for _, c := range classes.Items {
241244
if c.Annotations[localv1alpha1.IsDefaultClassAnnotation] == "true" {

‎internal/controller/ipaddressclaim_controller_test.go‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import (
3636

3737
const (
3838
testClassName = "public"
39+
otherClassName = "private"
3940
testProvisioner = "metallb.drivers.local.sdn.cozystack.io"
4041
testNamespace = "tenant-a"
4142
testClaimName = "web"
@@ -59,13 +60,8 @@ func testClient(t *testing.T, objs ...client.Object) client.Client {
5960
return fake.NewClientBuilder().
6061
WithScheme(testScheme(t)).
6162
WithStatusSubresource(&localv1alpha1.IPAddress{}, &localv1alpha1.IPAddressClaim{}).
62-
WithIndex(&localv1alpha1.IPAddress{}, IPAddressClaimRefIndex, func(o client.Object) []string {
63-
addr := o.(*localv1alpha1.IPAddress)
64-
if addr.Spec.ClaimRef == nil {
65-
return nil
66-
}
67-
return []string{ClaimRefIndexKey(addr.Spec.ClaimRef.Namespace, addr.Spec.ClaimRef.Name)}
68-
}).
63+
WithIndex(&localv1alpha1.IPAddress{}, IPAddressClaimRefIndex, claimRefIndex).
64+
WithIndex(&localv1alpha1.IPAddress{}, IPAddressClassNameIndex, classNameIndex).
6965
WithObjects(objs...).
7066
Build()
7167
}
@@ -449,7 +445,7 @@ func TestLostAddressIsNotReplaced(t *testing.T) {
449445

450446
func TestClaimRefusesMismatchedPreBinding(t *testing.T) {
451447
cases := map[string]*localv1alpha1.IPAddress{
452-
"other class": preBoundAddress("203.0.113.18", "private"),
448+
"other class": preBoundAddress("203.0.113.18", otherClassName),
453449
"unrequested family": preBoundAddress("2001:db8::18", testClassName),
454450
}
455451
for name, addr := range cases {
@@ -499,7 +495,7 @@ func TestOwnedClaimDeletionSparesRefusedPreBinding(t *testing.T) {
499495
claim.OwnerReferences = []metav1.OwnerReference{{
500496
APIVersion: "v1", Kind: serviceKind, Name: "web-lb", UID: testServiceUID, Controller: new(true),
501497
}}
502-
c := testClient(t, publicClass(nil), claim, preBoundAddress("203.0.113.21", "private"))
498+
c := testClient(t, publicClass(nil), claim, preBoundAddress("203.0.113.21", otherClassName))
503499
if err := c.Delete(context.Background(), claim); err != nil {
504500
t.Fatal(err)
505501
}
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package controller
18+
19+
import (
20+
"context"
21+
"sort"
22+
23+
"k8s.io/apimachinery/pkg/runtime"
24+
"k8s.io/apimachinery/pkg/types"
25+
"k8s.io/client-go/tools/record"
26+
ctrl "sigs.k8s.io/controller-runtime"
27+
"sigs.k8s.io/controller-runtime/pkg/client"
28+
"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
29+
"sigs.k8s.io/controller-runtime/pkg/handler"
30+
"sigs.k8s.io/controller-runtime/pkg/reconcile"
31+
32+
localv1alpha1 "github.com/cozystack/address-controller/api/v1alpha1"
33+
)
34+
35+
// IPAddressClassReconciler guards class deletion: a deleted class is held
36+
// by the class-protection finalizer until no IPAddress of the class is left.
37+
type IPAddressClassReconciler struct {
38+
client.Client
39+
Scheme *runtime.Scheme
40+
Recorder record.EventRecorder
41+
}
42+
43+
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddressclasses,verbs=get;list;watch;update;patch
44+
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddressclasses/finalizers,verbs=update
45+
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddresses,verbs=get;list;watch
46+
// +kubebuilder:rbac:groups="",resources=events,verbs=create;patch
47+
48+
// Reconcile adds the protection finalizer, or releases a deleted class once
49+
// its addresses are gone.
50+
func (r *IPAddressClassReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
51+
class := &localv1alpha1.IPAddressClass{}
52+
if err := r.Get(ctx, req.NamespacedName, class); err != nil {
53+
return ctrl.Result{}, client.IgnoreNotFound(err)
54+
}
55+
56+
if class.DeletionTimestamp.IsZero() {
57+
if controllerutil.AddFinalizer(class, localv1alpha1.ClassProtectionFinalizer) {
58+
return ctrl.Result{}, r.Update(ctx, class)
59+
}
60+
return ctrl.Result{}, nil
61+
}
62+
if !controllerutil.ContainsFinalizer(class, localv1alpha1.ClassProtectionFinalizer) {
63+
return ctrl.Result{}, nil
64+
}
65+
66+
addrs := &localv1alpha1.IPAddressList{}
67+
if err := r.List(ctx, addrs, client.MatchingFields{IPAddressClassNameIndex: class.Name}); err != nil {
68+
return ctrl.Result{}, err
69+
}
70+
if len(addrs.Items) > 0 {
71+
names := make([]string, 0, len(addrs.Items))
72+
for _, addr := range addrs.Items {
73+
names = append(names, addr.Name)
74+
}
75+
sort.Strings(names)
76+
r.Recorder.Eventf(class, "Warning", localv1alpha1.ReasonClassInUse,
77+
"deletion waits for %d IPAddress(es) of this class: %v", len(names), names)
78+
return ctrl.Result{}, nil
79+
}
80+
controllerutil.RemoveFinalizer(class, localv1alpha1.ClassProtectionFinalizer)
81+
return ctrl.Result{}, r.Update(ctx, class)
82+
}
83+
84+
// classDeleting reports whether a class is being deleted.
85+
func classDeleting(c localv1alpha1.IPAddressClass) bool {
86+
return !c.DeletionTimestamp.IsZero()
87+
}
88+
89+
// classForAddress maps an IPAddress event to the address's class.
90+
func (r *IPAddressClassReconciler) classForAddress(_ context.Context, o client.Object) []reconcile.Request {
91+
addr := o.(*localv1alpha1.IPAddress)
92+
if addr.Spec.ClassName == "" {
93+
return nil
94+
}
95+
return []reconcile.Request{{NamespacedName: types.NamespacedName{Name: addr.Spec.ClassName}}}
96+
}
97+
98+
// SetupWithManager sets up the controller with the Manager.
99+
func (r *IPAddressClassReconciler) SetupWithManager(mgr ctrl.Manager) error {
100+
return ctrl.NewControllerManagedBy(mgr).
101+
For(&localv1alpha1.IPAddressClass{}).
102+
Watches(&localv1alpha1.IPAddress{}, handler.EnqueueRequestsFromMapFunc(r.classForAddress)).
103+
Named("ipaddressclass").
104+
Complete(r)
105+
}

0 commit comments

Comments
 (0)