📝 docs(controller): document cluster-scope GVK backstop and upgrade impact - #305
Merged
Conversation
…mpact PR #304 makes the KollectClusterTarget reconciler re-check KollectClusterScope `allowedGVKs` after the profile loads, and degrades with `ScopeGVKDenied`. That is a new user-visible condition reason on a kind whose reference page did not list it, and it is a behaviour change an operator can be surprised by: An existing, collecting ClusterTarget whose profile `targetGVK` sits outside a non-empty `allowedGVKs` now unregisters its informers and goes Degraded on the first reconcile after upgrade. Reaching that state needs no bug — admission only runs when the object is written, so every target admitted before the ceiling was created or tightened is in the affected set. - kollectclustertarget.md: `ScopeGVKDenied` and `ScopeNamespaceDenied` rows in the Degraded table (the latter was already reachable and undocumented), the two admission denials the fix adds, and the post-upgrade symptom. - kollectclusterscope.md: an Enforcement section stating which stage checks what, so the reconcile backstop ADR-0207 always specified is visible on the ceiling's own page. Includes the ClusterInventory sink reasons for completeness. - upgrading.md: a pre-upgrade audit and post-upgrade triage for the affected set, under the existing behaviour-changes section. - troubleshooting.md: the two scope reasons applied to Target *and* ClusterTarget; they named only the namespaced kind and KollectScope. Docs-only; no version invented for the note, which says "after v0.18.0". Gates: lint:markdown 0 issues (148 files), scrub ok. Requires #304 to merge first, or the reconcile column of the enforcement table describes code that is not on main yet.
konih
force-pushed
the
docs/clustertarget-scope-gvk-notes
branch
from
August 18, 2026 09:18
fa143a5 to
9b0036e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs follow-up to #304. Merge #304 first — the reconcile column of the new enforcement table describes code that only exists once that PR lands.
#304 adds a reconcile-time
allowedGVKscheck that degrades withScopeGVKDenied. That reason was not on the KollectClusterTarget reference page, and the change has an upgrade impact worth stating: an existing, collecting ClusterTarget whose profiletargetGVKsits outside a non-emptyallowedGVKsunregisters its informers and goes Degraded on the first reconcile after upgrade. No bug is needed to reach that state — admission only runs when the object is written, so every target admitted before the ceiling was created or tightened is affected.kollectclustertarget.md—ScopeGVKDeniedandScopeNamespaceDeniedrows (the latter was already reachable and undocumented), the two admission denials 🐛 fix(webhook): enforce cluster-scope when the profile is missing #304 adds, and the post-upgrade symptom.kollectclusterscope.md— an Enforcement section: which stage checks what, including the ClusterInventory sink reasons.upgrading.md— pre-upgrade audit and post-upgrade triage, under the existing behaviour-changes section. No version invented; it says "after v0.18.0".troubleshooting.md— the two scope reasons applied to ClusterTarget as well as Target.Deliberately makes no claim about when a ceiling edit takes effect, so it stays accurate whether or not the KollectClusterScope watch lands.
Gates:
task lint:markdown0 issues across 148 files,task scrubok. Docs-only.