Skip to content

Commit e4484b3

Browse files
authored
Merge pull request #11 from cozystack/feat/release-delay
Return Released addresses to the pool after a class's releaseDelay
2 parents 7e24ca1 + fd2a67e commit e4484b3

12 files changed

Lines changed: 275 additions & 15 deletions

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@ claim as a `Released` `IPAddress`.
3535
`IPAddress` and reports both in `status.addresses`.
3636
- **Address**: `Pending` → `Available` (no `claimRef`) → `Bound` →
3737
`Released` (claim deleted under `Retain`; not reusable until an admin
38-
clears `spec.claimRef`, at which point it is `Available` again). `Conflict`
38+
clears `spec.claimRef`, or the class's `spec.releaseDelay` elapses, at
39+
which point it is `Available` again; an address annotated
40+
`ipaddress.local.sdn.cozystack.io/held: "true"` waits for the admin). `Conflict`
3941
and `Lost` are driver-owned phases; the core controller treats them as
4042
sticky.
4143

‎api/v1alpha1/ipaddressclass_types.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,14 @@ type IPAddressClassSpec struct {
5353
// +kubebuilder:default=Retain
5454
ReclaimPolicy ReclaimPolicy `json:"reclaimPolicy,omitempty"`
5555

56+
// releaseDelay, under reclaimPolicy Retain, returns a Released address
57+
// of this class to Available once it has been Released this long: the
58+
// core controller clears its claimRef. Unset keeps a Released address
59+
// until an admin clears it. An address annotated
60+
// ipaddress.local.sdn.cozystack.io/held: "true" is exempt.
61+
// +optional
62+
ReleaseDelay *metav1.Duration `json:"releaseDelay,omitempty"`
63+
5664
// parameters is an opaque, driver-specific configuration blob (for
5765
// example the address ranges to carve from). The core controller never
5866
// interprets it.

‎api/v1alpha1/well_known.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ package v1alpha1
2020
// Together with the CRD schemas these constants are the contract between the
2121
// core controller and the per-class drivers.
2222
const (
23+
// AnnotationTrue is the value that turns on a boolean annotation of
24+
// this group, such as IsDefaultClassAnnotation.
25+
AnnotationTrue = "true"
26+
2327
// IsDefaultClassAnnotation marks an IPAddressClass as the class for
2428
// claims that do not name one. Value must be "true". The analogue of
2529
// storageclass.kubernetes.io/is-default-class.
@@ -55,6 +59,11 @@ const (
5559
// own bookkeeping, such as reservation placeholders.
5660
ServiceAutoClaimAnnotation = "local.sdn.cozystack.io/auto-claim"
5761

62+
// HeldAnnotation set to "true" on an IPAddress exempts it from its
63+
// class's releaseDelay: a Released address stays Released until an
64+
// admin clears its claimRef.
65+
HeldAnnotation = "ipaddress.local.sdn.cozystack.io/held"
66+
5867
// ClaimProtectionFinalizer is placed on every IPAddressClaim by the
5968
// core controller so that claim deletion runs the reclaim flow for the
6069
// bound addresses before the claim disappears.
@@ -89,6 +98,12 @@ const (
8998
ReasonWaitingForProvisioning = "WaitingForProvisioning"
9099
ReasonAddressLost = "AddressLost"
91100

101+
// Reasons of the Bound condition on an IPAddress, which the core sets
102+
// with its phase; its lastTransitionTime dates the last change.
103+
ReasonAvailable = "Available"
104+
ReasonReleased = "Released"
105+
ReasonPending = "Pending"
106+
92107
// ReasonClassInUse is recorded on a deleted class that still has
93108
// addresses.
94109
ReasonClassInUse = "ClassInUse"

‎api/v1alpha1/zz_generated.deepcopy.go‎

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎chart/address-controller/crds/local.sdn.cozystack.io_ipaddressclasses.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,14 @@ spec:
8080
- Retain
8181
- Delete
8282
type: string
83+
releaseDelay:
84+
description: |-
85+
releaseDelay, under reclaimPolicy Retain, returns a Released address
86+
of this class to Available once it has been Released this long: the
87+
core controller clears its claimRef. Unset keeps a Released address
88+
until an admin clears it. An address annotated
89+
ipaddress.local.sdn.cozystack.io/held: "true" is exempt.
90+
type: string
8391
required:
8492
- provisioner
8593
type: object

‎docs/design.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -271,10 +271,10 @@ State machine (core-owned transitions solid, driver-owned dashed):
271271

272272
```
273273
(new) ──► Pending ──► Available ◄────────────────┐
274-
(invalid │ │ ▲ │ admin clears
274+
(invalid │ │ ▲ │ admin clears claimRef,
275275
address │ core matches / driver │ claimRef
276276
stays │ pre-binds + core accepts │
277-
Pending) │ ▼ │ │
277+
Pending) │ ▼ │ │ or releaseDelay elapses
278278
│ Bound ───────────────► Released
279279
│ ┆ claim deleted │
280280
│ ┆ (Retain) │ (Delete: object
@@ -301,7 +301,8 @@ Each pass:
301301
5. **Unbound.** No `claimRef` → `Available`. This single rule is also the
302302
recycling path: an admin clears the `claimRef` of a `Released` address
303303
and it becomes matchable again — the deliberate, manual step PV
304-
semantics prescribe for `Retain`.
304+
semantics prescribe for `Retain`. A class may automate the step with
305+
`spec.releaseDelay` (step 7).
305306
6. **Bound.** With a `claimRef`:
306307
- claim exists, UID matches → `Bound`;
307308
- claim exists, `claimRef.uid` empty → wait (the claim reconciler is
@@ -313,6 +314,16 @@ Each pass:
313314
`Released`). This duplicates the claim-side flow on purpose: reclaim
314315
must happen even if the claim vanished without its finalizer running
315316
(e.g. the finalizer was force-removed).
317+
7. **Release delay.** A `Released` address of a class with
318+
`spec.releaseDelay` has its `claimRef` cleared once the delay has passed
319+
since it was released, and step 5 makes it `Available`. The release time
320+
is the `lastTransitionTime` of the address's `Bound` condition, which
321+
the core sets with every phase it owns (`True` for `Bound`; `False` with
322+
reason `Available`, `Released` or `Pending` otherwise). An address
323+
annotated `ipaddress.local.sdn.cozystack.io/held: "true"` is exempt and
324+
stays `Released` until an admin acts. An address `Released` before this
325+
condition existed is dated from the first pass that sets it. Changing a
326+
class's delay re-evaluates its `Released` addresses.
316327

317328
## 6. The reclaim flow (claim deletion)
318329

‎internal/controller/ipaddress_controller.go‎

Lines changed: 91 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@ package controller
1818

1919
import (
2020
"context"
21+
"time"
2122

2223
apierrors "k8s.io/apimachinery/pkg/api/errors"
24+
"k8s.io/apimachinery/pkg/api/meta"
25+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
2326
"k8s.io/apimachinery/pkg/runtime"
2427
"k8s.io/apimachinery/pkg/types"
2528
"k8s.io/client-go/tools/record"
@@ -42,12 +45,15 @@ type IPAddressReconciler struct {
4245
client.Client
4346
Scheme *runtime.Scheme
4447
Recorder record.EventRecorder
48+
// Now returns the current time; nil means time.Now.
49+
Now func() time.Time
4550
}
4651

4752
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddresses,verbs=get;list;watch;update;patch;delete
4853
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddresses/status,verbs=get;update;patch
4954
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddresses/finalizers,verbs=update
5055
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddressclaims,verbs=get;list;watch
56+
// +kubebuilder:rbac:groups=local.sdn.cozystack.io,resources=ipaddressclasses,verbs=get;list;watch
5157
// +kubebuilder:rbac:groups="",resources=events,verbs=create;patch
5258

5359
// Reconcile drives an IPAddress's phase bookkeeping.
@@ -95,9 +101,13 @@ func (r *IPAddressReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
95101

96102
switch {
97103
case claim == nil:
98-
// The claim is gone but the claim-side reclaim never ran (stale
99-
// UID, or the claim disappeared without the finalizer flow).
100-
return ctrl.Result{}, r.reclaim(ctx, addr)
104+
// The claim is gone: reclaim it, unless the claim-side flow already
105+
// did (a stale UID, or a claim that vanished without its
106+
// finalizer), and then count down a Released address's delay.
107+
if err := r.reclaim(ctx, addr); err != nil {
108+
return ctrl.Result{}, err
109+
}
110+
return r.releaseAfterDelay(ctx, addr)
101111
case !claim.DeletionTimestamp.IsZero():
102112
// The claim-side flow owns the transition; nothing to do here.
103113
return ctrl.Result{}, nil
@@ -170,13 +180,88 @@ func (r *IPAddressReconciler) reclaim(ctx context.Context, addr *localv1alpha1.I
170180
}
171181

172182
func (r *IPAddressReconciler) setPhase(ctx context.Context, addr *localv1alpha1.IPAddress, phase localv1alpha1.IPAddressPhase) error {
173-
if addr.Status.Phase == phase {
183+
if !markPhase(addr, phase) {
174184
return nil
175185
}
176-
addr.Status.Phase = phase
177186
return r.Status().Update(ctx, addr)
178187
}
179188

189+
// releaseAfterDelay returns a Released address to the pool once its
190+
// class's releaseDelay has passed since it was Released, by clearing its
191+
// claimRef; the next pass makes it Available. An address annotated held,
192+
// or of a class without a delay, is left alone.
193+
func (r *IPAddressReconciler) releaseAfterDelay(ctx context.Context, addr *localv1alpha1.IPAddress) (ctrl.Result, error) {
194+
if addr.Status.Phase != localv1alpha1.IPAddressReleased || addr.Annotations[localv1alpha1.HeldAnnotation] == localv1alpha1.AnnotationTrue {
195+
return ctrl.Result{}, nil
196+
}
197+
class := &localv1alpha1.IPAddressClass{}
198+
if err := r.Get(ctx, types.NamespacedName{Name: addr.Spec.ClassName}, class); err != nil {
199+
return ctrl.Result{}, client.IgnoreNotFound(err)
200+
}
201+
if class.Spec.ReleaseDelay == nil || class.Spec.ReleaseDelay.Duration <= 0 {
202+
return ctrl.Result{}, nil
203+
}
204+
released := meta.FindStatusCondition(addr.Status.Conditions, localv1alpha1.ConditionBound)
205+
if released == nil || released.Reason != localv1alpha1.ReasonReleased {
206+
return ctrl.Result{}, nil
207+
}
208+
now := time.Now
209+
if r.Now != nil {
210+
now = r.Now
211+
}
212+
if remaining := released.LastTransitionTime.Add(class.Spec.ReleaseDelay.Duration).Sub(now()); remaining > 0 {
213+
return ctrl.Result{RequeueAfter: remaining}, nil
214+
}
215+
ref := addr.Spec.ClaimRef
216+
addr.Spec.ClaimRef = nil
217+
if err := r.Update(ctx, addr); err != nil {
218+
return ctrl.Result{}, err
219+
}
220+
r.Recorder.Eventf(addr, "Normal", "ReleaseDelayElapsed",
221+
"released by claim %s/%s for %s; returned to the pool", ref.Namespace, ref.Name, class.Spec.ReleaseDelay.Duration)
222+
return ctrl.Result{}, nil
223+
}
224+
225+
// markPhase sets a core-owned phase on the in-memory address together with
226+
// its Bound condition, whose lastTransitionTime then dates the change. It
227+
// reports whether anything changed.
228+
func markPhase(addr *localv1alpha1.IPAddress, phase localv1alpha1.IPAddressPhase) bool {
229+
cond := metav1.Condition{
230+
Type: localv1alpha1.ConditionBound,
231+
Status: metav1.ConditionFalse,
232+
ObservedGeneration: addr.Generation,
233+
}
234+
switch phase {
235+
case localv1alpha1.IPAddressBound:
236+
cond.Status, cond.Reason, cond.Message = metav1.ConditionTrue, localv1alpha1.ReasonBound, "bound to its claim"
237+
case localv1alpha1.IPAddressReleased:
238+
cond.Reason, cond.Message = localv1alpha1.ReasonReleased, "its claim was deleted under reclaimPolicy Retain"
239+
case localv1alpha1.IPAddressAvailable:
240+
cond.Reason, cond.Message = localv1alpha1.ReasonAvailable, "bound to no claim"
241+
default:
242+
cond.Reason, cond.Message = localv1alpha1.ReasonPending, "spec.address does not parse"
243+
}
244+
changed := addr.Status.Phase != phase
245+
addr.Status.Phase = phase
246+
return meta.SetStatusCondition(&addr.Status.Conditions, cond) || changed
247+
}
248+
249+
// releasedAddressesForClass maps a class event to its Released addresses,
250+
// so a changed releaseDelay takes effect.
251+
func (r *IPAddressReconciler) releasedAddressesForClass(ctx context.Context, o client.Object) []reconcile.Request {
252+
list := &localv1alpha1.IPAddressList{}
253+
if err := r.List(ctx, list, client.MatchingFields{IPAddressClassNameIndex: o.GetName()}); err != nil {
254+
return nil
255+
}
256+
var reqs []reconcile.Request
257+
for _, addr := range list.Items {
258+
if addr.Status.Phase == localv1alpha1.IPAddressReleased {
259+
reqs = append(reqs, reconcile.Request{NamespacedName: types.NamespacedName{Name: addr.Name}})
260+
}
261+
}
262+
return reqs
263+
}
264+
180265
// addressesForClaim maps a claim event to the addresses bound to it, so
181266
// claim deletion and rebinding propagate promptly.
182267
func (r *IPAddressReconciler) addressesForClaim(ctx context.Context, o client.Object) []reconcile.Request {
@@ -198,6 +283,7 @@ func (r *IPAddressReconciler) SetupWithManager(mgr ctrl.Manager) error {
198283
return ctrl.NewControllerManagedBy(mgr).
199284
For(&localv1alpha1.IPAddress{}).
200285
Watches(&localv1alpha1.IPAddressClaim{}, handler.EnqueueRequestsFromMapFunc(r.addressesForClaim)).
286+
Watches(&localv1alpha1.IPAddressClass{}, handler.EnqueueRequestsFromMapFunc(r.releasedAddressesForClass)).
201287
Named("ipaddress").
202288
Complete(r)
203289
}

‎internal/controller/ipaddressclaim_controller.go‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -166,8 +166,7 @@ func (r *IPAddressClaimReconciler) finalizeClaim(ctx context.Context, claim *loc
166166
case addr.Status.Phase == localv1alpha1.IPAddressConflict || addr.Status.Phase == localv1alpha1.IPAddressLost:
167167
// Conflict and Lost belong to the driver and stay as recorded.
168168
default: // Retain
169-
if addr.Status.Phase != localv1alpha1.IPAddressReleased {
170-
addr.Status.Phase = localv1alpha1.IPAddressReleased
169+
if markPhase(addr, localv1alpha1.IPAddressReleased) {
171170
if err := r.Status().Update(ctx, addr); err != nil {
172171
return err
173172
}
@@ -241,7 +240,7 @@ func (r *IPAddressClaimReconciler) defaultClassName(ctx context.Context, claim *
241240
classes.Items = slices.DeleteFunc(classes.Items, classDeleting)
242241
var defaults []string
243242
for _, c := range classes.Items {
244-
if c.Annotations[localv1alpha1.IsDefaultClassAnnotation] == "true" {
243+
if c.Annotations[localv1alpha1.IsDefaultClassAnnotation] == localv1alpha1.AnnotationTrue {
245244
defaults = append(defaults, c.Name)
246245
}
247246
}

‎internal/controller/ipaddressclaim_controller_test.go‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ func publicClass(annotations map[string]string) *localv1alpha1.IPAddressClass {
113113
}
114114

115115
func defaultClass() *localv1alpha1.IPAddressClass {
116-
return publicClass(map[string]string{localv1alpha1.IsDefaultClassAnnotation: "true"})
116+
return publicClass(map[string]string{localv1alpha1.IsDefaultClassAnnotation: localv1alpha1.AnnotationTrue})
117117
}
118118

119119
func pendingClaim(className string) *localv1alpha1.IPAddressClaim {
@@ -342,6 +342,9 @@ func TestClaimDeletionRetainReleasesAddress(t *testing.T) {
342342
if got.Spec.ClaimRef == nil {
343343
t.Error("claimRef cleared on Retain; it must survive until an admin clears it")
344344
}
345+
if cond := meta.FindStatusCondition(got.Status.Conditions, localv1alpha1.ConditionBound); cond == nil || cond.Reason != localv1alpha1.ReasonReleased {
346+
t.Errorf("Bound condition = %+v, want reason Released to date the release", cond)
347+
}
345348
}
346349

347350
func TestClaimDeletionDeletePolicyDeletesAddress(t *testing.T) {

0 commit comments

Comments
 (0)