[dmt] feat: rbac.yaml module declaration with contract, coverage and sync rules

[Jabejixo]

Description

One declaration per module, modules/<module>/rbac.yaml, describes the user-facing access to every resource the module ships in both role models (RBACv2 capabilities and legacy user-authz roles), the rights of its ServiceAccounts and the access it grants to others. Three new rules of the rbac linter work with it; the templates are generated from it by --fix.

• contract — runs on every module, rbac.yaml or not. It holds the rendered ClusterRoles under templates/rbacv2/ to the platform's label and naming contract (d8: prefix, rbac.deckhouse.io/{kind,scope,capability,aggregate-to-<lineage>-as,use-role,delegatable}, the four en|ru.meta.deckhouse.io/* annotations, per-lineage levels, the module label). It is a port of the platform's testing/rbacv2 validation, so a module outside the platform repository is checked the same way. One check beyond the platform test: a cluster-scoped resource inside a namespace capability is a warning — such a rule grants nothing through a RoleBinding.
• coverage — with rbac.yaml: every CRD under crds/ (recursively, by kind) has an entry that grants levels or denies access with a reason. noAccess: "TODO" is an error of its own: a decision is owed. --fix appends an undecided stub for a missing entry and deliberately leaves the run red — the stub is not a decision.
• sync — with rbac.yaml: the rendered objects and the declaration say the same thing, in both directions, compared as (apiGroup, resource, resourceName, verb) tuples plus aggregation edges, roleRefs and subjects. It owns three classes of rendered objects (legacy roles by annotation, module capabilities by kind and module label, objects whose names the generator builds); everything else in the render is neither generated nor reported. --fix regenerates a file from the declaration with two safeguards: a file without the generator header is maintained by hand (the generated text lands beside it as <file>.generated), and a regeneration that would drop a right the render grants today is refused and names the right — removing access is always a person's decision. Under --matrix the fix runs once per file and judges the union of every variant's render.
• The declaration format (rbac.deckhouse.io/v1alpha1) is validated before anything is compared or generated: explicit verb lists, namespace levels only for namespaced resources, a scope for resources the module ships no CRD for, a reason for whole-group entries and for namespaced resources granted cluster-wide, localized texts for capabilities outside the view/edit convention, when conditions that parse as Helm expressions. Unknown keys are errors.
• Configuration: global.linters-settings.rbac.rules.{contract,coverage,sync}.impact sets each rule's level on its own; linters-settings.rbac.exclude-rules.{contract,coverage,sync} excludes objects or group/resource keys. The rbac configuration blocks refuse unknown keys. The three rules start at warn wherever nothing sets them, whatever the linter's impact is; the four original rules keep their level and their output untouched. One change outside the linter: --fix no longer runs the autofix of a finding at the ignored level.
• The three states a module can be in when this dmt first runs are handled and covered by e2e cases: only the RBACv2 scheme before DKP 1.78 (kind: use|manage — contract gives one "migrate" finding per object instead of failing every check; with an rbac.yaml, sync names the legacy template as the cause), only the 1.78 scheme, and both behind the version gate rbacv2-migrate-module.sh writes (the linter's values answer the gate with the new model, the legacy branch is neither judged nor "extra", and --fix never rewrites a gated file).
• no-cyrillic/files no longer judges the ru.meta.deckhouse.io/title|description lines: the role model requires that Russian text and the contract rule enforces it, so the two rules contradicted each other -- 41 in-tree modules carry an identical exclude-rules entry for templates/rbacv2 to reconcile them, and every external module would have needed one. Cyrillic anywhere else in the same file is still reported.
• Verified against the changes a module goes through (a CRD added, removed, renamed or rescoped; a verb dropped; a hand-added rule; a deleted file or declaration; subsystems changed; subresources, whole-group entries, rules under when), on a regenerated copy of an external module. Three findings from that pass are in: a noAccess entry whose group lost every CRD is a coverage warning unless it names a scope; a generator-owned file (header present) is compared as text with what the declaration renders, so a rule under when that is false today still reaches the template through --fix; the copy written beside a hand-maintained file is _<file>.generated, because Helm renders every file under templates/. A fourth came from the full loop on an external module (every RBAC template deleted and regenerated from the declaration): a file whose objects are all under when was never written back, because their absence from the render is not a divergence (D4) -- a declared file that does not exist while an object it holds is absent from the render is now reported and created. The loop ends with 646 rules, 26 bindings and ServiceAccounts and 18 role-model labels identical before and after, modulo the renames the generator's naming forces.
• The same loop on three platform modules (cert-manager, user-authz, multitenancy-manager) added two more: sync owns only the module's own namespace/system capabilities by name -- the project lineage of multitenancy-manager and the platform-wide capabilities of user-authz are not the declaration's and stay hand-written; and a generated file that also holds objects the declaration does not produce (cert-manager's webhook:requester, user-authz's permission-browser ClusterRoles) is never rewritten, since the generator writes the whole file. no-cyrillic skips rbac.yaml as it skips module.yaml: the declaration carries the Russian capability texts the role model requires.
• Fifteen corner cases on a synthetic module (a module without subsystems or with a non-d8 namespace, a marker past 63 characters, an account named unlike its directory, an object rendered from another file than the declaration places it, braces in when, core-group resources, BOM and CRLF, an rbac.yaml of the earlier shape, duplicate objects and subjects, a conditional object off by default at bootstrap) closed nine more gaps; the generator now refuses what the declaration alone cannot know is wrong -- system levels without a subsystem, a marker too long for a label, an account the placement rule would reject -- and built-in Kubernetes resources need no scope.
• Docs: pkg/linters/rbac/README.md has the format, the three rules and the developer loop (rbac.yaml → dmt lint --linter rbac --fix → dmt lint). e2e cases under test/e2e/testdata/rbac/.

What the findings look like on the platform tree today (--linter rbac, 47 modules; the base dmt reports nothing there):

🐒 [contract (#rbac)]
     Message:      capability "d8:namespace-capability:cert-manager:view" grants cert-manager.io/clusterissuers, a
                   cluster-scoped resource, in a namespace capability: bound through a RoleBinding the rule grants
                   nothing; move it to a system capability
     Module:       cert-manager
     Object:       ClusterRole/d8:namespace-capability:cert-manager:view
     FilePath:     templates/rbacv2/use/view.yaml

🐒 [sync (#rbac)]
     Message:      parse rbac.yaml: yaml: unmarshal errors: ...; nothing is compared or generated until the declaration parses
     Module:       cert-manager
     FilePath:     rbac.yaml

Under --matrix the same 10 findings appear; every other rule's output on the tree, default render and matrix alike, is identical to the base. On two external modules still on the pre-1.78 scheme (operator-trivy, security-profiles) the run gives four "legacy scheme" warnings each and no errors.

The sync warnings come from six rbac.yaml files of an older, never consumed shape that still sit in the platform tree; their removal is a separate platform PR.

How an existing module enters the declaration

Without rbac.yaml, sync reports the declaration missing and --fix writes it from the RBAC objects the module renders today: the file a person would have transcribed from the templates, with a TODO wherever a decision is still theirs (a resource without a CRD whose scope the linter cannot know, a CRD nobody grants, a namespaced resource granted cluster-wide) and a note on top for every object the generator will name differently or cannot describe. The person reviews it, resolves the TODOs, and runs --fix again: the templates are regenerated from the declaration, which is the source from then on -- a right removed from it leaves the template, a CRD added to the module gets an undecided stub, a new ServiceAccount is declared and generated.

The format grew what the platform modules needed for this: serviceAccounts[].extraClusterRoles (further ClusterRoles in the account's file, bound to it or not), serviceAccounts[].automountServiceAccountToken (the import keeps the token mounted where it was, so no pod loses it), access[].path (grants kept in a component's files).

Verified end to end on four modules -- operator-trivy after the platform's migration script (both RBACv2 schemes behind the version gate), cert-manager, user-authz and multitenancy-manager: every RBAC template regenerated from the written declaration, the rendered rights identical before and after (646, 339→336 for the dead clusterissuers rule, 2367 and 206 rule tuples), only the object names the generator's convention forces changed; the project-lineage capabilities of multitenancy-manager and the platform-wide roles and capabilities of user-authz stay hand-written and are listed as such.

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

A module's RBAC lives in four places that nobody keeps in step: RBACv2 capability templates, 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. When the platform's role contract changes, every module is edited by hand, and the platform test that checks the contract sees only in-tree modules — external modules drift silently until aggregation breaks in a cluster.

The declaration makes the decision explicit per resource and the templates a derivative of it. The linter is where this belongs: dmt already renders the chart, so sync compares rendered objects rather than template text, the developer keeps the freedom to add conditions and comments, and an external module gets the same contract check as an in-tree one from the tool it already runs.

Design: platform-security/2026-04-27-module-rbac-yaml.md (architecture-decision-records, branch rbac-v2, revision ccd35e0 of 2026-09-22 -- the ADR text now describes exactly this implementation: the bootstrap from the render, the declaration as the source, the three owned classes, extraClusterRoles / automountServiceAccountToken / path / reason, the version gate, the no-cyrillic exemptions and the warn default). A regeneration logs the rights and objects it removes, so a --fix run without a preceding dmt lint does not remove rights in silence.