[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]

🔵 11. prometheusAccess workload findings come out in random order

range over a map literal (deployments/daemonsets/statefulsets) makes the order of these validation errors vary between runs. The texts are the same, so dedupe is fine, but output and golden tests are not stable -- the same class as finding 7. A slice of pairs fixes it.

[Jabejixo]

No change needed: ValidateFor sorts the errors by their text before returning (validate.go:220), and each message names its list and index, so the map order never reaches the output.

[AlwxSin]

🔵 12. A subsystem whose roles render conditionally is "unrendered" in the variants where they don't render

renderedSubsystems reads the current render variant only. If a module's own d8:subsystem:<name>:* roles are rendered under a condition (the version gate, a values flag), then in a --matrix variant where they don't render the contract rule reports the subsystem on module.yaml as unrendered, and knownSubsystems (sync.go:159) drops it, so ValidateFor rejects the rbac.yaml subsystems: entry and sync says "nothing is compared or written until the declaration is valid" for that variant: a false finding plus a blind sync.

This comes from reading the code only; I did not reproduce it. If no module gates its own subsystem roles (virtualization being the known case), feel free to drop it.

[Jabejixo]

No change needed: --matrix varies only the module's own values (buildOverride keys the overrides by the module name), and the version gate reads global.deckhouseVersion, which is dev/test in every render, so the gate always renders the new roles. No module gates its own subsystem roles on a module value: none in deckhouse main declares one, and virtualization has no d8:subsystem:virtualization:* roles yet.