[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 eight subsystems of the platform 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. Every selector of a system or subsystem role leaves out rbac.deckhouse.io/kind: use with a NotIn expression, as the platform test requires: a use capability of the scheme before DKP 1.78 gives rules in a namespace, and a role bound cluster-wide would give them in every namespace.
• 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.

Names and namespace. Bootstrap keeps the names the templates already give. A prometheusAccess entry -- one, or a list when the module has several scrape Roles -- carries the path and name of an existing scrape Role, and a bindRoles entry the bindingName of an existing binding; without them the generator writes access-to-<module> at the root and the derived binding name, as before. Where an existing name cannot be expressed (a Role and RoleBinding named apart, a name the placement rule refuses) bootstrap falls back to the generated name and says why in its note. The generator writes the module namespace as d8-{{ $.Chart.Name }} when the module lives in d8-<chart name>, as the hand-written templates do; any other namespace stays literal.

Names of the other objects. Each kind of object the declaration names gets an optional name field of its own: access[].roleName and bindingName, prometheusAccess[].bindingName, serviceAccounts[].clusterRoleBindingName, roleName and roleBindingName (the Role of namespaceRules and its RoleBinding), extraClusterRoles[].bindingName, and a bindClusterRoles entry, which may now be a mapping of name and bindingName beside the plain role name, as bindRoles[].bindingName already was. Without a field an object gets the derived name as before, so existing declarations read, validate and render unchanged; a field naming an object the entry does not produce is an error. The bootstrap fills a field only where the placement rule, with the module's exclude-rules.placement, accepts the existing name in the file the declaration writes the object to, or refuses the derived name as well; otherwise --fix renames the object and the note says which file refuses which name. An access name that already starts with access-to-<module> is no longer prefixed twice, and a note names an access entry's object that moves to another template. On deckhouse main the rename notes of the bootstrap drop from 117 to 13, each a name the placement rule refuses in its target file.

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]

🟡 13. module.yaml subsystems may diverge from the lineages the system capabilities carry, which the platform test in deckhouse forbids

Deckhouse MR !352 adds TestRBACv2ModuleSubsystemsValidation (testing/rbacv2/rbacv2_legacy_aliases_test.go:124-233, f47e77e01c). It requires that a module with templates/rbacv2/manage/*.yaml declares in module.yaml exactly the set of aggregate-to-<lineage>-as lineages (excluding system) its capabilities carry. Docs and the console read module.yaml, and the aggregation controller reads the labels. kube-dns, kube-proxy and istio were aligned to this there.

dmt goes the other way:

• the rbac.yaml subsystems: override (rbacyaml/types.go:56-59) exists to aggregate into subsystems module.yaml does not declare. Its comment still names kube-dns/kube-proxy/istio, which is stale after !352.
• bootstrap writes that override itself when the lineages differ from module.yaml (bootstrap/bootstrap.go:1116-1121), and only adds a note.
• the README (:1362-1364, :1796) suggests setting subsystems in rbac.yaml.

Nothing in contract compares module.yaml with the carried lineages. So an external module passes dmt with a mismatch the platform treats as a bug, and an in-tree module that follows dmt's advice fails testing/rbacv2.

Suggestion: port the equality check (module.yaml subsystems == lineages of the system capabilities) into contract. Turn the rbac.yaml subsystems: override into a finding ("declare it in module.yaml"), or drop it. Bootstrap should propose a module.yaml change instead of writing the override. If dmt is deliberately looser here, please state it explicitly in the README.

[Jabejixo]

Done in 735b44c, 47854ef, 506d4ca and f0807f8: contract now holds the module.yaml subsystems to the lineages the rendered system capabilities carry and reports a difference on module.yaml, a system capability carrying the namespace or project lineage gets its own finding, rbac.yaml no longer sets subsystems (the key still parses and sync reports it), bootstrap proposes the module.yaml change instead of writing an override, and the README follows.