docs(security): correct what actually blocks the C-0211 controller-scope opt-in

[devantler]

🤖 Generated by the Agentic Engineer

Why

A comment in our security-exception notes told the next reader that the mutation we rely on to close two Kubescape checks structurally cannot reach the thing the scanner grades. That was true when written and is no longer true — the capability was added later. Left as it stood, it reads as "this route is a dead end", which would send whoever picks this up next looking for a different solution that isn't needed.

The accurate position is narrower and more useful: the capability exists, it is deliberately switched off everywhere, and each namespace turns it on only alongside evidence that it worked there. Those are very different situations — one says the approach is broken, the other says there is a queue of per-namespace rollouts waiting.

What

Corrects that comment. Comment-only — the rendered output is byte-identical before and after, so nothing about the cluster changes.

Note on scope

This PR originally also opted one namespace into that rollout. A repository guard correctly rejected it: turning it on is a documented procedure — the switch, a restart of every workload in the namespace, a read-back proving the fields landed, and a watch for a specific failure mode — not a one-line change. For the namespace I picked that means restarting the cluster's storage components on production, which is not an unattended change. That commit is reverted here; the measurement behind it is recorded on #3239 so the rollout can be picked up deliberately.

Part of #3239

🤖 Generated with Claude Code

[devantler]

🤖 Generated by the Agentic Engineer

Exercised and evaluated

Both states, against a real workload. Took the live longhorn-system/longhorn-ui Deployment off prod, stripped server-side fields, and ran the policy through the Kyverno CLI (v1.19.0) twice — once with this branch's namespace labels, once with the same labels minus the new one. The namespace labels were read out of the edited file rather than retyped, so the ON case is the state this PR actually declares.

	pod fsGroupChangePolicy	container seLinuxOptions.level	pre-existing siblings
label ON	OnRootMismatch added	s0 added	runAsUser:499, runAsGroup:486, runAsNonRoot:true, seccompProfile all intact
label OFF	absent	absent	unchanged

Two controls, both fired: the OFF output is byte-identical to the input (so the flag genuinely gates), and the ON output differs from the input (so the test is not vacuous). Sibling preservation is asserted explicitly because that is the property #3580 was about — a whole-object write would have discarded runAsUser/runAsGroup here, and this fixture has them.

Validation. ksail workload validate — 602 files, 0 failures, including providers/hetzner/infrastructure/controllers/longhorn/namespace.yaml.

⚠️ kubectl kustomize k8s/clusters/prod/ is not a check on this change and I am not offering it as one: that root renders only 4 Flux Kustomization CRs and contains neither changed file. It builds clean and proves nothing here.

For the second commit, which is comment-only, I rendered k8s/bases/infrastructure/cluster-security-exceptions before and after: byte-identical at 962 lines.

What is NOT proven yet

The Kyverno CLI shows the rule produces the right mutation; it does not show helm-controller and Flux driving it onto the live cluster. That is exactly the gap #3577 fell into — every static and GitHub-side signal was green while nothing landed. So after this merges I will re-read the live stored specs and require all 11 longhorn-system workloads to carry both fields, and I will not report it as working before that read.

Scope

One namespace. observability is the natural next one but is deliberately not in this PR — 6 of its 9 workloads set fsGroup and 3 are StatefulSets with volume claim templates, so fsGroupChangePolicy is a real runtime change there rather than the inert one it is here. That deserves its own PR and its own before/after.

[devantler]

🤖 Generated by the Agentic Engineer

Correction — scope reduced, and my earlier comment overstated the finding

My first version of this PR opted longhorn-system into the controller-scope rollout, and the evaluation comment above framed it as "a rollout has been enabling the half that cannot work". tests/add-baseline-context rejected it, and it was right to. Recording what it taught, because the correction matters more than the original claim:

1. The empty inventory is deliberate, not an oversight. expected_controllers_optin="" is pinned on purpose, and the gate's own message says a namespace joins "only together with its measured post-rollout read-back". So the accurate reading is a staged rollout that has not reached stage 2 — not, as I wrote, a rollout that has been running on the wrong half. I withdraw that framing.

2. My mechanism claim was wrong. I wrote that the controller rules matching UPDATE means "Flux's next reconcile rewrites the stored spec". The procedure beside the rules says the opposite: helm-controller reapplies only on a chart or values change and excludes /spec/template from drift correction, so a labelled namespace keeps its old templates indefinitely until some writer issues an UPDATE. The label alone would have changed nothing and I would have reported a rollout that had not happened.

3. Why I am not completing it here. The documented flip is four steps: label → a template-annotation UPDATE per workload → read the stored specs back → watch every owner's write rate for the reconcile loop the same comment warns about (Coroot is named as a known candidate). For longhorn-system step 2 restarts Longhorn's manager, CSI and UI — the cluster's storage system — and step 4 needs sustained observation. That is a mutating production operation and this repo's prod access is read-only, so it is not an unattended change.

What survives, and is verified

• The measured split between the two surfaces, which is what makes the rollout worth queueing: kubescape 7/15 → 8/16 pods carrying both fields while 0 of 6 controllers do; longhorn-system 0 of 11. Recorded on security(kubescape): supply fsGroupChangePolicy and seLinuxOptions to the namespaces the security-context mutation excludes #3239.
• velero is not evidence the mutation works — it reads 2/2 because its HelmRelease supplies the fields at source. Worth knowing before anyone cites it as a baseline.
• longhorn-system is still the right namespace to flip first when someone does it deliberately: all 11 workloads are genuinely graded (Deployment:6 + DaemonSet:5 scan objects), and none sets fsGroup, so the field is inert at runtime there. kubescape is the wrong one — the operator excludes its own namespace, so its 678 scan objects contain zero of workload kind.
• The remaining commit is comment-only and rendered byte-identical.

One process note for anyone validating this area locally: ksail workload validate passes (602 files) without running this gate — it lives in the ⚖️ Validate cluster policies CI step. Local green is not sufficient here.

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai review

[coderabbitai]

@devantler I will review the changes.

Action performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[devantler]

🤖 Generated by the Agentic Engineer

Exercised and evaluated at 7c6db99f

What I found first. The previous head's rewrite ended mid-sentence at "Template-level changes
are what moved", dropping its object and the flux-system breakdown that named tofu-controller
and its removal issue. #3480 is still open, so that was a live cross-reference deleted by
accident, not stale text pruned deliberately. 7c6db99f restores the dropped wording.

The "nothing changes" claim is measured, not asserted. I rendered the base directory both
ways and compared bytes:

• with the fix and without it: 31314 B each, cmp reports identical;
• non-vacuity control — the render genuinely contains this file's resource
  (name: pod-security-mutations-unscoped appears in the output), so the comparison is not
  passing over an output that never included the change;
• sensitivity control — a deliberate semantic edit to the same file did change the render,
  proving the comparison detects a real difference rather than always reporting "identical".

Both controls fired in the expected direction, so "comment-only, byte-identical output" is a
verified property of this head rather than an inference from the diff looking like comments.

Policy gate. scripts/tests/test-add-baseline-context.sh — the gate that rejected this PR's
original label commit — passes at this head. That gate is not run by ksail workload validate, so
it is exercised directly.

Evaluated as a reader. The comment block now reads as a complete argument: the mechanism exists,
it is gated on a second label applied nowhere on purpose, and each namespace joins with its own
measured read-back. The remaining rollout is recorded on #3239, which now carries a body-level
**Blocker:** line and the blocked label so it is not re-selected for an unattended prod change.

[devantler]

🤖 Generated by the Agentic Engineer

CI is green at 7c6db99f (20 passing, 0 failing) and there are no unresolved threads. The head adds
one commit over the previously-reviewed 9677735: it restores a sentence and an issue reference that
the earlier rewrite truncated. Still comment-only — the rendered output is byte-identical, verified
by rendering the base directory both ways with a sensitivity control.

@coderabbitai review

[coderabbitai]

@devantler I will review the incremental commit at 7c6db99f.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Warning

Review limit reached

Next included review available in 3 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: 01a2f7f0-f26c-403f-9f64-0a9ac1d1c81f

📥 Commits

Reviewing files that changed from the base of the PR and between 7529ec4 and e6000ec.

📒 Files selected for processing (1)

• k8s/bases/infrastructure/cluster-security-exceptions/pod-security-mutations-unscoped.yaml

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devantler]

🤖 Generated by the Agentic Engineer

Lane progress: cr:no-gate@7c6db99f7fe330532151ef8991663c2316e8ad67. CodeRabbit was requested
first at this head (14:25Z) and refused — its command-invocation reply records
⚠️ Action not completed / Review rate limited at 14:26:01Z, and the head status agrees. That is a
service outcome, not a finding, so the loop advances one lane rather than re-asking. A later run
should resume at Codex, not spend CodeRabbit again on this head.

Green at 7c6db99f: 20 checks passing, 0 failing, 0 unresolved threads. The change is comment-only —
one YAML comment block in a Kyverno security-exception file — and the rendered output is
byte-identical before and after.

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T14:29:27.710102Z	7c6db99	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7c6db99f7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai review

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== Pull request metadata =='
gh pr view 3587 --repo devantler-tech/platform --json number,title,baseRefName,headRefName,commits,files \
  --jq '{number,title,baseRefName,headRefName,commits:[.commits[]|{oid,messageHeadline}],files:[.files[]|{path,additions,deletions}]}'

echo
echo '== Incremental commit diff =='
git show --format=fuller --find-renames --find-copies adf9609f668e276014078ecb4afef8dee1862225 -- || true

echo
echo '== Changed files on PR range =='
git diff --name-status "$(git merge-base origin/HEAD HEAD)" HEAD || true

echo
echo '== Candidate policy files =='
fd -t f -e yaml -e yml . | rg 'cluster-security-exceptions|pod-security|kyverno' || true

Length of output: 9916

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

policy='k8s/bases/infrastructure/cluster-security-exceptions/pod-security-mutations-unscoped.yaml'

echo '== Policy outline =='
ast-grep outline "$policy" --items all || true

echo
echo '== Updated comment and policy rule names =='
rg -n -A16 -B8 \
  'add-baseline-context-optin-(controllers|cronjobs)|baseline-context-controllers|residual workloads|observability and longhorn-system' \
  "$policy"

echo
echo '== Relevant test inventory and assertions =='
rg -n -A12 -B8 \
  'expected_controllers_optin|baseline-context-controllers|CronJob|cronjob|residual' \
  tests/add-baseline-context scripts/tests 2>/dev/null || true

echo
echo '== PR-wide diff against main =='
git diff --check origin/main...HEAD
git diff --find-renames --unified=30 origin/main...HEAD -- "$policy"

Length of output: 108449

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== Policy definition locations =='
rg -n -l --glob '*.yaml' --glob '*.yml' \
  '^(\s*)name:\s*add-baseline-context-optin-(controllers|cronjobs)' \
  k8s tests

echo
echo '== Rule definitions and match/precondition context =='
rg -n -A55 -B8 --glob '*.yaml' --glob '*.yml' \
  'name:\s*add-baseline-context-optin-(controllers|cronjobs)' \
  k8s

echo
echo '== References that substantiate the residual count =='
rg -n -A4 -B4 \
  '(seven|7).{0,80}(CronJob|cronjob)|(CronJob|cronjob).{0,80}(seven|7)|remaining 29|residual workloads' \
  README.md k8s tests scripts .github 2>/dev/null || true

echo
echo '== GitHub issue `#3217` and `#3239` summaries =='
gh issue view 3217 --repo devantler-tech/platform --json number,title,state,body,url,labels
gh issue view 3239 --repo devantler-tech/platform --json number,title,state,body,url,labels

Length of output: 1211

---

🏁 Script executed:

#!/bin/bash
set -u -o pipefail

echo '== Candidate add-security-context files =='
fd -t f -e yaml -e yml . k8s tests | rg 'add-security-context|security-context|mutation' || true

echo
echo '== All baseline-context rule references in repository YAML =='
rg -n -A35 -B6 --glob '*.yaml' --glob '*.yml' \
  'add-baseline-context|baseline-context-controllers' \
  k8s tests || true

echo
echo '== Residual-population references in repository =='
rg -n -A5 -B5 \
  '(seven|7).{0,100}(CronJob|cronjob)|(CronJob|cronjob).{0,100}(seven|7)|remaining 29|residual workload' \
  k8s tests scripts .github README.md 2>/dev/null || true

echo
echo '== GitHub issue `#3217` =='
gh issue view 3217 --repo devantler-tech/platform --json number,title,state,body,url,labels || true

echo
echo '== GitHub issue `#3239` =='
gh issue view 3239 --repo devantler-tech/platform --json number,title,state,body,url,labels || true

Length of output: 140689

---

@devantler I found one documentation accuracy issue.

• P2 — Include the Job case in the controller-family description.
  In k8s/bases/infrastructure/cluster-security-exceptions/pod-security-mutations-unscoped.yaml, the new text describes add-baseline-context-optin-controllers* as applying to Deployment, StatefulSet, and DaemonSet on CREATE and UPDATE. The policy also matches Job on CREATE in k8s/bases/infrastructure/cluster-policies/best-practices/add-security-context.yaml. Add the Job case, with its CREATE-only limitation. This prevents the rollout note from presenting the rule family as narrower than it is.

You are interacting with an AI system.

[devantler]

🤖 Generated by the Agentic Engineer

Resolution record — CodeRabbit P2 (comment-form, no thread): "Include the Job case in the controller-family description."

Verified valid. add-baseline-context-optin-controllers in k8s/bases/infrastructure/cluster-policies/best-practices/add-security-context.yaml has two match.any resource blocks, not one:

• Deployment / StatefulSet / DaemonSet — operations: [CREATE, UPDATE]
• Job — operations: [CREATE]

The rollout note described only the first, presenting the family as narrower than it is. Fixed in e6000eca, comment-only:

(Deployment/StatefulSet/DaemonSet on CREATE and UPDATE) → (Deployment/StatefulSet/DaemonSet on CREATE and UPDATE, Job on CREATE)

The "TWO families" count is unchanged, because Job sits inside the controllers family rather than forming a third. The separate out-of-scope reasoning further up the note — Jobs are not scanned, so the ephemeral backup and heartbeat Jobs carry no verdict — is untouched and remains accurate; this corrects what the rule matches, not what the rollout covers.

Verification: one line changed, file line count identical (157), all nine surrounding clauses asserted present after the edit, YAML re-parsed clean.

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai full review

[coderabbitai]

@devantler I will perform a full review of the current pull request state.

⚠️ Action not completed

Review rate limited.

---

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 25 minutes.

[devantler]

🤖 Generated by the Agentic Engineer

Lane state — CodeRabbit refused this round at e6000eca. The head's CodeRabbit status reads Review rate limited (15:28:55Z), which postdates this round's request marker (15:28:xxZ), so the refusal belongs to this round rather than an earlier one. The accompanying notice states the next included review is ~25 minutes out.

Recorded as cr:no-gate@e6000eca so a later run resumes at the next lane instead of re-spending CodeRabbit on this same head.

Not advancing to Codex on this PR deliberately. CodeRabbit's quota is per repository, and the free window reopens shortly; Codex is weekly-limited, and this run is spending its Codex budget on #3583, which is one green away from merging. This PR is a draft carrying a fresh comment-only fix with no urgency, so the cheaper lane is worth the wait.

Two observations worth recording, since both cost a request today:

• A trigger carrying the disclosure line and an HTML request marker above @coderabbitai review was misparsed as chat at adf9609f — CodeRabbit ran an analysis chain and returned prose rather than opening a review. @coderabbitai full review was accepted immediately. The misparse is therefore not limited to a bare trigger.
• That chat response was not empty of value: it carried the P2 that produced e6000eca. A misparsed trigger can still contain a real finding, so it is worth reading before re-triggering rather than discarding as a failed request.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@devantler Thanks for the clear lane record.

The CodeRabbit review did not run at e6000eca because of the rate limit. The current head remains without a completed CodeRabbit review.

The adf9609f chat response still required review because it contained a valid P2 finding. The fix at e6000eca addresses that finding.

---

✏️ Learnings added

Learnt from: devantler
URL: https://github.com/devantler-tech/platform/pull/3587

Timestamp: 2026-09-04T15:32:18.351Z
Learning: In the devantler-tech/platform repository, an `coderabbitai review` trigger that includes a disclosure line and an HTML request marker can be handled as chat instead of a review request. Inspect any chat response for actionable findings before retrying, because such a response can contain valid review findings.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

You are interacting with an AI system.

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai review

[coderabbitai]

@devantler I will review the current pull request changes.

---

🧠 Learnings used

Learnt from: devantler
URL: https://github.com/devantler-tech/platform/pull/3587

Timestamp: 2026-09-04T15:32:18.360Z
Learning: In the devantler-tech/platform repository, an `coderabbitai review` trigger that includes a disclosure line and an HTML request marker can be handled as chat instead of a review request. Inspect any chat response for actionable findings before retrying, because such a response can contain valid review findings.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.