Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Le socket de gouvernance

Le socket tout entier plutôt qu’un seul de ses rôles : les quatre rôles — deux qui jugent un build, deux qui le façonnent —, les deux moteurs de politiques livrés dans le compilateur, et la façon dont un opérateur rattache un plugin.

Un opérateur rattache un plugin de gouvernance Wasm pour inspecter un build et agir sur ce qu’il trouve. L’hôte du compilateur reste neutre vis-à-vis du contenu et sans parti pris : il achemine la charge utile du build vers le guest et agit sur ce que le guest renvoie, et il n’interprète jamais la politique elle-même. Toute l’intelligence de domaine des politiques — le langage de politique, son moteur et les règles — réside dans le guest.

C’est le même contrat de pureté ahead-of-time sous lequel s’exécute chaque socket : le guest évalue la charge utile qu’on lui remet et renvoie un résultat que l’hôte consomme tel quel (voir le contrat de la sandbox). L’hôte n’apprend rien du langage de politique que parle le guest et ne porte aucun code de moteur de politiques qui lui soit propre.

Un plugin de gouvernance est rattaché à exactement un rôle, et c’est le rôle — et non le plugin — qui fixe à la fois quelle charge utile arrive et ce que le rattachement peut en faire. Deux sont des rôles de verdict : le rattachement juge le build, et l’hôte entreprend exactement une action parmi trois pour chaque verdict qu’il renvoie. Deux sont des rôles de transformation : le rattachement signale une modification des labels ou des annotations du build, et l’hôte l’applique. Un plugin qui sert plus d’un rôle est rattaché une fois par rôle, et il ne déclare aucun rôle qui lui soit propre — c’est le rattachement qui le porte.

Cette page est le traitement complet du socket de gouvernance : les quatre rôles et la charge utile que porte chacun, les niveaux de gravité des verdicts sur lesquels agit l’hôte, le canal d’entrée agnostique vis-à-vis du moteur que fournit un opérateur, la façon d’écrire une politique pour l’un ou l’autre des deux moteurs de politiques livrés dans le compilateur — l’un évaluant Rego, l’autre évaluant CEL —, la façon dont un guest encapsule un moteur de politiques externe, les guests de référence livrés, et la façon dont un opérateur rattache un plugin à un espace de travail. Pour la place du socket dans le pipeline et ses formes de transmission typées, voir plugin-contract.md ; pour la création et la publication d’un plugin comme entité du catalogue, voir le Guide du développeur de plugins Wasm.

Le modèle mental : l’hôte achemine, le guest décide

Lors d’un build, l’hôte assemble la charge utile pour le rôle du rattachement, la transmet à travers la frontière de l’ABI et relit ce que le guest a renvoyé. À un rôle de verdict, il s’agit d’une liste de verdicts, chacun portant un niveau de gravité et un message lisible par un humain : l’hôte fait correspondre chaque niveau de gravité à une action de build, et il ne lit pas le message pour en tirer un sens, ne sait pas ce que la politique a vérifié et ne sait pas quel moteur a produit la décision. À un rôle de transformation, il s’agit de la modification à apporter, adressée aux labels ou aux annotations que ce rôle gouverne et à rien d’autre.

Comme l’hôte n’interprète pas le contenu des politiques, toute la surface des politiques appartient au guest : le langage dans lequel les règles sont écrites, le moteur qui les évalue et la manière dont une règle qui se déclenche devient un verdict ou une modification. Le contrat du socket est étroit par conception — un rôle, un ensemble d’entrées et un résultat — afin que toute technologie de politiques qui se compile en Wasm puisse le servir.

Un rôle de verdict accepte ou rejette et ne fait rien d’autre : l’hôte ne lit sa sortie que comme une décision et ne l’applique jamais comme une modification, si bien qu’une politique ne peut pas rendre discrètement conforme un build non conforme. Un rôle de transformation est l’exception délibérée, et ce qui en fait une exception, c’est que l’opérateur l’a rattaché — rattacher un plugin pour façonner les labels est une déclaration que les labels doivent être façonnés. Ce qu’un tel rattachement peut modifier est borné à la surface de son propre rôle, et le build s’arrête bruyamment sur tout ce qui en sort.

Les quatre rôles

Un plugin est rattaché à exactement un rôle, et le rôle fixe l’endroit du pipeline où l’hôte l’évalue, la charge utile qu’il reçoit et ce qu’il peut renvoyer. Un plugin qui doit servir deux rôles est rattaché deux fois — une fois par rôle.

Les rôles de verdict : ir-verdict et render-verdict

  • ir-verdict — le guest raisonne sur le graphe de représentation intermédiaire, avant le rendu. La charge utile porte le graphe IR complet, agnostique vis-à-vis des capacités (chaque nœud, arête et rattachement que détient le compilateur), ainsi que les chemins de routage que l’analyseur énumère, si bien qu’une politique peut raisonner sur la topologie et l’accessibilité sans reparcourir le graphe. Cette liste de chemins est bornée par nœud de départ — une topologie densément connectée ou cyclique peut contenir plus de chemins distincts que l’énumération n’en émet, et une fois la borne atteinte, les chemins restants depuis ce nœud de départ ne sont pas listés. Un chemin présent est donc réel, alors que l’absence d’un chemin ne prouve pas qu’il n’en existe aucun : une politique dont le verdict dépend du fait que quelque chose soit inaccessible doit l’établir à partir des nœuds et des arêtes, que la charge utile porte en entier, plutôt qu’à partir de la seule liste de chemins. Une chose dans le graphe n’est pas telle qu’écrite : chaque valeur qu’un auteur a déclarée sensible — dans les values ou l’infra d’un rattachement, dans l’infra d’un rattachement au niveau d’une frontière, dans les values ou l’infra propres d’un nœud, ou dans les values ou l’infra propres d’une connexion — arrive sous la forme du marqueur de rétention {"aggrega_withheld": "declared"}, tandis que sa clé, son marquage de sensibilité et chaque valeur non déclarée à côté d’elle arrivent tels qu’écrits. Une politique juge où transite le contenu déclaré sensible et ne reçoit jamais ce contenu ; voir les faits de rattachement que lit une politique de gouvernance. Une politique ir-verdict s’exécute au point de contrôle de l’analyse statique, avant que le moindre artefact soit produit. Utilisez-la pour des politiques portant sur l’architecture et le câblage — invariants de topologie, authentification entre frontières, forme du flux d’identifiants — qui doivent arrêter un build avant qu’il ne rende quoi que ce soit.
  • render-verdict — le guest raisonne sur la sortie rendue, après le rendu. La charge utile porte les artefacts émis triés par chemin, si bien que les données transmises sont identiques octet pour octet d’une exécution à l’autre sur une entrée identique. Chaque artefact porte son chemin de sortie et son texte rendu ; il porte en outre le format dans lequel il a été rendu, lorsque le fournisseur qui l’a produit en a déclaré un, et une vue structurée et analysée de son contenu, lorsque le contenu est dans un format qui a été analysé en amont de la politique. Une politique render-verdict voit exactement ce que le build a produit, et rien n’y est retenu : une valeur qu’une Recipe a rendue dans un artefact arrive telle qu’elle a été rendue, parce que l’artefact est ce que juge la politique. Utilisez-la pour des politiques portant sur la sortie concrète — par exemple une règle qui inspecte des services Docker Compose ou des objets Kubernetes rendus.

Les rôles de transformation : annotation-transform et label-transform

  • annotation-transform — le guest rapporte les annotations à ajouter, pendant la résolution et avant l’expansion des annotations. La charge utile porte chaque composant que le rattachement peut annoter, chacun avec les annotations qu’il a déjà, ainsi que les clés d’annotation pour lesquelles le Manifest enregistre une liaison. Une annotation injectée sous une clé enregistrée s’étend ensuite en un rattachement de Feature, et c’est ainsi que ce rôle ajoute à un build une capacité que le développeur n’a pas saisie.

    Les composants qu’il peut annoter sont chaque composant qu’une frontière nomme sous components:, et chaque composant que l’entrée de routage aggregates: d’une frontière y achemine. Une entrée de routage place chaque composant de son module, y compris les composants des modules imbriqués en son sein, que son propre components: les nomme tous, certains ou aucun, comme le fait documents: {}, qui n’en nomme aucun ; la charge utile les porte tous. Un composant acheminé est adressé par l’id qu’il porte dans le graphe de build — le nom du module, un point et le nom du composant dans le module, comme dans documents.backend, avec un nom de module et un point de plus pour chaque module imbriqué — ce qui est la façon dont le graphe de build et ses diagnostics l’écrivent, si bien qu’une décision le nomme aussi de cette façon. Un composant que l’entrée de routage place sans le nommer ne porte aucune annotation propre dans la charge utile, et une annotation injectée sur lui est appliquée comme une annotation écrite sur lui sous l’entrée de routage.

  • label-transform — le guest rapporte les modifications de labels à appliquer, pendant la construction de la topologie : après la construction du graphe et avant que le graphe soit jugé. La charge utile porte une projection des nœuds du build — chacun avec le Component qu’il instancie, la version résolue pour lui, les labels qu’il porte actuellement et les valeurs que déclare son instance, en lecture seule et avec chaque valeur que son Component déclare sensible retenue comme le verdict sur le graphe la retient — ainsi que le nom et l’environnement de la Release. Utilisez-le pour des métadonnées dérivées qu’un développeur ne devrait jamais avoir à saisir (périmètre de conformité, propriété, attribution des coûts) et pour un label de capacité que gagne la configuration déclarée d’un développeur.

Les rôles portent des charges utiles différentes parce qu’ils agissent à des moments différents et répondent à des questions différentes. Tous les quatre portent le même canal d’entrée fourni par l’opérateur, décrit ci-dessous. Pour voir une charge utile plutôt que de lire sa description, aggrega build --release <release> --policy-input <dir> écrit la charge utile que chaque rôle remet à un plugin qui y est rattaché — y compris un rôle auquel rien n’est rattaché — sous la forme d’un fichier JSON par rôle, ou par rattachement lorsque les rattachements d’un rôle reçoivent des charges utiles différentes, et combiné avec --dry-run il écrit ces fichiers et rien d’autre. À annotation-transform, label-transform et ir-verdict, le fichier est le document input que lit une politique. À render-verdict, le moteur de politiques remodèle la charge utile avant qu’une politique ne la lise — les documents de chaque artefact en sont analysés — si bien qu’une politique render-verdict sur un moteur intégré au compilateur se teste dans un build, rattachée à warn ou info, comme le montre Tester une politique avant qu’elle ne bloque un build. Pour un plugin dont vous avez compilé vous-même le .wasm, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json l’exécute sur ce fichier.

Verdicts et niveaux de gravité

Les niveaux de gravité ci-dessous sont le vocabulaire des rôles de verdict. Un rôle de transformation rapporte une modification plutôt qu’un verdict, il ne porte donc aucun niveau de gravité.

Un guest renvoie une liste de verdicts. Chaque verdict porte un niveau de gravité qui détermine l’action de build :

  • halt — arrête le build ; l’hôte présente le message du verdict comme motif. Le build ne produit aucun artefact.
  • warn — signale le verdict ; le build continue.
  • info — enregistre le verdict ; l’issue du build est inchangée.

Ces trois-là forment l’ensemble complet, et ce sont les trois mêmes qu’utilisent les diagnostics de tous les autres sockets, si bien qu’un niveau de gravité a le même sens partout où vous en lisez un.

Un verdict portant toute autre valeur est une violation du contrat plutôt qu’une quatrième voie. Le build s’arrête, et le message nomme le plugin, la valeur que portait le verdict et les trois que déclare le contrat — si bien qu’un niveau de gravité mal orthographié est signalé comme une erreur de build au lieu de passer pour un verdict sur lequel rien n’agit. Un guest qui rapporte parmi les trois n’est pas concerné.

Une évaluation qui autorise ne renvoie rien. Un guest n’émet un verdict que lorsqu’une règle se déclenche, si bien qu’une liste de verdicts vide signifie que la politique a autorisé le build. Il n’existe aucun verdict « pass » à émettre — le silence vaut autorisation.

Un guest peut renvoyer de nombreux verdicts en une seule évaluation, en mélangeant les niveaux de gravité. L’hôte les parcourt tous : tout halt arrête le build (et chaque message halt est présenté), tandis que les verdicts warn et info sont rapportés sans bloquer. Cela reflète la distinction entre arrêt et avertissement qui sépare une politique qui arrête le build d’une vérification de lint consultative.

Le canal with : sources et paramètres

Un guest de politiques est généralement générique vis-à-vis des règles précises qu’il applique — le moteur est intégré au guest, mais les règles sont fournies par rattachement. Le canal with porte cette entrée par rattachement. Il comporte deux champs agnostiques vis-à-vis du moteur :

  • sources — les fichiers de définition de politiques que charge le guest. L’hôte lit chaque fichier nommé au moment du build et en transmet les octets au guest de façon opaque : il n’analyse jamais une source, et le chemin qu’il remet au guest est le nom de base du fichier, jamais un chemin absolu de l’hôte. Ce que signifient les octets relève entièrement du guest — un fichier .rego pour un guest, un autre format de politique pour un autre, et une archive encodée en base64 d’un ensemble complet de politiques pour un guest qui en lit une.
  • settings — une table de configuration que le guest fait correspondre à son moteur. Un guest lit ses réglages (un plafond de réplicas, une clé de label obligatoire) dans cette table. Par défaut, l’hôte la transmet telle quelle sans agir dessus ; un guest peut en outre déclarer un schéma pour elle (voir ci-dessous), auquel cas l’hôte valide la table par rapport à ce schéma avant d’exécuter le guest.

Un guest entièrement précompilé — dont les règles sont compilées en son sein plutôt que fournies au moment du rattachement — omet entièrement with. Le canal est facultatif à chaque rôle.

Paramètres typés

Un guest peut déclarer un JSON Schema pour les settings qu’il attend. Dans ce cas, l’hôte valide les settings du rattachement par rapport à ce schéma avant d’exécuter le guest. Des paramètres non conformes arrêtent le build avec un message qui nomme la clé fautive et ce que le schéma attendait — une clé obligatoire manquante, une valeur du mauvais type, une clé inconnue ou une valeur hors limites est détectée en amont plutôt que de se manifester comme un échec obscur du guest ou, pire, comme un build erroné mais réussi.

Les paramètres typés sont facultatifs et déclarés par le guest, non par l’hôte. Un guest qui ne déclare aucun schéma de paramètres conserve le comportement libre : l’hôte transmet ses settings sans les vérifier. L’hôte effectue une validation JSON Schema ordinaire par rapport au schéma que le guest a déclaré, quel qu’il soit ; il n’interprète pas ce que signifient les paramètres. Cela maintient la vérification neutre vis-à-vis du moteur — chaque guest décrit la forme des paramètres qu’il lit, et l’hôte impose exactement cette forme et rien de plus.

Un rattachement qui ne déclare aucun paramètre est validé comme JSON null. C’est ce qui permet à un guest de rendre ses paramètres obligatoires : un schéma qui n’admet qu’un objet refuse un rattachement qui n’en fournit aucun, et le build s’arrête. La conséquence vaut aussi dans l’autre sens, et c’est celle pour laquelle il faut écrire délibérément : un guest dont les paramètres sont réellement facultatifs doit déclarer un schéma qui admet null aussi bien qu’un objet, faute de quoi il ne peut pas du tout être rattaché sans paramètres. Les deux moteurs de politiques livrés dans le compilateur déclarent "type": ["object", "null"] précisément pour cette raison — rattachez-en un sans bloc with: et il s’exécute avec ses valeurs par défaut. Un guest qui déclare "type": "object" seul a rendu ses paramètres obligatoires, que ce soit ou non l’intention.

L’ABI appartient à Aggrega

Le contrat du socket est l’ABI propre d’Aggrega, et non celle d’un quelconque moteur de politiques. C’est ce qui permet à toute technologie de politiques compilée en Wasm de servir de guest interchangeable : le guest présente vers l’extérieur la surface d’Aggrega — describe(), plus l’export qu’appelle le rôle qu’il sert — et le moteur qu’il utilise, quel qu’il soit, est un détail d’implémentation derrière cette surface.

Un guest qui encapsule un moteur de politiques externe absorbe l’ABI de ce moteur en son sein. Si le moteur a sa propre ABI Wasm, ses propres points d’entrée ou son propre protocole de rappel vers l’hôte, le guest qui l’encapsule l’instancie et le pilote en interne, et fait correspondre la décision du moteur à la forme de verdict du socket. L’hôte du compilateur ne voit que la surface standard des verdicts de gouvernance ; il n’apprend jamais quel moteur est en jeu et ne porte aucun code propre à un moteur. Faire passer une politique d’un moteur à un autre est une modification du rattachement, pas une modification de l’hôte.

Deux moteurs de politiques sont livrés dans le compilateur

Deux moteurs de politiques sont compilés dans le binaire de la CLI, et un opérateur rattache l’un ou l’autre — ou les deux — de la même façon que n’importe quel plugin de gouvernance est rattaché :

CoordonnéeLangage de politiqueSource rattachée
governance/regoRegoFichiers .rego, ou une archive encodée en base64 d’un ensemble complet de politiques
governance/celCommon Expression Language (CEL)Fichiers d’expressions .cel, ou documents de règles .yaml / .yml

Tout ce qui entoure le langage est partagé. Les deux servent les quatre rôles, les deux lisent la même charge utile par rôle sous les mêmes noms de champs, les deux font correspondre leurs décisions aux trois mêmes niveaux de gravité de verdict via le même paramètre translation, et les deux échouent bruyamment plutôt que d’autoriser un build qu’ils n’ont pas pu évaluer. Chacun porte comme version la release du compilateur qui le livre, et aucun n’a besoin d’une chaîne d’outils externe ni ne récupère quoi que ce soit au moment du build. Ce que chaque langage peut dire n’est pas partagé : une règle qui tient en quelques règles auxiliaires en Rego peut nécessiter des paramètres et de la répétition en CEL — voir Ce qu’une expression peut dire avant d’en écrire une qui parcourt un chemin.

Ce qui diffère, c’est le langage dans lequel les règles sont écrites, et c’est là toute la base du choix. Un parc informatique qui conserve déjà un corpus Rego — ou une équipe qui écrit du Rego pour le contrôle d’admission ailleurs — rattache le moteur Rego, et ses politiques s’exécutent telles quelles. Une équipe qui exprime ses règles sous forme d’expressions uniques portant sur un document, comme le fait une politique d’admission de validation Kubernetes, rattache le moteur CEL. Les deux sont rattachés par rôle, si bien qu’un espace de travail peut exécuter Rego à un rôle et CEL à un autre, ou les deux au même rôle sous forme de deux rattachements.

L’hôte est agnostique vis-à-vis de celui des deux dont provient une décision : il achemine la charge utile, relit un verdict ou une modification, et agit en conséquence. Faire passer une politique d’un langage à l’autre est une modification du rattachement et une réécriture des règles — jamais une modification de l’hôte.

Politiques Rego : deux voies

Rego est un langage de politiques répandu, et il existe deux voies pour l’exécuter — un moteur à faible friction livré dans le compilateur, et une porte de sortie de fidélité complète.

Le moteur Rego du compilateur est la voie à faible friction. Il embarque un évaluateur Rego natif Wasm, si bien qu’un opérateur dépose un fichier .rego dans sources et rattache le plugin — aucune chaîne d’outils externe, et rien n’est récupéré au moment du build. Il sert les quatre rôles : le même plugin juge le graphe de build, juge la sortie rendue, façonne les labels ou injecte des annotations, selon le rôle auquel il est rattaché. Son identité de catalogue est le nom nu rego sous pluginType: governance — la coordonnée governance/rego — et sa version est la release du compilateur qui le livre. Écrire une politique pour ce moteur fait l’objet de la section suivante.

L’évaluateur réimplémente Rego de façon indépendante au lieu d’embarquer l’implémentation de référence, et il n’implémente pas toutes les fonctions intégrées de Rego. Lorsqu’une politique appelle une fonction intégrée que l’évaluateur n’implémente pas, le rattachement échoue bruyamment : il renvoie une défaillance, pas une autorisation. Le build s’arrête alors avec une défaillance qui nomme le plugin — délibérément distincte d’un verdict halt, afin que « le moteur ne peut pas évaluer cette politique » ne soit jamais confondu avec « la politique autorise le build ». Une politique inévaluable arrête le build ; elle ne passe jamais discrètement.

La porte de sortie opa build -t wasm est la voie de fidélité complète. Lorsqu’une politique a besoin de l’ensemble complet des fonctions intégrées ou de la sémantique exacte du moteur de référence, compilez-la avec la chaîne d’outils propre à OPA en un module Wasm et exécutez ce module derrière un guest adaptateur léger. L’adaptateur absorbe entièrement l’ABI Wasm d’OPA en son sein (voir L’ABI appartient à Aggrega plus haut) : il instancie le module produit par OPA, définit l’entrée, invoque l’évaluation et fait correspondre la décision à la forme du verdict. L’hôte ne voit que la surface standard des verdicts de gouvernance.

Un guest adaptateur de référence est livré comme exemple complet. Il embarque une politique écrite en Rego et précompilée avec opa build -t wasm en un module WebAssembly — un artefact épinglé et versionné dans le dépôt, si bien que l’évaluation s’exécute entièrement dans le guest, sans processus OPA et sans rien récupérer. À chaque build, l’adaptateur instancie ce module précompilé en son sein avec un interpréteur Wasm embarqué, satisfait les imports propres du module (sa mémoire linéaire et ses rappels de fonctions intégrées), lit la charge utile comme document input d’OPA et les settings du rattachement comme document data d’OPA, évalue chaque point d’entrée compilé et fait correspondre le nom de point d’entrée deny / warn / audit de chacun à un niveau de gravité de verdict — respectivement halt, warn et info. Si une politique précompilée a besoin d’une fonction intégrée fournie par l’hôte que l’adaptateur n’implémente pas, l’adaptateur échoue bruyamment — il refuse le module au lieu de renvoyer une autorisation — si bien qu’une politique inévaluable arrête le build au lieu de passer discrètement. Régénérer le module précompilé à partir de sa source Rego est une étape de création exécutée avec la CLI d’OPA, pas une dépendance au moment du build. ../examples/policy-data-class-route/ construit cet adaptateur autour d’un module qui lui est propre, et donne les commandes qui régénèrent les deux.

Les deux voies partagent le même contrat avec l’hôte, si bien que faire passer une politique du moteur du compilateur au moteur complet est une modification du rattachement.

Écrire une politique pour le moteur Rego

Le moteur évalue le Rego écrit par l’opérateur entièrement dans le guest, quel que soit celui des quatre rôles auquel il est rattaché. Le rattacher deux fois, à deux rôles, avec deux fichiers de politique différents, est la façon dont un seul moteur couvre deux moments du même build.

La charge utile du rôle du rattachement est le document input de la politique, et l’objet settings du rattachement est le document data de la politique — ainsi, une politique lit un seuil fourni par l’opérateur sous la forme data.max_replicas. Chaque fichier que le rattachement déclare sous sources devient un module de politique, et chaque package que ces fichiers déclarent est évalué.

Dans quelle syntaxe de règles une politique est écrite

Rego s’écrit dans deux syntaxes de règles et le moteur accepte les deux, module par module. Un ensemble de politiques assemblé avant que la syntaxe actuelle n’existe est donc évalué aux côtés d’un ensemble écrit aujourd’hui, dans le même rattachement.

Dans la syntaxe actuelle, le corps d’une règle est introduit par if, une règle qui collecte dans un ensemble l’indique avec contains, et le module indique dans quelle syntaxe il est écrit en déclarant import rego.v1 sur une ligne à part sous la déclaration de package :

package example
import rego.v1
deny contains msg if {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Dans l’ancienne syntaxe à tête entre crochets, la valeur qu’une règle collecte se trouve entre crochets dans la tête de la règle, et le corps la suit directement. Un module dans cette syntaxe ne déclare rien, car il est reconnu au fait qu’il ne s’analyse pas comme la syntaxe actuelle :

package example
deny[msg] {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Un module qui s’analyse comme la syntaxe actuelle tout en ne déclarant rien est refusé, nommément. La déclaration est ce qui fixe la lecture, et sans elle le même texte de règle peut aboutir à la décision opposée : un corps de règle qui n’est jamais satisfait n’apporte aucune décision dans la syntaxe actuelle et en apporte une dans l’ancienne syntaxe — si bien qu’une politique qui aurait dû rester silencieuse arrête le build, et que le cas symétrique laisse passer un build qu’une règle avait été écrite pour arrêter. Plutôt que de choisir une lecture pour un tel module, le moteur le refuse et indique ce qu’il faut ajouter :

policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.

Le refus est une défaillance de build qui nomme le plugin plutôt qu’un verdict, si bien qu’il arrête le build comme le fait une politique inévaluable et ne se lit jamais comme une politique qui l’a autorisé.

Deux cas limites méritent d’être connus avant qu’ils ne vous surprennent. Un module sans aucun corps de règle — qui ne déclare que des données — s’analyse comme la syntaxe actuelle, si bien que la déclaration lui est demandée aussi, même si les deux lectures n’auraient pas pu différer pour lui. Et un module écrit dans l’ancienne syntaxe n’est jamais refusé, parce qu’il ne s’analyse pas comme la syntaxe actuelle : c’est le moteur lui-même qui distingue les deux, si bien qu’une politique délibérément écrite avec une tête entre crochets n’est jamais prise pour une politique de syntaxe actuelle qui aurait oublié de le dire.

Une politique collecte ses décisions sous une clé de décision

Chaque rôle lit les décisions d’une politique à partir d’une clé de décision — une règle nommée dans laquelle la politique collecte. Les clés lues, et ce que signifie une décision sous l’une d’elles, sont fixées par le rôle.

À un rôle de verdict, une décision est un message, et la clé sous laquelle il a été collecté fixe le niveau de gravité auquel ce message est rapporté. Par défaut, les clés sont les noms de collecte conventionnels de Rego :

Collecté sousRapporté commeEffet sur le build
denyhaltarrête le build
warnwarnapparaît à côté d’un build qui aboutit
auditinfoenregistré ; l’issue du build est inchangée

Gardez les deux vocabulaires séparés, car ils sont deux : deny, warn et audit sont des noms de votre politique, et halt, warn et info sont les niveaux de gravité auxquels rapporte le socket. La colonne de gauche, vous pouvez la renommer ; la colonne de droite est l’ensemble fermé que partagent tous les sockets.

Une politique qui nomme ses décisions autrement déclare la correspondance dans les paramètres du rattachement :

with:
settings:
translation:
- key: blocked
severity: halt
- key: advisory
severity: warn

Une correspondance déclarée remplace celle par défaut au lieu de l’étendre : les clés qu’elle nomme sont exactement les clés lues, si bien qu’une politique qui collecte encore dans deny n’atteint aucun verdict une fois la correspondance ci-dessus déclarée. L’ordre dans lequel les règles sont déclarées est l’ordre dans lequel les verdicts sont rapportés. Une clé que la politique ne déclare pas est une décision absente plutôt qu’un échec, si bien qu’un même fichier de politique peut servir plusieurs rattachements.

Un niveau de gravité hors des trois, et une correspondance déclarée vide, sont refusés par le schéma de paramètres que déclare le plugin — l’hôte valide les paramètres d’un rattachement par rapport à lui avant l’envoi. La même clé mise en correspondance deux fois est refusée lorsque la correspondance est lue, ce qui se produit aussi avant l’exécution de toute politique. Dans les deux cas, le build s’arrête avant qu’une décision ne soit atteinte, jamais avec une correspondance à moitié appliquée.

Pour le reste, les paramètres sont les données propres de la politique : la correspondance est extraite de l’objet, et l’objet atteint le document data de la politique inchangé, si bien qu’une politique écrite pour les clés par défaut voit exactement le document de données qu’elle aurait vu sans aucune correspondance configurée.

À un rôle de transformation, une décision est la modification à apporter plutôt qu’un message ; il n’y a donc aucun niveau de gravité à fixer, et c’est la clé qui est fixée à la place : labels au rôle qui façonne les labels, annotations au rôle qui injecte les annotations. Un paramètre translation n’est lu que là où des verdicts sont rapportés, si bien qu’un rattachement de transformation qui en déclare un porte un paramètre que son rôle ne consomme pas.

Une clé de décision est lue dans chaque package que charge le rattachement, si bien qu’un ensemble de politiques peut répartir ses règles entre plusieurs packages et que chacun apporte ce qu’il a collecté. Le revers de la médaille mérite d’être connu avant qu’il ne vous joue un tour : au sein d’un rattachement, la clé de décision est un nom de règle réservé dans chaque package, si bien qu’un package auxiliaire qui collecte par hasard dans labels pour ses propres besoins voit ses entrées lues comme des décisions de labels. Cela échoue bruyamment plutôt que discrètement — le rattachement signale que quelque chose collecté sous la clé n’est pas une décision de cette forme — mais la façon la plus rapide de lire un tel message est d’y voir une collision de noms ; réservez donc la clé à la décision et donnez un autre nom à une règle auxiliaire.

Ce qu’expose la charge utile de chaque rôle

La charge utile est le document input de la politique, si bien qu’une politique la lit sous les noms que lui donne le format de transmission.

Le graphe de build se trouve à un chemin différent dans les deux rôles qui en portent un. Un verdict sur le graphe reçoit le document entier du graphe, si bien que ses nœuds se trouvent à input.graph.spec.nodes ; le rôle qui façonne les labels reçoit une projection des nœuds, si bien que ses nœuds se trouvent à input.graph.nodes. Une règle déplacée entre ces deux rôles est donc modifiée, pas copiée — et le symptôme d’un oubli est une règle qui ne se déclenche jamais plutôt qu’une erreur, car un chemin qui n’existe pas est simplement indéfini.

RôleCe que lit une politique
ir-verdictinput.graph — le document entier du graphe de build : les nœuds à input.graph.spec.nodes, indexés par id de nœud, les arêtes à input.graph.spec.edges. Une valeur qu’un auteur a déclarée sensible se lit comme {"aggrega_withheld": "declared"}. input.precalculated_paths — les chemins de routage énumérés, chacun portant sa liste ordonnée nodes et attached_features, les types de Feature rattachés n’importe où sur lui (voir ci-dessous). La liste est toujours présente : un build sans chemin entre les composants porte une liste vide.
render-verdictinput.artifacts — une entrée par fichier émis, chacune avec path, content, format et documents, les documents analysés du fichier. format est le format que le fournisseur qui a rendu le fichier a déclaré pour lui — le fournisseur Terraform déclare hcl pour chaque fichier .tf qu’il émet et json pour chaque fichier .tf.json, y compris les fichiers d’un module vendorisé — et la chaîne vide lorsqu’aucun fournisseur n’en a déclaré, comme pour un fichier qu’une Recipe apporte à la sortie partagée d’une frontière. Un tel fichier est tout de même analysé d’après son extension, si bien que ses documents sont présents dans tous les cas. Un artefact qui n’a pas pu être lu de façon structurée porte parse_error et aucun document, si bien qu’une politique peut rejeter sur l’échec lui-même plutôt que de laisser passer sans examen un fichier illisible.
label-transforminput.graph.nodes — les nœuds du build indexés par id de nœud, chacun avec component, resolved_version, labels et values : les valeurs que l’instance du nœud déclare dans l’Aggregate, avec ses templates évalués par rapport à ses paramètres, absentes lorsqu’elle n’en déclare aucune. Une valeur que le Component du nœud déclare sensible se lit comme {"aggrega_withheld": "declared"}, comme à ir-verdict, et ses voisines non déclarées se lisent telles qu’écrites. Une règle lit input.graph.nodes[id].values pour décider d’un label ; elle ne peut pas modifier une valeur. input.compilation_context — le release_name et l’environment de la Release, si bien qu’une politique peut décider différemment selon l’environnement.
annotation-transforminput.targets — chaque composant que le rattachement peut annoter, chacun avec boundary_path, component_name — pour un composant qu’une entrée de routage place, son id dans le graphe de build, par exemple metrics.query — et les annotations que la Release écrit sur le composant lui-même, chaque valeur telle qu’écrite : une chaîne, un objet de sous-clés, ou null lorsque le composant renonce à une annotation dont il hériterait. Chaque clé que porte le composant est présente quelle que soit sa valeur, si bien qu’une règle peut laisser intacte une clé que quelqu’un a déjà écrite. input.binding_keys — les clés d’annotation pour lesquelles le Manifest enregistre une liaison.

Une ressource Terraform se lit à un chemin différent dans chacune des deux formes de Terraform. Dans les documents d’un fichier .tf natif, un bloc est imbriqué sous son type puis sous chacun de ses labels, et le dernier label contient une liste de blocs, car les blocs partageant un type et des labels sont collectés dans une même liste dans l’ordre de la source. Un attribut de ressource se lit donc à input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — pour une instance RDS de n’importe quel nom, input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Un fichier .tf.json est lu tel que la Recipe l’a écrit, si bien que sa forme objet conventionnelle, où le nom contient le bloc lui-même, se lit à resource.<type>.<name>.<attr>, et qu’une politique destinée aux deux formes lit les deux chemins. Cela vaut pour les deux moteurs de politiques du compilateur. Une règle Rego écrite pour l’autre forme trouve indéfini le chemin qu’elle nomme : une règle qui teste une valeur à cet endroit ne se déclenche jamais, et une règle qui refuse sur une valeur absente, avec not, se déclenche sur chaque ressource ; une expression CEL qui indexe ou sélectionne dans l’autre forme arrête le build avec une défaillance d’évaluation qui nomme son fichier de politique. L’adaptateur de rendu Rego de référence, décrit sous Adaptateurs de politiques pour l’étape de rendu plus bas, analyse lui-même un fichier .tf natif et lit un bloc unique comme un objet, si bien qu’un chemin Terraform est modifié, pas copié, lorsqu’une politique est déplacée entre cet adaptateur et un moteur du compilateur.

Chaque rôle porte en outre input.sources — les fichiers propres du rattachement, chacun avec son nom de base comme path et son content. Une politique ne s’exécute qu’en tant que l’un de ces fichiers, si bien que, partout où une règle lit la liste, celle-ci contient au moins ce fichier.

input.settings est l’objet de paramètres du rattachement, le même objet que le document data de la politique, et il est présent lorsque le rattachement déclare des paramètres. Lorsque le rattachement n’en déclare aucun, ce que trouve une règle dépend du rôle : à ir-verdict, label-transform et annotation-transform, le champ est absent, si bien que input.settings est indéfini comme tout chemin que la charge utile ne porte pas, et à render-verdict c’est l’objet vide. Une règle qui dépend du fait qu’un paramètre a été configuré ou non teste donc le paramètre qu’elle lit plutôt que l’objet, ce qui se comporte de la même façon à chaque rôle — un max_nodes configuré est lu, et un paramètre non configuré laisse input.settings.max_nodes indéfini et la règle silencieuse :

package example
import rego.v1
deny contains msg if {
limit := input.settings.max_nodes
count(input.graph.spec.nodes) > limit
msg := sprintf("this build declares more than %v nodes", [limit])
}

Le moteur CEL traite différemment un objet de paramètres non déclaré, et l’indique dans sa propre section plus bas.

attached_features et binding_keys sont des listes plutôt que des objets, si bien qu’une politique teste l’appartenance avec in :

package security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some gateway in path.nodes
input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"]
not "core/data-masking" in path.attached_features
msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])
}

attached_features est l’union des types de Feature de chaque rattachement que détient n’importe quel nœud du chemin — y compris un rattachement écrit sur l’une des connexions de ce nœud, quelle que soit la connexion sur laquelle il a été écrit — si bien que la règle est satisfaite par un rattachement core/data-masking sur la passerelle elle-même, qui est l’endroit où cette Feature se rattache : elle sélectionne sur la capacité de masquage de contenu que déclare la passerelle. Ce que masque le rattachement, c’est le texte de chat et de complétion qui passe par cette passerelle ; la règle vérifie que le rattachement existe, pas ce qu’il liste.

Comme c’est une union sur tout le chemin, la liste indique qu’une Feature est rattachée quelque part sur un chemin, et jamais où. Une règle qui doit savoir si une Feature se trouve entre deux composants particuliers d’un chemin — celui qui détient des données restreintes et celui qu’il atteint — lit les nodes du chemin dans l’ordre et les rattachements propres de chaque nœud, à input.graph.spec.feature_values_mapping[<node>] ; posée à attached_features, la même question laisse passer un chemin sur lequel la Feature se trouve au-delà du second composant. ../examples/policy-data-class-route/ est écrit de cette façon, pour le moteur Rego, le moteur CEL et OPA.

Un objet nœud ne porte aucun id propre : l’id est la clé sous laquelle il se trouve dans input.graph.spec.nodes, c’est pourquoi la règle ci-dessus reprend dans son message les id qu’elle a lus dans path.nodes au lieu de lire un champ id.

L’ordre dans lequel une politique rencontre les clés d’une table

Le graphe conserve l’ordre que son auteur a écrit : les nœuds dans l’ordre où les composants ont été déclarés, et les labels de chaque nœud dans l’ordre où le nœud les porte. Cet ordre passe intact dans le guest — la charge utile porte les deux sous forme d’entrées ordonnées (voir tables qui conservent leur ordre). Qu’une politique le rencontre ou non dépend de la façon dont le moteur qui évalue la politique conserve un objet, et non de la charge utile :

  • Le moteur Rego conserve les clés d’un objet triées. Une règle qui itère sur input.graph.spec.nodes, sur les labels d’un nœud ou sur tout autre objet — y compris un objet écrit dans la politique elle-même — rencontre les clés dans l’ordre trié : des composants déclarés web, api, metrics sont rencontrés comme api, metrics, web.
  • Le moteur CEL ne fixe aucun ordre pour une table. Une compréhension sur input.graph.spec.nodes ou sur les labels d’un nœud peut rencontrer les clés dans un ordre différent lors de deux builds sur une entrée identique, et deux parcours de la même table au sein d’une seule expression peuvent différer l’un de l’autre. C’est pourquoi les messages sous une même clé de décision sont triés : écrivez une règle dont la décision ne dépend pas de la position qu’occupe une clé.
  • Un guest écrit avec un kit de plugin rencontre l’ordre de l’auteur. Décodés par son kit, les nœuds et les labels de chaque nœud arrivent dans le conteneur du kit qui conserve l’ordre, dans l’ordre où la charge utile les porte, et le squelette d’adaptateur de gouvernance que fournit chaque kit remet à son moteur un document JSON écrit dans ce même ordre. Un moteur qui convertit ce document en un type de valeur qui lui est propre rencontre à la place l’ordre de ce type, comme le décrit tables qui conservent leur ordre.

Façonner les labels : une politique nomme le label, et le moteur le désigne

Au rôle qui façonne les labels, une politique collecte une décision par label sous labels, en nommant le nœud, la clé du label et la valeur que prend le label :

package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

Définir une clé déjà présente remplace sa valeur. Une décision peut au contraire demander qu’une clé soit supprimée :

labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if {
some id, node in input.graph.nodes
node.labels["draft.example.com/scratch"]
}

Une politique nomme le label au lieu d’écrire l’instruction de modification que le build applique, et la raison mérite d’être connue : l’instruction désigne un label par un chemin, et une clé de label Aggrega contient couramment un /, qui est le séparateur de chemin — si bien qu’un chemin écrit à la main désignerait un emplacement imbriqué au lieu d’un seul label. Le moteur désigne le label que nomme la décision, si bien que l’échappement est écrit une seule fois au lieu de l’être dans chaque politique, et qu’une politique reste lisible comme un énoncé sur des labels plutôt que sur des chemins.

Une décision ne peut que modifier un label. Chaque instruction qu’émet le moteur désigne un label sur un nœud, si bien qu’une politique n’a aucun moyen d’exprimer une modification du Component d’un nœud, de sa version résolue, de l’ensemble des nœuds ou d’une valeur de label qui n’est pas une chaîne. Une décision qui nomme un nœud que le build n’a pas, ou qui supprime un label que le nœud ne porte pas, est refusée par le build avec un message qui nomme l’instruction — jamais ignorée en silence.

../examples/policy-label-transform/ rattache une telle politique à côté des deux plugins de tagging intégrés, ainsi qu’un verdict sur le graphe qui lit les labels qu’ils écrivent. Ce que chacun de ces plugins lit et écrit se trouve sur Les plugins de tagging intégrés.

Injecter des annotations

Au rôle qui injecte les annotations, une politique collecte une décision par annotation sous annotations, en nommant la cible par la coordonnée que porte la cible elle-même, ainsi que la clé et sa valeur :

package tagging
import rego.v1
annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
} if {
some target in input.targets
not target.annotations["backup.example.com/schedule"]
}

Les noms de champs qu’écrit une décision sont les noms de champs sous lesquels elle a lu ses cibles, si bien que la convention peut s’apprendre à partir de la seule charge utile. Lire input.binding_keys permet à une politique de n’injecter que des clés pour lesquelles le Manifest a enregistré une signification — ce sont celles qui s’étendent en un rattachement de Feature.

La valeur d’une décision est une valeur que vous pourriez écrire vous-même sur cette annotation : une chaîne, ou un objet de sous-clés. Une liaison qui achemine une seule sous-clé prend une chaîne ; une liaison qui en achemine plusieurs prend un objet qui nomme chacune d’elles, exactement comme un opérateur l’écrit dans la Release :

annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "feature.aggrega.ai/monitoring",
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
some target in input.targets
not target.annotations["feature.aggrega.ai/monitoring"]
}

Le build lit une valeur injectée exactement comme il lit la même valeur écrite dans la Release, si bien qu’elle s’étend de la même façon et est vérifiée de la même façon par rapport à la Feature liée. Le moteur conserve les clés d’un objet triées, si bien que les sous-clés atteignent le build dans l’ordre trié. Une valeur de toute autre forme — null, une liste, un nombre, un booléen ou un objet sans sous-clés — est refusée par le build, qui nomme l’injection : le rôle ajoute des annotations, et null ou un objet vide se lit comme le renoncement qu’un auteur écrit pour en supprimer une. Une décision qui nomme un composant que la charge utile ne porte pas est refusée de la même façon, en nommant la coordonnée et l’annotation.

Lorsque le build refuse une annotation injectée pour la façon dont elle est acheminée ou pour ce qu’elle porte — une chaîne fournie à une liaison qui achemine plusieurs sous-clés, une valeur de sous-clé que le schéma de la Feature liée n’admet pas, ou une sous-clé acheminée par le pilier values, qu’une annotation côté Release ne peut pas utiliser —, le refus nomme le plugin qui l’a injectée et le rôle de gouvernance auquel il est rattaché, si bien que la valeur est reliée à la politique qui l’a décidée plutôt qu’à une ligne de la Release que personne n’a écrite.

../examples/policy-annotation-transform/ rattache une telle politique, qui injecte une chaîne sous une liaison et un objet de sous-clés sous une autre, et produit par le build les mêmes fichiers qu’une Release qui écrit ces annotations à la main.

Rattacher un ensemble complet de politiques sous forme d’une seule archive

Un ensemble de politiques est rattaché fichier par fichier, ou sous forme d’une seule archive contenant ensemble ses fichiers de politiques et ses documents de données — la forme que construit une chaîne d’outils Rego. Le contenu d’un fichier rattaché parvient au guest sous forme de texte, et une archive compressée est faite d’octets arbitraires plutôt que de texte, si bien qu’une archive est rattachée encodée en base64, avec un nom qui se termine par .base64 :

Terminal window
tar czf bundle.tar.gz policy.rego data.json
base64 -w0 bundle.tar.gz > bundle.tar.gz.base64
with:
sources:
- ./policies/bundle.tar.gz.base64

Le nom est ce qui marque un fichier comme une archive plutôt que comme du texte de politique, ce qui fait du choix une déclaration explicite de l’opérateur lui-même : une archive endommagée est alors signalée comme une archive endommagée, en nommant le fichier et l’étape qui a échoué, au lieu d’être lue comme un fichier de politique qui ne s’analyse pas. Encoder l’archive est une étape que l’opérateur ajoute après que sa chaîne d’outils l’a construite.

À l’intérieur de l’archive, chaque membre .rego est un module de politique et chaque membre data.json ou data.yaml est un document de données imbriqué sous le répertoire où il se trouve — un fichier limits/data.json contenant {"max": 3} est lu par une politique comme data.limits.max. Les membres de tout autre type sont portés par l’archive pour sa propre chaîne d’outils et ne sont pas des entrées de politique.

Une archive qui ne peut pas être ouverte est un échec qui nomme le fichier rattaché : un encodage qui ne se décode pas, un flux qui ne se décompresse pas, une archive tronquée, un fichier de données qui ne se lit pas, ou une archive ne contenant aucune politique. Aucun de ces cas ne donne un ensemble de politiques vide, car un ensemble de politiques vide n’atteint aucune décision — et « l’archive était illisible » ne doit jamais être impossible à distinguer de « la politique a autorisé le build ».

Écrire une politique pour le moteur CEL

Le moteur évalue du CEL écrit par l’opérateur entièrement à l’intérieur du guest, quel que soit celui des quatre rôles auquel il est rattaché. Son identité de catalogue est le nom nu cel sous pluginType: governance — la coordonnée governance/cel — et sa version est la release du compilateur qui le livre. Le rattacher deux fois, à deux rôles, avec deux fichiers de politique différents, est la façon dont un seul moteur couvre deux moments du même build.

plugins:
governance:
- uri: governance/cel:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.cel
settings:
max_nodes: 20

Une politique s’adresse à toute la charge utile par un seul nom, input, si bien que les noms qu’elle lit sont ceux que leur donne le format de transmission : le graphe de build à input.graph, les chemins de routage énumérés à input.precalculated_paths, les fichiers rendus à input.artifacts, les cibles d’annotation à input.targets. Ces chemins par rôle sont ceux présentés dans le tableau de Ce qu’expose la charge utile de chaque rôle ci-dessus, et ils sont identiques pour les deux moteurs — un seul format de transmission, lu sous un seul nom racine.

Les fichiers propres du rattachement se trouvent à input.sources et ses paramètres à input.settings, si bien qu’un seuil fourni par l’opérateur se lit input.settings.max_nodes. Il n’y a pas de second document à apprendre : les paramètres font partie de input comme tout le reste. Les deux sont toujours présents en tant que valeur — les paramètres sont l’objet vide à chaque rôle lorsque le rattachement n’en déclare aucun — si bien qu’une expression qui y accède n’a pas à se prémunir contre leur absence, et savoir si un paramètre donné a été configuré est un test sur sa clé : has(input.settings.max_nodes).

Les deux formes écrites, et le nom de fichier qui choisit entre elles

Une politique est rattachée sous l’une de deux formes, et le nom du fichier dit laquelle :

Le nom du fichier se termine parLu comme
.celune expression, évaluée telle quelle
.yaml ou .ymlun document de règles — une liste de règles
toute autre choseune expression

Le nom est toute la règle. Aucun paramètre ne sélectionne une forme, et le texte du fichier n’est pas examiné pour en deviner une — il ne pourrait de toute façon pas répondre à la question, car la valeur la plus externe d’une expression est une table, tout comme celle d’un document de règles, ce qui rend les deux formes impossibles à distinguer par leur structure.

La règle vaut donc dans les deux sens, et les deux erreurs sont refusées plutôt que mal lues. Un document de règles nommé policy.cel est refusé, parce qu’une liste de règles YAML n’est pas une expression ; une expression nommée policy.yaml est refusée, parce qu’une expression n’est pas une liste de règles. Chaque refus nomme le fichier. Renommer le fichier est la correction dans les deux sens.

Un ensemble de politiques compte autant de fichiers qu’il lui en faut, et les deux formes se mélangent librement au sein d’un même rattachement.

Une expression, dans un fichier nommé .cel

Un langage d’expressions n’a pas de noms de règles sous lesquels collecter les décisions, si bien que les décisions sont la valeur que produit l’expression : une table qui va de la clé de décision à ce que cette clé collecte. À un rôle de verdict, une clé collecte les messages atteints sous elle ; à un rôle qui façonne le build, elle collecte les décisions à appliquer.

{
"deny": input.graph.spec.nodes
.filter(n, input.graph.spec.nodes[n].resolved_version == "latest")
.map(n, "component " + n + " tracks the latest version; pin it"),
"warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],
}

Une clé que le fichier omet n’a atteint aucune décision à cet endroit, si bien qu’un fichier n’a pas besoin de nommer chaque clé — et chaque rôle ne lit que la clé qui le concerne, si bien qu’un même ensemble de politiques peut servir un rôle de verdict et un rôle qui façonne le build à partir des mêmes fichiers. Une clé porte une liste de ce qu’elle collecte, un seul élément, ou la valeur null pour aucun.

Une expression dont l’évaluation donne autre chose qu’une table est refusée, avec un message qui nomme la forme à écrire. Un simple size(input.graph.spec.nodes) <= 5 est l’erreur à prévoir : c’est un booléen, et lire false comme un arrêt reviendrait à inventer un message que l’auteur n’a jamais écrit.

Un document de règles, dans un fichier nommé .yaml ou .yml

Un document de règles est une liste de règles, chacune nommant la clé de décision qu’elle atteint, l’expression qui décide si elle est atteinte, et ce qui est rapporté quand elle l’est :

- key: deny
expression: size(input.graph.spec.nodes) > 20
message: this build declares a lot of components
- key: warn
expression: has(input.settings.max_nodes)
message: a component ceiling is configured for this environment

Ce qu’une règle rapporte suit la clé de décision qu’elle atteint, exactement comme dans une expression. Du texte est le message que porte un verdict. Un mapping, ce sont les champs de l’unique décision que lit un rôle qui façonne le build :

- key: labels
expression: input.compilation_context.environment == "production"
message:
node: app
key: compliance.example.com/tier
value: gold

Lequel des deux une règle écrit est décidé par la règle seule — aucun paramètre ne le sélectionne — et une règle qui écrit le mauvais pour sa clé est refusée, nommément.

Un détail YAML à connaître avant qu’il ne vous joue un tour : une expression qui commence par un guillemet double doit être mise entre guillemets pour le lecteur du document, car une valeur qui commence par " est lue comme un scalaire entre guillemets plutôt que comme un texte commençant par un guillemet.

- key: annotations
expression: '"backup.example.com/schedule" in input.binding_keys'
message:
boundary_path: main
component_name: app
annotation_key: backup.example.com/schedule
annotation_value: nightly

Un document de règles est lu comme l’expression qu’il représente avant que quoi que ce soit ne soit évalué. Chaque règle devient sa clé de décision, qui porte ce que la règle rapporte quand l’expression est vraie et rien quand elle ne l’est pas, et les règles qui partagent une clé sont réunies. Ainsi un seul évaluateur exécute les deux formes, et un document de règles décide exactement ce que décide l’expression qu’il représente — à chaque rôle, verdicts et décisions qui façonnent le build confondus. Deux conséquences en découlent. Un document et l’expression écrite à la main qu’il représente atteignent les mêmes décisions, parce qu’ils sont la même évaluation. Et les règles d’ordre décrites ci-dessous sont celles de la forme évaluée plutôt que du document — les règles d’un document ne sont pas rapportées dans l’ordre où elles ont été écrites.

Quelle forme convient — elles ne sont pas interchangeables

Les deux formes passent par un seul évaluateur, si bien qu’aucune n’est plus rapide ni plus fiable que l’autre. Ce qui diffère, c’est ce que chacune peut dire, et comme deux formes sont deux choses à apprendre, la répartition mérite d’être énoncée clairement plutôt que laissée au goût de chacun. Choisissez selon ce que la règle rapporte.

  • Un document de règles, quand ce qui est rapporté est fixe. Le message ou la décision est écrit une fois, à côté de l’expression qui l’atteint, et le fichier se lit comme une liste de gardes. C’est la forme la plus courte pour « si ceci est vrai, dire exactement ceci ».
  • Une expression, quand ce qui est rapporté nomme ce qu’elle a trouvé. Une seule expression filtre les composants d’un build et produit un message — ou une décision — par composant, si bien qu’un lecteur obtient component payments tracks the latest version; pin it pour chaque élément fautif plutôt qu’une phrase sur un nombre.

Cette seconde tâche est celle qu’un document de règles ne peut pas accomplir : chacune de ses règles porte un seul rapport, écrit à l’avance, si bien qu’elle n’a rien à dire sur le composant qui l’a déclenchée. Opter pour la forme document puis vouloir le nom de l’élément fautif dans le message est le chemin qui finit par la réécriture de la règle en expression, si bien qu’il vaut la peine de trancher cette question dès le départ.

Ce qu’une expression peut dire

Les expressions qu’évalue ce moteur utilisent les compréhensions filter, map et exists, + sur les chaînes et sur les listes, size, in, startsWith, string(), l’opérateur conditionnel, et une liste indexée par un entier calculé. Elles n’offrent pas les fonctions d’extension qu’ajoutent certains environnements CEL : join, split, substring, indexOf, flatten, cel.bind et lists.range sont chacune refusées comme référence non déclarée, et une compréhension prend une seule variable, si bien qu’une forme à deux variables telle que exists(i, v, …) est refusée de la même façon. Un refus est une défaillance de build qui nomme le fichier et la référence :

policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'

Trois conséquences façonnent une règle qui parcourt un chemin :

  • Il n’existe aucun moyen de nommer une valeur intermédiaire. Une sous-expression utilisée deux fois s’écrit deux fois, ou se lie en appliquant un map à une liste d’un seul élément : [value].map(name, …)[0] évalue son corps une fois avec name lié à value.
  • Il n’existe aucun moyen de parcourir les positions d’une liste. Une règle qui compare les composants d’un chemin par position prend les positions dans ses paramètres — une liste positions telle que [0, 1, 2, …] — et indexe le chemin à chacune d’elles, si bien qu’elle doit se prémunir contre un chemin plus long que la liste elle-même, en arrêtant le build sur un tel chemin, plutôt que de le lire en partie.
  • Une clé de décision collecte des messages, pas des listes de messages. Une expression qui produit une liste de messages par chemin est refusée sous une clé de décision — la défaillance indique qu’elle a collecté une valeur de type liste plutôt qu’un message — si bien qu’une règle produit un enregistrement par chemin et construit le message à partir de celui-ci. Et un message que l’expression produit deux fois est rapporté deux fois : le tri décrit ci-dessous ordonne ce qu’une clé a collecté, et ne supprime pas une répétition.

../examples/policy-data-class-route/ contient une règle CEL écrite en tenant compte de ces trois conséquences, à côté de la même règle pour le moteur Rego.

Clés de décision et niveaux de gravité

Les clés de décision, la correspondance par défaut avec les niveaux de gravité et le paramètre translation qui les renomme sont les mêmes que pour le moteur Rego — voir Une politique collecte ses décisions sous une clé de décision plus haut. Par défaut, deny est rapporté comme halt, warn comme warn et audit comme info ; une translation déclarée remplace cette correspondance par défaut au lieu de l’étendre, et l’ordre qu’elle déclare est l’ordre dans lequel les verdicts sont rapportés.

Les deux moteurs déclarent le même schéma de paramètres pour celui-ci, si bien qu’un bloc translation signifie la même chose quel que soit le langage qui exprime les décisions, et qu’un bloc mal formé est refusé avant l’exécution de toute politique.

À un rôle qui façonne le build, la clé est fixée plutôt que mise en correspondance : labels au rôle qui façonne les labels, annotations au rôle qui injecte les annotations.

Ordre : trié au sein d’une clé, et un ordre total sur les décisions

Les messages sous une même clé de décision sont rapportés dans l’ordre trié. Cela fait partie du contrat plutôt que d’un choix de présentation, et la raison mérite d’être retenue : une compréhension sur une table — .filter(...) et .map(...) sur input.graph.spec.nodes, qui est la façon la plus naturelle d’écrire une règle par composant — parcourt cette table dans un ordre que l’évaluateur ne fixe pas. Livrée à elle-même, une entrée identique rapporterait les mêmes messages dans une séquence différente à chaque build. Le tri supprime cela.

Il en découle deux choses qu’il est facile de prendre pour des bugs et qui n’en sont pas :

  • Les règles d’un document de règles sont elles aussi rapportées triées, et non dans l’ordre où elles ont été écrites — parce que le document est évalué comme l’expression qu’il représente, et que le tri s’applique à ce qu’une clé a collecté.
  • Une liste écrite à la main est triée elle aussi. Une clé portant ["second", "first"] rapporte first avant second. Rien dans un résultat évalué ne distingue une liste que l’auteur a saisie d’une liste produite par une compréhension, si bien qu’il n’existe aucun ordre de l’auteur à préserver.

D’une clé à l’autre, l’ordre est l’ordre déclaré de translation. D’un fichier à l’autre, c’est l’ordre des noms de fichiers, car les sources d’un rattachement arrivent triées par nom plutôt que dans l’ordre où le rattachement les énumère.

À un rôle qui façonne le build, le même raisonnement s’applique aux décisions elles-mêmes, et l’ordre est plus fort : les décisions sont rapportées dans l’ordre croissant de tout ce qu’elles nomment, ce qui est un ordre total sur ce qu’une décision peut exprimer — le nœud, puis la clé du label, puis le fait que le label soit ajouté ou supprimé, puis la valeur ; et pour une injection, la frontière, puis le composant, puis la clé d’annotation, puis sa valeur. Une modification des labels ou des annotations atteint la sortie rendue, si bien qu’un ordre arbitraire signifierait qu’une entrée identique serait rendue différemment d’un build à l’autre.

Façonner les labels

Au rôle qui façonne les labels, une politique collecte une décision par label sous labels, en nommant le nœud, la clé du label et la valeur que prend le label :

{
"labels": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server")
.map(n, {
"node": n,
"key": "compliance.example.com/tier",
"value": input.compilation_context.environment == "production" ? "gold" : "bronze",
}),
}

Définir une clé déjà présente remplace sa valeur. Une décision peut au contraire demander qu’une clé soit supprimée, en indiquant op comme remove :

{
"labels": input.graph.nodes
.filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels)
.map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),
}

Une décision seule n’a pas besoin d’une liste autour d’elle, et un fichier qui ne nomme aucune clé labels ne décide d’aucun label.

Une politique nomme le label au lieu d’écrire l’instruction de modification que le build applique, pour la raison donnée dans la section sur le façonnage des labels du moteur Rego : une clé de label Aggrega contient couramment un /, et un chemin écrit à la main désignerait un emplacement imbriqué au lieu d’un seul label. Le moteur désigne le label que nomme la décision.

Lire un label qu’un nœud pourrait ne pas porter est un échec plutôt qu’une valeur vide, et c’est pourquoi le second exemple vérifie si la clé est présente avant de la lire. C’est la règle propre au langage d’expressions concernant la lecture d’une clé absente, et elle est bruyante : une politique qui cherche un label qu’aucun nœud ne porte signale qu’elle n’a pas pu être évaluée au lieu de ne rien décider discrètement.

Une décision ne peut que modifier un label. Une décision qui nomme un nœud que le build n’a pas, ou qui supprime un label que le nœud ne porte pas, est refusée par le build avec un message qui nomme l’instruction — jamais ignorée en silence.

N’atteignez qu’une seule décision par nœud et par clé de label. Une règle qui peut produire deux valeurs différentes pour le même label sur le même nœud est sous-spécifiée : résolvez la valeur à l’intérieur de l’expression — avec une condition, ou avec un filtre qui n’admet qu’une branche — plutôt que d’émettre les deux décisions.

../examples/policy-label-transform/ montre de bout en bout le rôle qui façonne les labels, avec sa politique écrite pour le moteur Rego.

Injecter des annotations sous une clé enregistrée

Au rôle qui injecte les annotations, une politique collecte une décision par annotation sous annotations, en nommant la cible par la coordonnée que porte la cible elle-même, ainsi que la clé et sa valeur :

{
"annotations": input.targets
.filter(t, "backup.example.com/schedule" in input.binding_keys)
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
}),
}

Les noms de champs qu’écrit une décision sont les noms de champs sous lesquels elle a lu ses cibles, si bien que la convention peut s’apprendre à partir de la seule charge utile. Lire input.binding_keys permet à une politique de n’injecter que des clés pour lesquelles le Manifest a enregistré une signification — ce sont celles qui s’étendent en un rattachement de Feature. Chaque champ est obligatoire : une annotation avec une clé vide ou un nom de composant vide n’est pas quelque chose qu’une politique entendait demander. La frontière sous laquelle se trouve un composant peut légitimement être nommée par la chaîne vide, si bien que ce champ doit être présent mais peut être vide.

La valeur est une valeur que vous pourriez écrire vous-même sur cette annotation : une chaîne, ou une table de sous-clés, ce qui alimente une liaison qui achemine plusieurs sous-clés à la fois — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Le moteur écrit les sous-clés d’une table dans l’ordre trié, puisque le langage d’expressions ne fixe aucun ordre pour une table, et transmet la valeur telle que l’expression l’a produite ; une valeur que le modèle JSON ne peut pas contenir — des octets, un horodatage, une durée — est refusée plutôt que convertie en texte. Le build lit ensuite la valeur exactement comme il lit la même valeur écrite dans la Release, et refuse null, une liste, un nombre, un booléen ou une table vide, en nommant l’injection. Deux décisions pour un même composant et une même clé avec des valeurs différentes sont ordonnées selon le JSON de la valeur. Les annotations d’une cible portent chaque valeur existante telle qu’elle est écrite — une chaîne, une table, ou null pour un renoncement — si bien que tester "feature.aggrega.ai/monitoring" in t.annotations trouve une clé quelle que soit sa valeur.

Une décision qui nomme un composant que la charge utile ne porte pas est refusée par le build, qui nomme la coordonnée et l’annotation. Lorsque le build refuse une annotation injectée pour son acheminement, pour les valeurs de ses sous-clés ou pour son pilier, le refus nomme le plugin qui l’a injectée et le rôle auquel il est rattaché. Comme pour les labels, n’atteignez qu’une seule décision par composant et par clé d’annotation, en résolvant la valeur à l’intérieur de l’expression plutôt que d’émettre deux décisions pour une même clé.

../examples/policy-annotation-transform/ montre de bout en bout le rôle qui injecte les annotations, avec sa politique écrite pour les deux moteurs.

Lorsqu’une politique ou une décision ne peut pas être lue

Une politique que le moteur ne peut pas lire, ne peut pas évaluer, ou qui produit autre chose que des décisions dans la forme documentée fait échouer le build au lieu de renvoyer un verdict ou une modification. L’échec est signalé comme une défaillance de build qui nomme le fichier et, lorsque la défaillance appartient à une partie du fichier, la position en son sein — délibérément distincte d’un verdict halt, afin que « cette politique n’a pas pu être évaluée » ne soit jamais confondu avec « cette politique autorise le build ».

Pour une expression, cela couvre une source qui ne s’analyse pas — signalée avec la ligne et la colonne propres à l’analyseur et un caret sous la position fautive — et une source dont l’évaluation donne autre chose qu’une table qui va de la clé de décision à ce que cette clé collecte.

Pour un document de règles, cela couvre un texte qui n’est pas une liste de règles, une liste sans aucune règle, une règle à laquelle il manque un champ ou qui en porte un vide, un champ que la forme ne définit pas, un rapport qui n’est ni du texte ni un mapping de texte vers du texte, et une expression qui ne peut pas être lue. Une défaillance qui appartient à une règle nomme la position de cette règle — comptée à partir de un, comme un auteur compte son propre fichier — et sa clé de décision. Une règle dont l’expression ne s’analyse pas est refusée avant l’évaluation, si bien que le caret tombe à l’intérieur de l’expression que l’auteur a écrite plutôt qu’à une position dans un texte traduit qu’il n’a jamais vu.

Pour une décision à un rôle qui façonne le build, cela couvre un message là où une décision est attendue, une coordonnée manquante, et un champ que la forme de décision de ce moteur ne définit pas. Ce dernier cas mérite d’être signalé à part : un annotation_valu mal orthographié est refusé, pas ignoré, si bien que l’erreur est signalée au lieu d’injecter discrètement une valeur vide et de laisser un build qui aboutit sans la modification. Chacun de ces refus nomme le fichier et se termine en nommant ce qu’une décision de ce type doit nommer.

Adaptateurs de politiques pour l’étape de rendu

Un adaptateur pour l’étape de rendu raisonne sur la sortie rendue du build plutôt que sur son graphe IR. La charge utile de rendu porte les artefacts émis — chacun avec son chemin de sortie et son contenu rendu et, lorsqu’ils s’appliquent, le format dans lequel il a été rendu et une vue structurée analysée de celui-ci — ainsi que les sources et les paramètres propres du rattachement, chacun là où le rattachement le déclare. Un adaptateur lit ce contenu pour la forme de sortie qu’il cible, évalue une politique sur le résultat structuré et fait correspondre l’issue à des verdicts halt / warn / info. Comme la charge utile ne nomme aucune forme de sortie qui lui soit propre, un seul modèle d’adaptateur sert n’importe quelle cible de rendu ; une nouvelle forme de sortie est un nouvel adaptateur, pas une modification de l’hôte.

Chaque adaptateur pour l’étape de rendu est un adaptateur au sens décrit plus haut : il parle l’ABI d’Aggrega vers l’extérieur et absorbe en son sein un format propre à la cible ou le contrat d’un moteur de politiques étranger, si bien que le compilateur reste exempt de toute logique de format de sortie ou de politique. Les moteurs Rego et CEL du compilateur servent directement le rôle render-verdict ; au-delà, deux adaptateurs de référence pour l’étape de rendu sont livrés comme exemples complets parmi les exemples Rust du kit de développement de plugins, un par forme de sortie courante.

../examples/policy-render-verdict/ rattache une règle à render-verdict sur la sortie de quatre cibles — des objets Kubernetes, un fichier Docker Compose, une configuration racine Terraform et un modèle CloudFormation — écrite une fois pour chaque moteur du compilateur, et vérifie que la violation implantée dans chaque cible provoque un arrêt et que son cas témoin passe.

Pour écrire votre propre adaptateur, à ce rôle ou à n’importe quel autre, partez du squelette d’adaptateur de gouvernance que fournit chaque kit de développement de plugins : Écrire votre propre plugin de gouvernance le mène du squelette jusqu’à un build qu’il refuse.

Sortie YAML, JSON et HCL Terraform — l’adaptateur de rendu Rego de référence

L’adaptateur de rendu Rego de référence exécute du Rego fourni par l’opérateur sur toute sortie de rendu YAML ou JSON, ainsi que sur la sortie HCL native de Terraform. C’est un exemple complet de la forme de l’étape de rendu : le même évaluateur Rego natif Wasm que le moteur du compilateur, et la même convention de collecte deny / warn / audit mise en correspondance avec les trois mêmes niveaux de gravité de verdict, en raisonnant sur des fichiers rendus plutôt que sur le graphe de build.

Il est indépendant de la forme de sortie pour toutes les cibles YAML/JSON. L’adaptateur analyse le contenu de chaque artefact comme un ou plusieurs documents YAML ou JSON — YAML est un sur-ensemble de JSON, si bien qu’un modèle JSON tel qu’une pile CloudFormation passe par le même analyseur — et expose à la politique les documents analysés à côté du contenu brut. Une politique raisonne sur la sortie de rendu structurée de toute cible de ce type avec du Rego ordinaire : input.artifacts[_].documents[_] donne les documents analysés (les services d’un fichier Docker Compose, les Resources d’un modèle CloudFormation), input.artifacts[_].content donne le texte brut, et l’objet settings du rattachement est le document data de Rego. Une politique qui exige un registre approuvé sur une sortie Docker Compose, par exemple, refuse tout service dont l’image ne porte aucun préfixe de registre.

L’adaptateur raisonne aussi sur la sortie de rendu HCL native de Terraform. Un fichier .tf natif n’est ni du YAML ni du JSON, si bien que l’adaptateur le projette dans le même objet canonique que celui que donne déjà l’analyse d’un fichier Terraform-JSON (.tf.json) : une politique lit un attribut de ressource à input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — pour une instance RDS, input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — de la même façon quelle que soit la forme Terraform émise par le compilateur. Les types d’attributs sont préservés (un nombre reste un nombre, un booléen un booléen), et une expression Terraform non résolue reste une chaîne sous sa forme ${ ... }. Les contenus Terraform-JSON (.tf.json, .auto.tfvars.json) passent sans changement par le chemin YAML/JSON, et un fichier de modèle Terraform (.tftpl) — du texte de modèle plutôt qu’une configuration autonome — n’est pas projeté et fait apparaître parse_error comme tout contenu non structuré.

Cette liste indique ce qu’accepte l’analyseur de l’adaptateur, pas ce qu’émet le compilateur. Les deux ne sont pas le même ensemble, et un fichier de variables chargé automatiquement est le cas où ils diffèrent : le compilateur n’émet une telle surcouche sur aucun chemin — les entrées d’un module référencé sont les arguments du bloc de module de ce composant dans la configuration racine de la frontière — si bien que cette forme n’atteint la vue d’une politique que lorsqu’un module vendorisé en livre une qui lui est propre, que le chemin des modules référencés copie tel quel dans la sortie. Une politique écrite en s’attendant à ce que le compilateur en produise une ne se déclenchera jamais.

Lorsque le contenu d’un artefact ne s’analyse pas, l’adaptateur ne le laisse pas passer discrètement : il conserve le contenu brut, n’expose aucun document analysé pour cet artefact, et enregistre le message de l’analyseur sous input.artifacts[_].parse_error, si bien qu’une politique peut arrêter explicitement le build sur un artefact mal formé. Comme pour le moteur Rego du compilateur, une politique qui appelle une fonction intégrée que l’évaluateur embarqué n’implémente pas échoue bruyamment — une défaillance qui nomme le plugin, jamais une autorisation silencieuse.

Sortie Kubernetes — l’adaptateur de rendu Kubewarden

L’adaptateur de rendu Kubewarden exécute des politiques d’admission de style Kubewarden sur des manifestes Kubernetes rendus. Il absorbe en son sein le contrat d’admission review de Kubernetes : une politique Kubewarden reçoit une requête enveloppant un seul objet et renvoie une réponse d’acceptation ou de rejet. À l’étape de rendu, la sortie du build est déjà un ensemble de ressources Kubernetes, ce qui fait de cette étape l’endroit naturel pour exécuter une politique en forme d’admission. Pour chaque objet rendu, l’adaptateur dérive les champs d’admission de l’objet analysé lui-même, enveloppe l’objet dans une requête en forme d’admission review à l’intérieur du guest, exécute la politique et fait correspondre la réponse à un verdict : un rejet devient un verdict ; une acceptation n’émet rien. La politique de référence fournie est une règle qui exige un label — chaque objet doit porter une clé de label nommée par settings — un modèle courant de Kubewarden.

Portée commune aux adaptateurs pour l’étape de rendu

  • Étape de rendu, une forme de sortie par adaptateur. Un adaptateur pour l’étape de rendu raisonne sur des artefacts rendus, pas sur le graphe IR, et cible la forme de sortie qu’il analyse — YAML/JSON et HCL natif de Terraform pour l’adaptateur de rendu Rego de référence, objets Kubernetes pour l’adaptateur Kubewarden. Une politique pour l’étape du graphe, ou une politique sur une forme de sortie qu’aucun adaptateur fourni n’analyse, est un guest différent.
  • Validation uniquement. Un adaptateur pour l’étape de rendu accepte ou rejette ; il ne renvoie jamais un objet modifié. L’objet modifié d’une politique de mutation est ignoré — le compilateur ne réécrit jamais la sortie rendue à partir d’un verdict de politique. Une politique décide ; elle ne modifie pas.

Rattacher une politique

Un opérateur rattache un plugin de gouvernance via la liste plugins.governance dans la configuration de l’espace de travail (.aggrega-config.yaml). Chaque entrée nomme un plugin, le role auquel il est rattaché et, éventuellement, le canal with qui fournit ses règles et ses paramètres réglables :

plugins:
governance:
- uri: <resolvable-plugin-reference>
role: ir-verdict
with:
sources:
- ./policies/replicas.rego
settings:
max_replicas: 3

L’uri se résout vers le plugin. L’hôte lit chaque fichier de sources au moment du build et en remet les octets au guest, et transmet settings tel quel. Un build sans aucun plugin de gouvernance rattaché exécute le socket comme une opération sans effet, si bien que le rattachement est purement additif pour un espace de travail.

Un plugin qui sert plusieurs rôles est rattaché une fois par rôle, chaque rattachement avec ses propres règles et ses propres paramètres :

plugins:
governance:
- uri: governance/rego:<version>
role: label-transform
with:
sources:
- ./policies/tagging.rego
- uri: governance/rego:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.rego
settings:
translation:
- key: blocked
severity: halt

Quelle version nomme un rattachement. Un uri nomme une entité Plugin — la coordonnée <pluginType>/<name> et, après les deux-points, une version — et la version participe à la résolution. Pour les deux moteurs compilés dans la CLI, l’entité provient de l’un de deux endroits. Chaque release du compilateur publie les entités Plugin de governance/rego et governance/cel à sa propre version, et le catalogue de la bibliothèque standard les porte, chacune à la version de la release qui l’a publiée ; un espace de travail les lit depuis les répertoires de catalogue qu’il liste. Le binaire aggrega porte une entité de chacun, à la version de sa propre release et à aucune autre. Un rattachement qui nomme une version que ni l’un ni l’autre ne porte, et qu’aucun pull n’a récupérée dans le cache de contenu, arrête le build avec E0137, en nommant la référence.

Un rattachement nomme donc une version que porte le catalogue lu par l’espace de travail. Cette version se résout depuis le catalogue également sous une release d’aggrega autre que la sienne, tandis qu’une version que seul le binaire porte — celle de sa propre release — ne se résout qu’avec cette release, à un rôle de verdict comme à un rôle de transformation. À un rôle de transformation, le pull épingle dans le fichier de verrouillage la version qu’il a résolue, et refuse avec E0103 une version que ne portent ni un catalogue lu par l’espace de travail ni le binaire. La version sélectionne l’entité Plugin, qui enregistre les exports et les limites d’exécution du plugin, et non le moteur : une fois la référence résolue, le moteur qui s’exécute est celui compilé dans le binaire qui exécute le build, car les plugins intégrés au binaire sont le premier endroit d’où le module d’un plugin est lu. Un plugin de gouvernance que l’espace de travail déclare lui-même — une entité Plugin dans son propre répertoire de catalogue, son .wasm à côté — est nommé à la version que cette entité enregistre.

Chaque rôle sélectionne une fonction d’entrée par défaut — verdict_ir pour le rôle qui juge le graphe, verdict_render pour le rôle qui juge les artefacts rendus, mutate pour le rôle qui façonne les labels, transform_annotations pour le rôle qui injecte les annotations — et un rattachement peut diriger un rôle vers un autre export avec function:. L’hôte refuse un envoi vers un export que le guest n’a pas déclaré dans son auto-description describe(), si bien qu’un rattachement qui nomme un rôle que son guest ne sert pas est signalé par son nom, avant que le guest ne s’exécute, plutôt que de ne rien faire en silence.

function: nomme un export du plugin que nomme l’uri. Un rattachement dans un rôle de verdict — ir-verdict ou render-verdict — qui nomme une function: et aucun uri: nomme une fonction sur aucun plugin, si bien que la configuration est refusée dès sa lecture, sous E0224, en nommant le fichier et la place de l’entrée dans sa liste : ajoutez l’uri du plugin qui exporte la fonction.

La liste plugins.governance a un pendant additif, plugins.governance_append : les entrées du pendant sont concaténées à la liste governance résolue à chaque couche de configuration, si bien qu’un espace de travail ou une configuration globale compose les rattachements de politiques plutôt que de masquer une liste de base.

La surcouche propre à la CI

À côté du .aggrega-config.yaml rédigé à la main, un pipeline automatisé peut posséder un fichier de surcouche distinct, .aggrega-config-append-ci.yaml. Il existe pour qu’un pipeline puisse rattacher des politiques (ou une autre configuration à valeurs de liste) qu’il contrôle sans jamais modifier la configuration de base rédigée à la main par le développeur — le pipeline peut écraser entièrement son propre fichier de surcouche.

La surcouche est strictement additive. Elle est validée par rapport au même schéma de configuration que le fichier de base, et pour chaque champ à valeurs de liste, ses entrées sont concaténées à la liste résolue. Elle ne peut qu’ajouter : elle ne peut pas retirer une entrée de base ni remplacer une valeur scalaire de base — une clé scalaire ou de table qu’elle porte n’a aucun sens additif et est ignorée (et nommée dans un avertissement de résolution) plutôt qu’appliquée. Et elle n’ancre jamais la racine d’un espace de travail : seul un .aggrega-config.yaml portant un bloc workspace: le fait, si bien que déposer la surcouche dans un répertoire ajoute des rattachements sans changer l’endroit où commence l’espace de travail.

Cela donne à un pipeline un point d’articulation propre pour imposer une politique à l’échelle de l’organisation : le pipeline dépose un .aggrega-config-append-ci.yaml nommant les plugins de politique obligatoires, et ces rattachements se fusionnent par-dessus ce que le développeur a rédigé, jamais à sa place.

# .aggrega-config-append-ci.yaml — owned by the pipeline, additive only
plugins:
governance_append:
- uri: <organization-policy-plugin-reference>
role: render-verdict
with:
settings:
required_label: app.kubernetes.io/name

examples/policy-org-overlay/ construit un espace de travail avec le rattachement d’une équipe, celui d’une organisation ajouté via le governance_append d’un fichier de configuration global, et celui d’un pipeline ajouté via cette surcouche, et vérifie ce que chaque combinaison affiche et si elle se termine.

Tester une politique avant qu’elle ne bloque un build

Une règle Rego qui nomme un chemin que la charge utile de son rôle ne porte pas n’est pas une erreur : le chemin est indéfini, la règle n’est jamais vraie, et le build se termine comme si la politique l’avait autorisé. Une nouvelle politique mérite donc halt en trois étapes : la rattacher à un niveau de gravité qui signale sans arrêter, vérifier chaque chemin qu’elle nomme par rapport à la charge utile que reçoit son rôle, et lire ce qu’elle signale sur les builds qu’elle jugera.

Les commandes ci-dessous s’exécutent dans une copie de examples/policy-org-overlay/ dont le .aggrega-config.yaml rattache une nouvelle politique à la place de celle de l’équipe. Elle est censée refuser un magasin de données qui fonctionne avec la haute disponibilité désactivée, et sa règle a été copiée d’une politique qui façonne les labels :

package datastores
import rego.v1
deny contains msg if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v is a datastore running with high availability off", [id])
}

Rattachez-la de façon qu’elle signale. La politique collecte sous deny, qui arrête le build par défaut. Une translation nommant deny seul, à warn, signale chacune de ses décisions comme un avertissement et laisse le build se terminer ; info les enregistre à la place. La politique elle-même reste telle qu’elle sera appliquée :

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/datastore-ha.rego
settings:
translation:
- key: deny
severity: warn

Écrivez la charge utile, et cherchez-y les chemins. Une fois qu’un build a rempli le fichier de verrouillage de la Release,

Terminal window
aggrega build --release release.yaml --dry-run --policy-input payloads

écrit dans payloads/ la charge utile que chaque rôle remet à ses rattachements, et rien d’autre, en signalant, avec <workspace> désignant le répertoire dans lequel le build s’est exécuté :

policy input: 4 file(s) written to <workspace>/payloads
[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]

Les quatre sont annotation-transform.json, ir-verdict.json, label-transform.json et render-verdict.json ; un rôle auquel rien n’est rattaché est également écrit, si bien qu’une politique peut être vérifiée par rapport à son rôle avant d’être rattachée où que ce soit. À ir-verdict, label-transform et annotation-transform, le fichier est le document input que lit une politique, si bien que chaque chemin que nomme une règle peut y être lu avec n’importe quel outil JSON avant qu’on ne fasse confiance à la règle :

Terminal window
jq '.graph.nodes' payloads/ir-verdict.json
# null
jq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json
# ["db","web"]
jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json
# {"enabled":false,"read_replicas":0}

Les nœuds de la règle n’y sont pas : input.graph.nodes est l’endroit où le rôle qui façonne les labels les porte, et à ir-verdict ils se trouvent sous input.graph.spec.nodes (voir Ce qu’expose la charge utile de chaque rôle). Le fichier dit aussi ce que la règle corrigée doit décider : db est un magasin de données, sa haute disponibilité est désactivée, et il doit être signalé.

Là où OPA est installé, une politique Rego s’évalue directement par rapport au même fichier, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Le moteur Rego du compilateur est une implémentation indépendante, si bien que le build reste l’évaluation qui décide : une fonction intégrée qu’il n’implémente pas arrête le build au lieu d’être évaluée.

À render-verdict, le fichier n’est pas l’input de la politique. Chaque artefact qu’il contient porte son path, son content et son format ; les documents que lit une règle sont analysés à partir du contenu par le moteur de politiques une fois qu’il reçoit la charge utile, si bien qu’une règle portant sur documents ne trouve rien dans le fichier. Une politique à ce rôle se teste là où le moteur les analyse : dans un build, comme le montre l’étape suivante.

Lancez le build, et comparez ce qu’il signale avec ce que dit la charge utile. Avec le chemin copié,

Terminal window
aggrega build --release release.yaml --auto-pull

se termine et ne signale rien :

Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

La charge utile contient un magasin de données dont la haute disponibilité est désactivée, et la politique n’en a rien dit : ce silence est l’erreur, et rien d’autre dans le build ne la signale. Avec la règle lisant input.graph.spec.nodes, la même commande signale db et se termine :

policy plugin "rego" warning: db is a datastore running with high availability off
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Ajouter --dry-run signale les mêmes verdicts et n’écrit aucun dist/, si bien que la boucle s’exécute sur un espace de travail sans perturber sa sortie.

La même règle écrite pour le moteur CEL n’échoue pas en silence. Y lire une clé que la charge utile ne porte pas est une défaillance d’évaluation, si bien que le chemin copié, dans policies/datastore-ha.cel rattaché avec la même translation,

{
"deny": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore"
&& input.graph.spec.infra_mapping[n].ha.enabled == false)
.map(n, n + " is a datastore running with high availability off"),
}

arrête le build même à warn. La commande se termine avec 1, et sa dernière ligne nomme le fichier de politique et la clé :

ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodes

Une politique render-verdict se teste de la même façon. Rattachée à render-verdict dans le même espace de travail, avec la même translation, une règle qui refuse un service Compose publiant un port sur l’hôte,

package published
import rego.v1
deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
count(service.ports) > 0
msg := sprintf("%v publishes a port on the host", [name])
}

signale le seul service qui le fait :

policy plugin "rego" warning: web publishes a port on the host
[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]

Puis appliquez-la. Retirer la translation ramène deny à halt, et le build qui signalait db s’arrête désormais dessus, se termine avec 1 et n’écrit aucun dist/ :

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db is a datastore running with high availability off
caused by: policy violation

Le rattachement qui signale n’a pas besoin d’être retiré partout à la fois. Un fichier de configuration peut garder la translation de son rattachement à warn pendant que la surcouche d’un pipeline rattache la même politique avec deny à halt, et c’est ainsi que examples/policy-org-overlay/ introduit la règle d’une organisation : un avertissement sur le build d’un développeur, et la raison pour laquelle le build d’un pipeline s’arrête.

Exécuter des politiques en CI, sur la sortie du build

Tout ce qui précède rattache une politique à l’intérieur d’un build. Il existe une seconde voie, et elle n’a besoin de rien du socket : exécuter votre propre outil dans le pipeline, sur les fichiers que le build a écrits.

Cela fonctionne grâce à ce qu’un build émet. Les cibles Kubernetes et Compose écrivent du YAML ; la cible Terraform écrit du HCL natif, ou du JSON dans sa forme .tf.json. Ce sont les formats que les outils de configuration de l’écosystème lisent déjà — et aggrega build écrit des fichiers simples dans un répertoire, sans format d’enveloppe, sans index et sans rien à décompresser. Un outil qui lit du YAML, du JSON ou du HCL s’exécute donc sur la sortie d’un build de la même façon qu’il s’exécute sur une configuration écrite à la main par une personne, et Aggrega ne se dote d’aucun socket, d’aucun type de plugin ni d’aucune clé de configuration pour cela.

Un corpus de règles existant ne nécessite donc aucun portage. Si vous gérez déjà des règles dans Conftest, la CLI de Kyverno, kubeconform, Checkov ou OPA, ces règles s’exécutent telles quelles sur la sortie d’un build Aggrega, et l’outil qui les évalue est celui que votre pipeline installe déjà.

Deux scripts de règles prêts à l’emploi, chacun avec l’étape de pipeline qui l’invoque et les deux refus qu’ils ont produits sur de vrais builds, se trouvent dans examples/policy-in-ci/. Ils utilisent yq et rien d’autre, si bien qu’ils s’exécutent sans aucune chaîne d’outils de politiques installée ; la forme qu’ils montrent — lire le répertoire de sortie, décider, se terminer avec un code non nul en nommant les artefacts fautifs — est la forme que prend tout outil à cette place.

À quelle voie appartient une règle

Les deux voies sont de premier plan, et un espace de travail utilise couramment les deux. Ce qui décide, c’est ce que la règle a besoin de voir et quand elle doit agir.

Rattachez-la au socket lorsque :

  • le build ne doit pas produire l’artefact du tout. Une politique ir-verdict s’exécute au contrôle d’analyse statique, avant que quoi que ce soit ne soit rendu, si bien qu’un arrêt à ce stade ne laisse rien d’écrit — aucun fichier de sortie à relire, à mettre en quarantaine ou à appliquer par accident. Une vérification en pipeline s’exécute nécessairement après que les fichiers existent.
  • la règle a besoin de faits que seul le build détient. Le rôle ir-verdict lit le graphe assemblé : les nœuds, les arêtes et leurs sockets, chaque rattachement avec l’emplacement qu’il a rempli, les valeurs qu’un auteur a déclarées sensibles, les chemins de routage. Rien de cela ne survit dans la sortie rendue — un manifeste Kubernetes n’enregistre pas quel socket a livré une valeur ni quelle Feature a contribué une ressource — si bien qu’une règle sur la topologie ou sur la provenance n’a qu’un seul lieu, et c’est le socket.
  • la règle doit s’appliquer partout où le build s’exécute. Un rattachement de gouvernance réside dans la configuration de l’espace de travail, si bien qu’il s’applique au build local d’un développeur autant qu’à celui du pipeline. Une vérification en pipeline s’applique là où le pipeline s’exécute.
  • la règle doit façonner le build plutôt que le juger. Seul un rôle de transformation le fait, et seulement parce qu’un opérateur l’a rattaché.

Exécutez-la en CI lorsque :

  • la règle existe déjà, dans un outil que votre équipe exécute et relit, sur un format que cet outil analyse déjà. La réexprimer comme contenu de politique pour le socket est un travail qui n’apporte, au bout du compte, aucune nouvelle couverture.
  • la règle porte sur les artefacts tels que la cible les recevra — l’ensemble final de fichiers, après chaque transformation, dans la forme qui est appliquée. C’est aussi l’objet du rôle render-verdict, si bien que sur ce seul point les deux voies voient la même chose et que le choix se joue sur les autres.
  • le constat est destiné à un relecteur plutôt qu’au build. Un pipeline qui publie les artefacts et les constats côte à côte donne les deux à un relecteur ; un build arrêté lui donne un message.
  • la vérification va au-delà d’un seul build — en comparant la sortie de ce build à la précédente, à l’état réel d’un cluster ou à un inventaire qu’aucune charge utile de build ne porte. Une politique à l’un ou l’autre rôle de verdict voit le build auquel elle est rattachée, et c’est tout ce qu’elle voit.

Les voies se composent plutôt que de se concurrencer : un invariant de topologie arrête le build depuis ir-verdict, et le même pipeline exécute ensuite les règles d’artefacts existantes du parc informatique sur ce que ce build a écrit.

Références croisées

  • plugin-contract.md — le placement du socket dans le pipeline, les formes de transmission typées qu’il porte et la sandbox sous laquelle s’exécute chaque plugin.
  • plugin-developer-guide.md — la création d’un plugin, l’auto-description describe() et le cycle de vie publish → pull → build.
  • ../entities/plugin.md — l’entité Plugin qui fait entrer un plugin dans le catalogue.
  • ../cli/aggrega-build.md — la commande de build qui invoque le socket.
  • ../schema/other/aggrega-config.md — le schéma de configuration de l’espace de travail, y compris la surface de rattachement plugins.governance.
  • ../examples/policy-in-ci/ — deux scripts de règles exécutables sur la sortie d’un build, avec l’étape de pipeline de chacun.
  • ../examples/policy-data-class-route/ — une règle ir-verdict sur les chemins, écrite pour le moteur Rego, le moteur CEL et OPA derrière le guest adaptateur de référence, rattachée par build par un fichier --config par moteur, avec un script qui vérifie que les trois aboutissent au même résultat sur chaque Release.