Skip to content

Commit 7073a2a

Browse files
sourcehawkclaude
andauthored
feat(component): add DeleteOnlyIfOwned to keep objects the owner does not own (#239)
* feat(component): add DeleteOnlyIfOwned to keep objects the owner does not own A gated-off resource was deleted by name, so an object a user created under the same name was deleted too. With DeleteOnlyIfOwned, a deletion reads the live object and deletes it only when it carries an owner reference with the owner's UID. The delete carries UID and resourceVersion preconditions. An object without the reference, or one that changed after the read, is kept and logged, and the reconcile does not fail. The option covers Delete, DeleteWhen, GatedBy, a disabled component feature gate and DeleteOnSuspend. It is a build error with ReadOnly or Unowned. Closes #233 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(component): keep an unowned object on delete-on-suspend With DeleteOnlyIfOwned and DeleteOnSuspend, the suspension apply set the owner reference on a user-created object, and the delete after it then found the object owned and deleted it. The suspension now checks the owner reference before Suspend and the apply, and an object without it counts as suspended with no write. The read goes through the API reader when set, so a stale cache that still shows an earlier owned object does not let the apply take over a new one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(component): read suspension ownership into an empty object The delete-on-suspend existence check read the live object into a copy of the desired object. The ownership check then depended on the decoder clearing ownerReferences that the copy carried from an earlier apply. The read now goes into an empty object of the same type, as observeController does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(component): bind the suspension apply to the ownership read With DeleteOnlyIfOwned and DeleteOnSuspend, an object that was replaced or disowned between the ownership read and the suspension apply was taken over by the apply and then deleted. The suspension apply now carries the observed resourceVersion, so the API server rejects it when the object changed. The resource then reports Suspending, the object is not written, and the reconcile does not fail. The deleteResources doc now says that an entry left in place is not an error, which the skip paths already did. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(component): cover a delete conflict with both ownership options Add a test for a precondition conflict on the delete when DeleteOnlyIfOwned and BlockOnForeignController are both set. The reconcile does not fail and the object is kept. BlockOnForeignController alone still fails on that conflict, so the combined case needs its own test. Move the owner reference check of the delete and suspension paths into one ownedBy helper. Split the DeleteOnlyIfOwned GoDoc into paragraphs, and give the suspension apply comment a subject. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent bca1bba commit 7073a2a

15 files changed

Lines changed: 801 additions & 54 deletions

File tree

‎docs/component.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ be passed without a guard.
6666
| `component.BlockOnAbsence()` | Read-only only: a NotFound records a blocked status and short-circuits the remaining resources |
6767
| `component.IgnoreIfAbsent()` | Read-only only: a NotFound is silently ignored and last-known state is preserved |
6868
| `component.BlockOnForeignController()` | Managed only: records a blocked status that names the owner whose controller reference is on the live object, then skips the apply and the remaining resources |
69+
| `component.DeleteOnlyIfOwned()` | Managed only: a deletion removes the live object only when it carries an owner reference to the owner; any other object is left in place |
6970
| `component.SuppressGraceInconsistencyWarning()` | Suppresses the grace/convergence inconsistency warning |
7071

7172
A read-only resource is not owned by the component, so it is never deleted. `ReadOnly()` is mutually exclusive with
@@ -105,6 +106,36 @@ A delete of an object that the read found safe carries the observed UID and reso
105106
owner claims the object between the read and the delete, the delete fails and the next reconcile reads the object again.
106107
The option requires a managed resource. A combination with `ReadOnly()` is a build error.
107108

109+
`DeleteOnlyIfOwned()` protects an object that the component did not create from a deletion. Without it, every deletion
110+
path removes the object by name, whoever created it. The only exception is an object that another owner controls, which
111+
`BlockOnForeignController()` keeps. Use the option when the resource name is one that a user can also create by hand.
112+
For example, a component registers `<name>-app` as a ServiceAccount behind `GatedBy()`. When the gate is off and the
113+
user created their own `<name>-app`, the option keeps the object of the user.
114+
115+
When `Delete()`, `DeleteWhen()`, `GatedBy()`, a disabled component feature gate, or a suspension with
116+
`DeleteOnSuspend()` asks for a deletion, the component first reads the live object, through `ReconcileContext.APIReader`
117+
when it is set and `ReconcileContext.Client` otherwise. The component deletes the object only when the object has an
118+
owner reference with the UID of the owner. This reference does not have to be the controller reference. The component
119+
sets this reference on each object that it applies, with two exceptions: an `Unowned()` resource, and a cluster-scoped
120+
resource of a namespace-scoped owner. The option never deletes an object of the second kind, so do not use it there. If
121+
the object does not have the reference, the component does not write to the object and records no `ResourceDeleted`
122+
event. It logs the skip, and the reconcile does not fail. The resource does not contribute to the component condition.
123+
As with a deletion, a disabled component feature gate reports `Disabled`. During a suspension with `DeleteOnSuspend()`,
124+
the component also skips the suspension apply for such an object, because that apply would set the owner reference. The
125+
resource counts as suspended. While no deletion is asked for, the option has no effect.
126+
127+
The delete carries the observed UID and resourceVersion as preconditions. If the object changes, or a different object
128+
takes the name, between the read and the delete, the API server rejects the delete with a conflict. The component then
129+
keeps the object, logs the skip, and does not fail the reconcile. The next reconcile reads the object again. A
130+
suspension with `DeleteOnSuspend()` binds its apply to the read in the same way, through the observed resourceVersion.
131+
If the object changes between the read and that apply, the API server rejects the apply. The component does not write
132+
the object, the resource reports `Suspending`, and the reconcile does not fail.
133+
134+
The option composes with `BlockOnForeignController()`. With both options, the component keeps an object that another
135+
owner controls, even when the object also references this owner. A conflict on the delete then does not fail the
136+
reconcile. `DeleteOnlyIfOwned()` requires a managed resource that carries the owner reference. A combination with
137+
`ReadOnly()` or `Unowned()` is a build error.
138+
108139
Options compose. Gate a resource and exclude it from health aggregation in one call:
109140

110141
```go

‎docs/guidelines.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -701,10 +701,13 @@ comp, _ := component.NewComponentBuilder().
701701
Build()
702702
```
703703

704-
A disabled `GatedBy` gate deletes the resource on the next reconcile. For an optional resource the component does
705-
**not** own (a read-only Secret reference behind an optional spec field), use `IncludeWhen`, which omits the resource
706-
without ever deleting it. The [IncludeWhen vs. GatedBy](component.md#includewhen-vs-gatedby) section covers the
707-
distinction.
704+
A disabled `GatedBy` gate deletes the resource on the next reconcile. The delete is by name, so it also removes an
705+
object that a user created under that name. If users can create an object with the same name, for example a
706+
ServiceAccount that a user brings instead of the one the operator makes, also register the resource with
707+
[`component.DeleteOnlyIfOwned()`](component.md#resource-registration-options). The component then deletes only an object
708+
that carries the owner reference of the owner. For an optional resource the component does **not** own (a read-only
709+
Secret reference behind an optional spec field), use `IncludeWhen`, which omits the resource without ever deleting it.
710+
The [IncludeWhen vs. GatedBy](component.md#includewhen-vs-gatedby) section covers the distinction.
708711

709712
## Provide a User-Override Escape Hatch as the Last Mutation
710713

‎pkg/component/create.go‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,24 @@ import (
2121
"sigs.k8s.io/controller-runtime/pkg/log"
2222
)
2323

24+
// applyConfig holds configuration for an applyResources call.
25+
type applyConfig struct {
26+
resourceVersion string
27+
}
28+
29+
// applyOption is a functional option for applyResources.
30+
type applyOption func(*applyConfig)
31+
32+
// withResourceVersion makes the apply conditional: the API server rejects it
33+
// with a conflict when the live object no longer has resourceVersion, because it
34+
// changed or was replaced since it was read. An empty resourceVersion applies
35+
// unconditionally.
36+
func withResourceVersion(resourceVersion string) applyOption {
37+
return func(cfg *applyConfig) {
38+
cfg.resourceVersion = resourceVersion
39+
}
40+
}
41+
2442
// applyResource applies a single resource to the cluster using Server-Side Apply and
2543
// collects its converging status. It returns the converging result (nil for static
2644
// resources with no status interface) and any error encountered.
@@ -30,7 +48,7 @@ import (
3048
// status-collection sequence.
3149
func applyResource(
3250
ctx context.Context, rec ReconcileContext, resource Resource, componentName string,
33-
fieldOwner client.FieldOwner, mapper meta.RESTMapper, skipOwnerRef bool,
51+
fieldOwner client.FieldOwner, mapper meta.RESTMapper, skipOwnerRef bool, resourceVersion string,
3452
) (*reconcileResult, error) {
3553
obj, err := resource.Object()
3654
if err != nil {
@@ -86,6 +104,7 @@ func applyResource(
86104
// server response (including these fields) because Mutate updates the internal
87105
// pointer and Patch writes back into the same object.
88106
clearServerFields(obj)
107+
obj.SetResourceVersion(resourceVersion)
89108

90109
// Re-assert the GVK. A Mutate implementation that assigns the whole struct
91110
// (*current = *desired) drops the TypeMeta set above, and SSA requires it.
@@ -247,15 +266,19 @@ const fieldManagerMaxLength = 128
247266
// declares.
248267
func applyResources(
249268
ctx context.Context, rec ReconcileContext, entries []reconcileEntry,
250-
componentName string, mapper meta.RESTMapper,
269+
componentName string, mapper meta.RESTMapper, opts ...applyOption,
251270
) ([]reconcileResult, error) {
271+
var cfg applyConfig
272+
for _, opt := range opts {
273+
opt(&cfg)
274+
}
252275
fieldOwner := applyFieldOwner(rec.Owner, componentName)
253276

254277
var results []reconcileResult
255278

256279
for _, entry := range entries {
257280
result, err := applyResource(
258-
ctx, rec, entry.Resource, componentName, fieldOwner, mapper, entry.Options.Unowned,
281+
ctx, rec, entry.Resource, componentName, fieldOwner, mapper, entry.Options.Unowned, cfg.resourceVersion,
259282
)
260283
if err != nil {
261284
return nil, err
@@ -343,7 +366,7 @@ func reconcileResources(
343366
result, err = readResource(ctx, rec, resource)
344367
} else {
345368
result, err = applyResource(
346-
ctx, rec, resource, componentName, fieldOwner, mapper, entry.Options.Unowned,
369+
ctx, rec, resource, componentName, fieldOwner, mapper, entry.Options.Unowned, "",
347370
)
348371
}
349372
if err != nil {

‎pkg/component/delete.go‎

Lines changed: 41 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,14 @@ func withDeletionReason(reason string) deleteOption {
4242
// live object is controlled by another owner: the object is not this
4343
// component's to delete, whichever path (a deletion flag, a disabled feature
4444
// gate, suspension) asked for it. The skip is logged with the controlling owner.
45+
// An entry registered with DeleteOnlyIfOwned is left in place, and logged,
46+
// when the live object does not carry an owner reference to the owner.
4547
//
4648
// For each successful deletion, a "ResourceDeleted" event is recorded on the owner object.
4749
// The opts parameter allows callers to customize the event message via functional options.
4850
//
49-
// Returns a joined error containing all encountered errors, or nil if all deletions
50-
// were successful or resulted in "Not Found" errors.
51+
// Returns the errors of all entries joined, or nil when no entry failed; an
52+
// entry left in place is not an error.
5153
func deleteResources(
5254
ctx context.Context, rec ReconcileContext, entries []reconcileEntry, opts ...deleteOption,
5355
) error {
@@ -92,22 +94,19 @@ func deleteResources(
9294
// reports whether a deletion happened. An object that is already gone is not
9395
// an error and reports false.
9496
//
95-
// For an entry registered with BlockOnForeignController the delete is bound to
96-
// what was observed: the live object is read first (through the API reader
97-
// when set), an absent object counts as deleted, an object another owner
98-
// controls is left in place and logged, and an object observed as safe is
99-
// deleted with its UID and resourceVersion as preconditions. An owner that
100-
// claims the object between the read and the delete therefore makes the delete
101-
// conflict instead of removing that owner's object; the error is returned so
102-
// the next reconcile observes the object again. Unlike a lost apply race, a
103-
// lost delete race is not repaired by the next reconcile, which is why the
104-
// delete carries the precondition and the apply does not.
97+
// For an entry registered with BlockOnForeignController or DeleteOnlyIfOwned
98+
// the delete is bound to what was observed: the live object is read first
99+
// (through the API reader when set), an absent object counts as deleted, an
100+
// object another owner controls (BlockOnForeignController) or that does not
101+
// reference the owner (DeleteOnlyIfOwned) is left in place and logged, and any
102+
// other object is deleted with its UID and resourceVersion as preconditions.
105103
func deleteEntry(
106104
ctx context.Context, rec ReconcileContext, entry reconcileEntry, object client.Object,
107105
) (bool, error) {
108106
resource := entry.Resource
107+
options := entry.Options
109108

110-
if !entry.Options.BlockOnForeignController {
109+
if !options.BlockOnForeignController && !options.DeleteOnlyIfOwned {
111110
if err := rec.Client.Delete(ctx, object); err != nil {
112111
if apierrors.IsNotFound(err) {
113112
return false, nil
@@ -124,23 +123,44 @@ func deleteEntry(
124123
if live == nil {
125124
return false, nil
126125
}
127-
if controller != nil {
126+
127+
if options.BlockOnForeignController && controller != nil {
128128
log.FromContext(ctx).Info(
129129
"skipping deletion of a resource another owner controls",
130130
"resource", resource.Identity(), "controller", controller.Kind+" "+controller.Name,
131131
)
132132
return false, nil
133133
}
134134

135+
if options.DeleteOnlyIfOwned && !ownedBy(live, rec.Owner.GetUID()) {
136+
log.FromContext(ctx).Info(
137+
"skipping deletion of a resource that does not reference the owner", "resource", resource.Identity(),
138+
)
139+
return false, nil
140+
}
141+
142+
// An owner that claims the object, or a user that replaces it, between the
143+
// read and the delete makes the delete conflict instead of removing an
144+
// object the checks above did not see. Unlike a lost apply race, a lost
145+
// delete race is not repaired by the next reconcile, which is why the
146+
// delete carries the precondition and the apply does not.
135147
uid, resourceVersion := live.GetUID(), live.GetResourceVersion()
136148
err = rec.Client.Delete(ctx, live, client.Preconditions{UID: &uid, ResourceVersion: &resourceVersion})
137-
if err != nil {
138-
if apierrors.IsNotFound(err) {
139-
return false, nil
140-
}
141-
return false, fmt.Errorf(
142-
"failed to delete resource %s as observed: %w", resource.Identity(), err,
149+
switch {
150+
case err == nil:
151+
return true, nil
152+
case apierrors.IsNotFound(err):
153+
return false, nil
154+
case options.DeleteOnlyIfOwned && apierrors.IsConflict(err):
155+
// The object changed after it was read. Leaving it is the safe outcome
156+
// and needs no retry: the next reconcile reads it again.
157+
log.FromContext(ctx).Info(
158+
"skipping deletion of a resource that changed after it was read", "resource", resource.Identity(),
143159
)
160+
return false, nil
161+
default:
162+
// BlockOnForeignController alone returns the conflict so the reconcile
163+
// fails and the object is observed again on the retry.
164+
return false, fmt.Errorf("failed to delete resource %s as observed: %w", resource.Identity(), err)
144165
}
145-
return true, nil
146166
}

0 commit comments

Comments
 (0)