[dmt] feat: module rbac.yaml declaration, final version (stacked on #479)

[Jabejixo]

Description

Stacked on #479, and the final version of the module RBAC declaration: #479 is the skeleton and is not merged without this PR. Together they add modules/<module>/rbac.yaml, one declaration of a module's RBAC, and three rules of the rbac linter around it -- contract, coverage and sync -- with --fix writing the first declaration from the render and the templates from the declaration. The full description is pkg/linters/rbac/README.md, section "The module RBAC declaration"; what follows is what the two PRs deliver, and what this one changes in the skeleton.

The declaration. rbac.deckhouse.io/v1alpha1, unknown keys refused, validated before anything is compared or written:

• resources[] -- user-facing access to every resource the module ships, in both role models: RBACv2 namespace and system levels (capabilities d8:namespace-capability:<module>:<action> and d8:system-capability:<module>:<action>) and legacy user-authz levels (d8:user-authz:<module>:<level>); explicit verbs, when conditions, noAccess with a reason, scope and reason where the linter cannot know them.
• capabilities -- keyed <lineage>.<action>: localized texts outside the view/edit convention; a capability with an action of its own (download_snapshots, as the platform's access_terminal), which a resource entry grants under its action and level places in a level of the lineage; labels of the module, by which a role of the module outside the role model aggregates its capabilities.
• serviceAccounts[] with cluster and namespace rules, bindings to existing roles, extraClusterRoles, labels, annotations and rbacAnnotations, path for component directories (nested ones included), automountServiceAccountToken; access[] for arbitrary subjects and prometheusAccess for the scraper, both with labels, annotations and when.

The rules.

• contract runs on every module, with or without rbac.yaml: the rendered ClusterRoles under templates/rbacv2/ follow the platform's label and naming contract. It is a port of the platform's testing/rbacv2 validation, so an external module is checked as an in-tree one; a module still on the scheme before DKP 1.78 gets one "migrate" finding per object. A subsystem the module's own module.yaml declares beyond the seven the platform ships (virtualization) is a lineage of that module, for its d8:subsystem:<name>:* roles, its capabilities and the subsystems of rbac.yaml; another module's own subsystem stays unknown.
• coverage: every CRD under crds/ has an entry that grants levels or denies access with a reason. --fix appends an undecided noAccess: "TODO" stub, which the lint then reports.
• sync: the render and the declaration say the same thing, in both directions -- rules as (apiGroup, resource, resourceName, verb) tuples, aggregation edges, the labels of the module and the localized texts of a capability, roleRefs and subjects. A when excuses an absent object or rule only while the condition is false: when anything the declaration writes under it renders, in any file, it holds, and a grant newly declared under it is written by --fix. The conditions around each object and its rules are also compared with the text of the template, both ways, so every render variant agrees: a condition the declaration writes that the template lacks is written by --fix, one the template holds that the declaration does not write keeps the fix off the file. It owns three classes of objects (legacy roles, the module's own capabilities, the objects whose names the declaration builds); everything else in the render is neither written nor reported. The render is judged, not the text of a template.

Either a lint finding or a fix that succeeds. Every case is one or the other, and this PR moves every refusal of the skeleton's autofix to lint time:

• A declaration that does not parse or validate, a broken module.yaml, a declaration in an edition overlay and an rbac.yaml of the earlier shape are findings without a fix.
• Without rbac.yaml, --fix writes it from the render and succeeds; the TODO values it leaves are reported by the lint that follows. The coverage stub works the same way.
• A file the declaration produces is rewritten from it unless the lint finds a case only a change of the templates or of the declaration closes: an object the declaration does not produce, one it puts in another file, a document the linter cannot read (an include, a range, a computed name, a fail/required guard), the version gate, the legacy scheme, a condition ({{ if }}) the declaration does not write, an object exclude-rules.sync keeps out of the comparison, a label or annotation of a legacy role or a capability the format cannot hold, the secrets of a ServiceAccount, a template that is a symbolic link. The finding then names the case and carries no fix: a rewrite never drops or widens what sync does not compare. The case is read from the template text, which is the same in every render variant; under --matrix a variant that finds one keeps the fix of every other variant off the file.
• A template the declaration produces nothing for is a finding without a fix; the autofix deletes no file.
• The templates carry no generator header, no file is copied aside, and --fix exits by the level of what is left, as for every other linter. The object store keeps no Dropped list: the render already warns about a template it skipped.

The first declaration. Bootstrap reads the template text around each rendered object with text/template/parse: {{ if X }} becomes when: X, an {{ else }} branch not (X), nested blocks an and; a condition with a template variable, and an account whose objects render under different conditions, become a TODO. Objects inside range, with or define, ones a named template renders (helm_lib), objects of a subchart and roles without rules stay hand-written; an RBAC object the text holds but no render showed is named in a note on top of the written file. Labels and annotations are imported where the format holds them and named in a note where it does not.

Configuration. global.linters-settings.rbac.rules.{contract,coverage,sync}.impact sets each rule's level, read from the root .dmtlint.yaml as every dmt setting; linters-settings.rbac.exclude-rules.{contract,coverage,sync} excludes objects or group/resource keys. The three rules start at warn wherever nothing sets them, and a rule at ignored is not run, so --fix rewrites nothing on behalf of findings nobody sees; the four original rbac rules keep their level and their output. Outside the linter the PRs change only the wiring of these levels and exclusions, the registration of the rules, and no-cyrillic, which leaves alone the module's rbac.yaml and the ru.meta.deckhouse.io/title|description lines the role model requires -- Cyrillic anywhere else in those files is still reported.

Behaviour to know.

• A level dmt does not know is read as error, as for every linter: rules: {sync: {impact: ignore}} (for ignored) runs sync at error, and a misspelled rule key such as coverge: is dropped. The rbac blocks get no stricter key check than the other linters.
• --fix does not lint again (cmd/dmt/main.go): a coverage stub is a fix that succeeds, so dmt lint --fix exits 0 with coverage at error, and the next plain run reports the TODO it wrote.
• Bootstrap writes not (X) for an {{ else }} branch and and (A) (B) for nested blocks, which the declaration writes as {{- if <when> }}; until the template's blocks are rewritten that way by hand, such a file is a finding without a fix (the template holds a condition the declaration does not write).

Verified.

• Unit and e2e tests with -race, golangci-lint 2.13. The e2e cases under test/e2e/testdata/rbac/ cover the three schemes a module can be on (legacy, 1.78, both behind the version gate), a bootstrap, a clean declaration, a hand edit, a foreign object that keeps the fix off, a missing file the fix writes, a template the render skips, and a role of the module outside the role model with its capabilities and the alias of its old name.
• The platform tree (deckhouse main, 41 modules): dmt lint --linter rbac gives no errors; the 40 warnings are 37 declarations still missing and 3 contract findings (a cluster-scoped resource in a namespace capability). The cert-manager pilot, declared in rbac.yaml, is clean. Bootstrap on every module writes a declaration that parses, and no fix fails.

Why do we need it, and what problem does it solve?

A module's RBAC lives in four places nobody keeps in step: the RBACv2 capability templates, the legacy user-authz roles, rbac-for-us.yaml and rbac-to-us.yaml. On the platform tree 66 of 181 CRDs have no user-facing access at all, and nothing says whether that is a decision or an omission. A change to the platform's role contract is a hand edit of every module, and the platform test that checks the contract sees only in-tree modules, so external modules drift until aggregation breaks in a cluster.

The declaration makes the decision explicit per resource, and the templates follow from it. The linter is where this belongs: dmt already renders the chart, so sync compares rendered objects rather than template text, and an external module gets the same check as an in-tree one from the tool it already runs. Design: ADR platform-security/2026-04-27-module-rbac-yaml.md (architecture-decision-records).

[AlwxSin]

🔴 1. Declared when missing from the template: the unconditional grant is never reported

The declaration grants challenges only under .Values.certManager.internal.acmeEnabled, while templates/rbacv2/use/view.yaml has no {{ if }} around it. The tuple renders for every value of the flag, so holdingConditions marks the condition as holding and nothing diverges. The text check in unfixable (L381) only goes one way: it catches a condition the template has and the rewrite would not write, never a condition the declaration writes and the template lacks.

Result: zero findings in every --matrix variant, and --fix never narrows the template. The template grants more than the declaration, which is exactly the drift sync exists to catch. A throwaway test with that setup gives findings: [].

Suggestion: when the declaration puts an object/rule under when: X and the file that renders it has no {{ if }} whose condition matches X, report it (and let --fix write the condition).

[Jabejixo]

Fixed in 5503908: the conditions around each object and its rules are now compared with the template text, per object, both ways. A condition the declaration writes that the template lacks is a divergence the fix writes back. Test: TestSync_ConditionsOfEveryObject.

[AlwxSin]

🔴 2. The rename path drops aggregation labels and resource-policy: keep, and logs removed: []

replacedByProduced (L649) pairs an object under an old name with a produced one on rules and subjects only; labels, annotations and aggregationRule of the old object are not looked at, and since it is not a managed object none of its metadata is compared.

Scenario: ClusterRole d8:cert-manager:admin-kubeconfig-old carries rbac.authorization.k8s.io/aggregate-to-admin: "true" (via the generator's own helm_lib_module_labels dict form, so the document stays readable) and helm.sh/resource-policy: keep; the declaration produces the same rules and subjects under the new name. --fix rewrites the file: the aggregation to admin (a right) and keep are gone, and the warning says removed: []. That contradicts the promise that a rewrite never drops what sync does not compare.

Suggestion: treat a replaced object as a rename only when its labels/annotations/aggregationRule are also carried over (or are empty); otherwise withhold the fix and name the case.

[Jabejixo]

Fixed in 5503908: it counts as a rename only without an aggregationRule and when the new object keeps every label and annotation outside the role model's own. Otherwise the file gets no fix. Test: TestSync_RenameCarriesMetadata. On the platform tree this caught one real case: app: docs-builder in documentation.

[AlwxSin]

🟡 3. A condition the template adds hides an unconditional object that is absent: no finding and no fix

Wrap templates/rbac-to-us.yaml in {{- if .Values.foo }} with no when anywhere in the declaration. With foo=false nothing renders from the file, so withoutUnrendered drops every object of its text from the comparison. unfixable does find the case and calls withholdFix, but report only emits for paths that have divergences, so the result is neither a finding nor a fix. With foo=true everything renders and matches. A throwaway test gives findings: [].

This breaks "either a lint finding or a fix that succeeds", and "a when excuses an absent object only while the condition is false" (here there is no when at all). Before this PR, Store.Dropped separated a skipped template from a false condition; the heuristic that replaced it does not. At minimum, a path with a withheld fix should get a finding even when it has no divergences.

[Jabejixo]

Covered by the same change: a condition the declaration does not write is a divergence read from the text, so the file gets a finding without a fix even when nothing renders from it.

[AlwxSin]

🟡 4. Bootstrap can give an object the condition of the wrong branch

(a) doc: an if/else inside a single YAML document with no --- between the branches. Only the first kind: of the document is read, so an object rendered from the else branch gets the if condition:

---
{{- if .Values.a }}
kind: ClusterRole
metadata: {name: foo}
rules: []
{{- else }}
kind: ClusterRole
metadata: {name: foo}
rules: [{apiGroups: [""], resources: [pods], verbs: [get]}]
{{- end }}

Locate returns when: .Values.a with Partial=false, although with default values (a false) foo came from the else branch.

(b) Locate (L440): byName is returned before templated is looked at, and the agreement check runs only within one set. With {{ if .Values.legacy }} name: d8:foo:x {{ else }} name: d8:{{ .Chart.Name }}:x {{ end }}, the object rendered with legacy=false gets when: .Values.legacy.

In both cases holdingConditions later treats the wrong condition as holding (an object declared under it rendered), which skews the check for everything else declared under that condition. --fix is saved only by the unrelated "template holds {{ else }}" case.

Suggestion: mark the doc Partial/Unmanageable when a block around it has an else branch inside the same document (or it has a second kind: span); in Locate, return ok=false when templated candidates disagree with byName[0] on When/Unmanageable.

[Jabejixo]

Fixed in 293eee7: an object in several branches of one document stays hand-written, and Locate refuses named and computed candidates that disagree. Test: TestLocate_BranchesOfOneBlock.

[AlwxSin]

🟡 5. Names and values the rewrite writes are not all validated

• Labels: only capabilities.*.labels get IsValidLabelValue and the reserved-key check (validateCapabilityLabels). On serviceAccounts[].labels (here), access[].labels (L595) and prometheusAccess.labels (L197) only the keys are checked, so app: "has space" or heritage: foo / module: bar pass. The value is rejected by the apiserver at install; heritage/module also duplicate what helm_lib_module_labels already writes.
• bindRoles / bindClusterRoles (L556-567) are checked for non-empty only: bindClusterRoles: ["a/b"], bindRoles: [{namespace: "Bad NS", name: "r/1"}] pass, and the binding names and namespace built from them are invalid.
• Subjects in access[] (L600-625) and prometheusAccess.deployments/workload names: name/namespace are not validated; deployments: [""] passes, although an empty resourceNames value is refused for SA rules.

All of these render, pass lint and fail only on install, which contradicts "validate names, paths and conditions as the rewrite writes them".

[Jabejixo]

Fixed in 8787ef0: the labels of serviceAccounts, access and prometheusAccess (values, no heritage/module), bindRoles/bindClusterRoles, ServiceAccount subjects and workload names are all validated now.

[AlwxSin]

🔵 6. The coverage --fix writes rbac.yaml without running Validate

The only caller of rbacyaml.Validate is sync.go:159. A declaration that parses but does not validate (scope: TODO, a duplicate entry, a bad verb) still gets "no entry" findings here plus the stub fix, and appendStub rewrites the file. The doc comment on Validate (validate.go:131-138) says the coverage rule refuses to run on such a declaration. The impact is low since the stub is additive, but either the comment or the code should change.

[Jabejixo]

Corrected the comment: coverage judges any declaration that parses, since the stub only adds an entry. That way CRDs still owed a decision stay visible while a TODO scope blocks sync.

[AlwxSin]

🔵 7. The "legacy scheme" message is not deterministic

misplaced["legacy scheme"] is assigned inside for id, object := range fromFile, so the last writer by map order wins. A file that renders both manage and use legacy ClusterRoles alternates between ...kind: manage... and ...kind: use... (2 distinct texts in 40 runs). Across --matrix variants dedupeErrors then does not collapse them, and golden tests get flaky. Picking the smaller kind, as legacyFiles does, fixes it.

[Jabejixo]

Fixed in 5503908: the finding names the smallest legacy kind. Test: TestSync_LegacySchemeMessageIsStable.

[AlwxSin]

🔵 8. Behavioral changes worth a line in the description

• With the strict rbac-key validation removed here, rules: {sync: {impact: ignore}} (typo) goes through the unknown-string path of ParseStringToLevel and becomes error: sync runs, --fix rewrites templates, the exit is non-zero. coverge: or a module-level linters-settings.rbac.rules is dropped silently. Same as other linters, but these are the rules people will be tuning.
• --fix does not re-lint (cmd/dmt/main.go): once the coverage stub counts as a successful fix, dmt lint --fix exits 0 even with coverage at error, and the next plain run fails on the TODO.
• Bootstrap writes not (X) / and (A) (B) for {{ else }} and nested ifs, while the generator never writes those blocks, so unfixable keeps --fix off every such file until the conditions are removed from the template by hand. The README says so; the PR description does not.

[Jabejixo]

Added to the description under "Behaviour to know".