Skip to content

add IgnoreIfAbsent for optional read-only resources #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sourcehawk wants to merge 7 commits into
base: main
Choose a base branch
from
Open

add IgnoreIfAbsent for optional read-only resources #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5073b4d
add design spec for IgnoreIfAbsent read-only resources
sourcehawk May 25, 2026
96a3db4
add implementation plan for IgnoreIfAbsent
sourcehawk May 25, 2026
b7c905e
add IgnoreIfAbsent flag to ResourceOptions
sourcehawk May 26, 2026
9f1b4ea
validate ReadOnly requirement and mutual exclusion for absence flags
sourcehawk May 26, 2026
b6e10ab
silently skip absent read-only resources flagged IgnoreIfAbsent
sourcehawk May 26, 2026
90ca854
document IgnoreIfAbsent and tightened BlockOnAbsence semantics
sourcehawk May 26, 2026
ea20300
format spec and plan with make fmt-md
sourcehawk May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions docs/component.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ Each resource is registered with a `ResourceOptions` struct that controls how th
| `ResourceOptions{ParticipationMode: ParticipationModeAuxiliary}` | The resource's health does not contribute to the component condition. The component can become Ready regardless of this resource's state. **Exception:** a blocked [guard](#guards) always contributes to the condition regardless of participation mode, because it halts the entire reconciliation pipeline |
| `ResourceOptions{SuppressGraceInconsistencyWarning: true}` | Suppresses the warning log emitted when the resource's grace handler returns Healthy while its convergence handler returns non-healthy. Use this when the inconsistency is intentional (e.g., a custom grace handler that deliberately reports Healthy for a resource that has not fully converged) |
| `ResourceOptions{ReadOnly: true, BlockOnAbsence: true}` | **Read-only with watch-driven retry**: a NotFound from the cluster is recorded as a blocked status (`waiting for <resource>`) and short-circuits the remaining resources, instead of erroring back through controller-runtime's exponential backoff. Use only when the consumer has a watch on the resource's type so the reconcile is re-enqueued when it appears |
| `ResourceOptions{ReadOnly: true, IgnoreIfAbsent: true}` | **Optional read-only**: a NotFound from the cluster is silently ignored. The entry contributes nothing to the component's conditions, no observation is recorded, and the data extractor is not invoked. Subsequent resources reconcile unchanged. Use for resources that may legitimately be absent (e.g. a referenced Secret owned by another operator) |

### Building Resource Options with Feature Gating

Expand All @@ -97,13 +98,14 @@ signature is unchanged.

**Methods:**

| Method | Effect |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `WithFeatureGate(f feature.Gate)` | Gates the resource on a feature. When disabled, the resource is deleted. |
| `When(truth bool)` | Adds a boolean condition (AND logic). If any condition is false, the resource is deleted. Calls are additive. |
| `Auxiliary()` | Sets participation mode to `Auxiliary` (resource does not affect component health). |
| `ReadOnly()` | Marks the resource as read-only. If the resource is also gated by a disabled feature, deletion takes precedence over read-only. |
| `BlockOnAbsence()` | Opts a read-only resource into guard-blocked semantics on NotFound. Only meaningful alongside `ReadOnly()`; requires a watch on the resource's type to avoid stalling until the periodic resync. |
| Method | Effect |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WithFeatureGate(f feature.Gate)` | Gates the resource on a feature. When disabled, the resource is deleted. |
| `When(truth bool)` | Adds a boolean condition (AND logic). If any condition is false, the resource is deleted. Calls are additive. |
| `Auxiliary()` | Sets participation mode to `Auxiliary` (resource does not affect component health). |
| `ReadOnly()` | Marks the resource as read-only. If the resource is also gated by a disabled feature, deletion takes precedence over read-only. |
| `BlockOnAbsence()` | Opts a read-only resource into guard-blocked semantics on NotFound. Requires `ReadOnly()` and is mutually exclusive with `IgnoreIfAbsent()`; `Build()` errors otherwise. Requires a watch on the resource's type to avoid stalling until the periodic resync. |
| `IgnoreIfAbsent()` | Opts a read-only resource into "optional" semantics: a NotFound is silently ignored, the entry is skipped, no condition or observation is reported, and the data extractor is not invoked. Requires `ReadOnly()` and is mutually exclusive with `BlockOnAbsence()`; `Build()` errors otherwise. |

For the common case of gating a resource on a single feature, use the convenience function:

Expand Down
Loading
Loading