[bmscomp]

Merge #577 first. This branch carries #577's two commits; after #577 squash-merges, I'll merge main in.

Why

kates deploy gave namespaces their labels from .labels, but had no way to label pods or pass the chart values a cluster's Kyverno policies need. On a cluster with an Enforce "pods need team" policy, the namespaces were created and then helm upgrade --install was refused at admission. #577's kyverno check could find the gap but deploy couldn't act on it.

What

.policies, git-ignored (.gitignore), written mode 0600, with a warning if git tracks it. It has one environment per kube context:

environments:
  kind-panda:
    namespaceLabels: {cost-center: cc-42, owner: platform}
    podLabels: {team: payments, tier: data}
    values:
      kates: {global: {imageRegistry: registry.internal/kates}}
    unresolved: [...]   # rules the last check couldn't fix

kates deploy reads the environment of the context it deploys to:

• namespaceLabels sit between .labels and KATES_NAMESPACE_LABELS in precedence.
• podLabels go under every value that labels each chart's pods. chartPodLabelKeys covers every chart deploy installs; a test holds it equal to label_args in scripts/check-chart-policies.sh, which proves in CI that those values reach every pod.
• values.<chart> goes in a file passed after deploy's own values files, so deploy's --set values still win.
• unresolved entries are a warning.
• --policies-file names another file.

kates kyverno check

• Applies the same environment to each render.
• Checks each namespace as the Namespace deploy would create there, so namespace label rules are evaluated too.
• --write-policies fills the environment. Kyverno reports only the first missing label of a rule, so the check reads the failing rule's pattern for every label it requires. A label's value comes from --label, else the one exact value the pattern names. ?*, a | b, a refused value, and every non-label rule go under unresolved with the suggested fix.

.labels is still read as namespace labels, with a one-line hint that .policies holds them now. --labels-file is unchanged.

Not covered

• kates auto, kates kyverno apply and the admin-less gate's scratch installs don't apply podLabels/values yet. They do get .policies' namespace labels, through the shared label reader.
• Third-party charts deploy installs (cert-manager, Kyverno) get no pod labels.
• An existing namespace's own labels aren't read by the check.
• Rules on Kafka broker pods are still not visible offline (the render has the Kafka CR, not the pods).

Tests

• cli: go test ./..., go vet, golangci-lint --new-from-rev=origin/main (0 issues), govulncheck (none). New tests:
  • file validation, and environments kept on save
  • pod labels under every key
  • namespace label precedence
  • pattern extraction, and withFindings
  • deploy passing the values file after its own (kafka component)
• scripts/check-cli-style.sh, check-cli-compat.sh, check-book-style.sh, gen-book-index.py --check, gen-version-matrix.sh --check
• Real run on a scratch Kind cluster (kyvpol, deleted after) with Kyverno 1.17.2 and two Enforce ClusterPolicies: Namespace needs cost-center: cc-42 and owner: ?*; Pod needs team: ?* and tier: data.
  • Run 1, kyverno check --chart kates -n kates --label team=payments --write-policies: exit 1. It wrote cost-center: cc-42, team: payments and tier: data, and listed owner as unresolved. Another environment in the file was kept, and the file ended up 0600.
  • Run 2, after filling owner: exit 0, "Every rule passes (6 passed)".
  • Admission agreed. A bare kates namespace was refused and the labelled one created. The kates chart with only tier set was denied 5 times on a server dry-run, and with both labels it applied with no errors.
• Not run: ./mvnw test (no backend change; feat(cli): kyverno check covers the stack and writes the values it misses #577's run on the same backend tree was 1,790 green), a full kates deploy on the scratch cluster, and the book render.

[graphify-labs]

Graphify reviewed this change.

Code graph out of date: Health delta baseline: last indexed commit 0a08117, 7 commit(s) behind this PR's base. Impact and hotspot numbers below may be wrong.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 2 advisory finding(s) below merit a look before merge.

Not checked: tests were not run; no formal proof of the changed code.

---

Graphify review — findings

Adds a per-kube-context .policies file that feeds namespace labels and per-chart Helm values into kates deploy. It is re-read once the target context is pinned, and each chart's values are appended after deploy's own -f files so they take precedence. In namespaceUserLabels, its namespaceLabels are merged after .labels but before KATES_NAMESPACE_LABELS and --namespace-label, and a hint tells users .labels is superseded. Also adds a Kyverno check that resolves the chart stack against those policies, with the CLI reference and deployment docs updated to match.

Worth a look

• .policies namespaceLabels bypass label validation and the reserved-domain check — cli/cmd/deploy_labels.go:76 · Escalate · medium
  • NOT verified (no proof, no reproducing execution) — needs human review
• Kafka stack chart uses chart-root-relative values path with chart prefix — cli/cmd/kyverno_check.go:62 · Escalate · medium
  • NOT verified (no proof, no reproducing execution) — needs human review

Review partial — this diff was larger than one review pass covers, so later files were not reviewed; some findings may be missing.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 976 functions depend on the 603 functions this change touches.

Health — this change adds coupling hotspots:

• worse: runDeploy() — 20 callers, 30 callees
• worse: namespaceUserLabels() — 11 callers, 6 callees
• new: writeKyvernoValues() — 4 callers, 6 callees
• new: recoverStuckReleases() — 6 callers, 4 callees
• worse: runComponents() — 7 callers, 3 callees
• new: recoverStuckRelease() — 1 callers, 8 callees
• new: checkKyvernoChart() — 1 callers, 7 callees
• new: runDeployAndReport() — 1 callers, 6 callees
• …and 1 more — each is listed as a finding

Verification — 976 functions in the blast radius were not formally verified this run (proofs are advisory here).

Health delta baseline: last indexed commit 0a08117, 7 commit(s) behind this PR's base.

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 862 function(s) in the blast radius were not formally verified this run

Docs that may be stale (advisory)

• docs/book/05-test-types.md § How a ROUND_TRIP Run Works (lines 249-276): references changed symbols note
• docs/book/06-chaos-theory.md § Leader Election (lines 180-204): references changed symbols accepts, note
• docs/book/11-api-reference.md § Workflow 3: Export Results in Different Formats (lines 1600-1643): references changed symbols accepts
• docs/book/21-kafka-connect.md § How EOS Works (lines 663-685): references changed symbols note
• docs/book/STYLE.md § Callouts (lines 74-92): references changed symbols note
• docs/book/appendix-compliance-language.md § Waivers (lines 307-327): references changed symbols note
• docs/book/appendix-compliance-language.md § The Report (lines 328-365): references changed symbols note
• docs/book/compliance.md § When the Cluster Falls Short (lines 479-516): references changed symbols note
• plans/book-professional-edition.md § 04-performance-theory.md (lines 176-225): references changed symbols note
• plans/book-professional-edition.md § 22-mirror-maker2-migration.md (lines 960-996): references changed symbols note

…and 2 more.

· 4 grounded finding(s) anchored inline below; 5 more finding(s) on lines outside this diff (see the check run).