Une politique sur la sortie rendue : une règle maison, quatre cibles, deux moteurs
Une règle maison, rattachée au rôle render-verdict, juge les fichiers qu’un build écrit pour quatre cibles et refuse une violation piégée dans chacune. La règle a deux clauses :
Chaque image de conteneur nomme une version fixe — un tag autre que
latest, ou un digest. Chaque instance de base de données stocke ses données chiffrées.
Cet espace de travail construit un Aggregate pour quatre cibles — Kubernetes via Helm, Docker Compose, Terraform et CloudFormation. Le rôle render-verdict juge les fichiers qu’un build écrit, après que chaque cible les a rendus, et la règle lit la structure de sortie propre à chaque cible : les images dans les objets Kubernetes et dans un fichier Compose, l’instance RDS dans un fichier Terraform et dans un modèle CloudFormation. Chaque cible a une Release qui passe et une Release dans laquelle une violation est piégée, que la règle refuse.
La règle est écrite deux fois, une fois pour chaque moteur de politiques compilé dans la CLI — Rego et CEL — et les deux copies concordent sur chaque build ici. Un script à côté des Releases construit les seize combinaisons et vérifie chaque résultat.
aggrega buildvotre politique
branchée sur le compilateur
réussite
fichiers écrits
prêts à être relus et déployés
échec
compilation arrêtée
Une politique peut arrêter une compilation et indiquer ce qu’il faut corriger. Elle ne modifie jamais vos fichiers pour les faire passer.
Ce qu’il construit
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
db | core/datastore/postgres | la base de données des commandes |
report | core/compute/task | une tâche de rapport qui lit db, lancée à la main : elle porte core/manual-trigger, si bien qu’aucune exécution ne démarre lorsque la Release est déployée |
report lit l’adresse, le port et le nom de la base de données via sa connexion database, sous la forme DB_HOST, DB_PORT et DB_NAME. L’Aggregate est le même fichier pour chaque build ; chaque Release nomme le Manifest qui choisit la cible :
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, un StatefulSet | helm/task, un CronJob maintenu suspendu |
manifest-compose.yaml | compose/postgres, un service | compose/task, un service derrière un profil |
manifest-terraform.yaml | terraform/postgres-rds, une instance RDS | terraform/task-ecs, une définition de tâche Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, une instance RDS | cloudformation/task-ecs, une définition de tâche Amazon ECS |
Chaque Recipe ici rend à partir du seul catalogue : la base de données Kubernetes est synthétisée plutôt que récupérée sous forme de chart, le corps de la base de données Terraform est écrit par sa Recipe, et le module de la tâche Terraform est conservé à côté de sa Recipe. Chaque build s’exécute donc hors ligne.
Les huit Releases
| Release | cible | ce que la règle trouve | le build |
|---|---|---|---|
release-helm.yaml | Kubernetes | report exécute registry.example.com/orders-report:1.4.2 | aboutit |
release-helm-unpinned.yaml | Kubernetes | report exécute la même image avec le tag latest | s’arrête |
release-compose.yaml | Docker Compose | report exécute registry.example.com/orders-report:1.4.2 | aboutit |
release-compose-unpinned.yaml | Docker Compose | report exécute l’image sans tag | s’arrête |
release-terraform.yaml | Terraform | l’instance est chiffrée avec la clé que nomme la Release | aboutit |
release-terraform-unencrypted.yaml | Terraform | la Release ne nomme aucune clé, donc l’instance n’est pas chiffrée | s’arrête |
release-cloudformation.yaml | CloudFormation | la Release active StorageEncrypted | aboutit |
release-cloudformation-unencrypted.yaml | CloudFormation | la Release le laisse désactivé | s’arrête |
L’image relève de la Release : core/compute/task n’empaquette aucun logiciel, si bien que la Release nomme sous infra.image l’image qu’une exécution lance, tag compris. Sur les deux cibles AWS, le chiffrement de la base de données relève aussi de la Release. La Recipe Terraform lit infra.overrides.kms_key_id et, lorsqu’il est défini, rend storage_encrypted = true à côté de la clé ; la Recipe CloudFormation lit infra.overrides.StorageEncrypted et KmsKeyId sous les noms propres des propriétés de la ressource. Une Release qui ne définit ni l’un ni l’autre rend une instance sans aucun attribut de chiffrement, ce que font les Releases piégées.
Les bases de données Kubernetes et Compose exécutent l’image postgres:16, un tag fixe, si bien que la règle les juge et les laisse passer dans chaque Release.
Rattacher la règle
.aggrega-config.yaml désigne le hub comme son registre et aucun répertoire de catalogue, ni aucun rattachement de gouvernance. La règle est rattachée par le fichier qu’un build nomme avec --config : governance-rego.yaml pour le moteur Rego, governance-cel.yaml pour le moteur CEL. Celui de Rego se lit ainsi :
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config nomme le fichier de configuration global pour cette exécution, à la place de celui que la machine lirait sinon, et le .aggrega-config.yaml de cet espace de travail se superpose toujours à lui. Une liste plugins.governance dans le fichier de l’espace de travail remplacerait celle que porte le fichier nommé, c’est pourquoi le fichier de l’espace de travail n’en déclare aucune. 0.9.0 est la version de l’entité Plugin de chaque moteur dans le catalogue de la bibliothèque standard. Les deux moteurs sont compilés dans la CLI — aggrega plugin list liste governance/rego et governance/cel parmi les plugins intégrés embarqués — si bien qu’aucun build ici ne récupère de plugin.
Ce que lit une politique render-verdict
Une politique en render-verdict lit les fichiers qu’écrit le build dans input.artifacts, une entrée par fichier, triées par chemin. Chacune porte :
path— le chemin du fichier sousdist/, par exempleterraform/modules/db/main.tf;content— le texte du fichier, tel qu’écrit ;format— le format que le fournisseur de la cible a déclaré pour le fichier :yamlpour le fichier Compose,jsonpour le modèle CloudFormation,hclpour chaque fichier Terraform, y compris le corps de la base de données qu’écrit sa Recipe. Là où rien n’en a déclaré, c’est la chaîne vide, comme pour les fichiers Kubernetes ici ;documents— le contenu du fichier analysé en structure, sous forme de liste de documents : un pour chaque fichier ici ;parse_error— présent uniquement sur un fichier qui n’a pas pu être analysé, à la place dedocuments.
À côté des fichiers, input.sources contient le fichier de politique propre au rattachement, et input.settings ses paramètres — ici l’objet vide, puisque ce rattachement n’en déclare aucun.
aggrega build --release <release> --dry-run --policy-input <dir> écrit dans <dir> la charge utile que reçoit chaque rôle et n’écrit rien d’autre. En render-verdict, ce fichier est ce que reçoit le moteur plutôt que ce que lit la politique : chaque fichier qu’il contient porte son path et son content et le format que son fournisseur a déclaré, et le moteur analyse les documents à partir du contenu une fois qu’il reçoit la charge utile. Le fichier liste donc les fichiers qui seront montrés à une règle, mais pas leurs documents. Après qu’un build de release-terraform.yaml a rempli son fichier de verrouillage :
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Un chemin qu’une règle lit dans documents est vérifié dans un build, où le moteur les a analysés. Aucun fichier qu’écrivent ces Recipes n’échoue à l’analyse, si bien qu’aucun fichier ici ne porte parse_error. Chaque clause de cette règle lit documents, si bien qu’un fichier qui n’a pas pu être analysé la passerait sans être examiné ; une règle qui ne doit pas laisser cela se produire ajoute une clause qui refuse un fichier portant parse_error.
Comment chaque clause lit la structure de sa cible
Chaque clause nomme la structure qu’elle lit, et un fichier d’une autre structure ne porte pas ce que la clause nomme : en Rego, le chemin est indéfini et la clause n’est pas vérifiée. Une seule règle s’exécute donc sur la sortie de chaque cible, et chaque clause ne trouve que la sienne.
Compose écrit un fichier dont le document indexe chaque service par nom sous services :
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Les objets Kubernetes portent leurs conteneurs dans un modèle de pod, qu’un CronJob contient un niveau plus bas que les autres charges de travail, sous spec.jobTemplate.spec :
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform en HCL natif imbrique un bloc 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 regroupés en une seule liste. Les attributs d’une instance se trouvent donc un index sous son nom, et la clause parcourt la liste :
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}La liste compte davantage ici que pour une règle qui cherche une valeur, car cette clause refuse sur une absence. Écrite pour un seul bloc — some name, block in doc.resource.aws_db_instance — block est la liste, block.storage_encrypted y est indéfini, et not est vérifié pour tout ce qui est indéfini : la clause refuse aussi release-terraform.yaml, dont l’instance est chiffrée, avec le même message que la Release piégée.
Un fichier .tf.json se lit tel que sa Recipe l’a écrit, le nom contenant directement le bloc, si bien qu’une règle écrite pour une forme ne lit pas l’autre. C’est pourquoi la clause lit d’abord format : native_hcl prend un fichier dont le format est hcl, ou dont le format est vide et dont le nom se termine par .tf — un fichier pour lequel aucun fournisseur n’a déclaré de format est analysé d’après son nom, si bien que la règle le reconnaît aussi à son nom, plutôt que de l’ignorer. Chaque fichier Terraform construit ici est déclaré hcl, si bien qu’aucun fichier ici n’est reconnu à son nom. Ces Recipes n’écrivent aucun fichier .tf.json, si bien que la règle ne lit aucune autre forme. Ce qu’expose la charge utile de chaque rôle présente les deux formes.
CloudFormation écrit un modèle dont les ressources sont indexées par ID logique sous Resources, chacune avec son Type et ses Properties :
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Une instance sans propriété StorageEncrypted, ou avec celle-ci définie à autre chose que true, est refusée : not … == true est vérifié dans les deux cas.
Pourquoi la règle CEL est écrite différemment
policies/house-rule.cel énonce les deux mêmes clauses et aboutit au même verdict sur chaque build ici. Elle est écrite différemment à trois endroits, chacun pour une raison propre au moteur.
Elle teste chaque clé avant de la lire. Lire une clé que ne porte pas une valeur est, en CEL, une défaillance d’évaluation plutôt qu’un chemin indéfini, et une défaillance arrête le build. Il manque aux fichiers de chaque cible des clés que portent ceux d’une autre — un objet Kubernetes n’a pas de services, un fichier Compose pas de kind — si bien que chaque clause teste d’abord avec has() les clés qu’elle lit :
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Sans le test has(d.services), aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull s’arrête, quelles que soient les images qu’exécutent les objets Kubernetes, se termine avec 1 et n’écrit aucun dist/, et la ligne qui signale la défaillance nomme le fichier de politique et la clé :
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesElle signale un seul élément fautif par fichier. Une clé de décision collecte des messages, et une expression CEL n’a aucun moyen de joindre en une seule liste les listes qu’elle construit par fichier. Chaque clause CEL signale donc un élément fautif dans chaque fichier : le premier conteneur d’un modèle de pod, ou, parmi les services, instances et ressources qu’un fichier indexe par nom, celui dont le nom vient en premier dans l’ordre de tri. Une compréhension parcourt une map sans ordre fixe, si bien que choisir par nom est ce qui garde le message identique d’un build à l’autre. La règle Rego signale chaque élément fautif. Avec deux services non épinglés dans un fichier Compose, le moteur Rego s’arrête avec deux messages et le moteur CEL avec un seul, pour le service dont le nom vient en premier dans l’ordre de tri ; avec un seul, comme dans chaque Release ici, les deux s’arrêtent avec le même message.
Elle se répète. CEL n’offre aucun moyen de nommer une sous-expression, si bien qu’un test utilisé deux fois est écrit deux fois, et le test de l’image est écrit en entier dans chaque clause plutôt qu’appelé comme l’est unpinned en Rego.
Les deux fichiers sont un quasi-doublon délibéré, chacun écrit indépendamment à partir de la règle ci-dessus plutôt que généré l’un à partir de l’autre, de sorte qu’un build sur lequel les moteurs divergent montre la divergence.
Un verdict ne change jamais la sortie
Une politique en render-verdict accepte le build ou le refuse. Elle reçoit les fichiers que le build a écrits et renvoie des verdicts ; rien de ce qu’elle renvoie ne leur est appliqué. Une Release témoin construit donc les mêmes fichiers, octet par octet, avec la règle rattachée et sans elle, et check.sh compare les deux arborescences à chaque exécution. Un build refusé n’écrit aucun dist/. Pour corriger un refus, c’est la Release qui change — un tag épinglé, une clé de chiffrement — et le build suivant est jugé à nouveau.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example policy-render-verdictElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd policy-render-verdictBuild
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Remplacez governance-rego.yaml par governance-cel.yaml pour exécuter la même règle sur le moteur CEL, et terraform dans le nom de fichier de la Release par helm, compose ou cloudformation, avec leurs Releases piégées release-helm-unpinned.yaml, release-compose-unpinned.yaml et release-cloudformation-unencrypted.yaml.
Le catalogue de la bibliothèque standard fournit ici chaque Component, Recipe, Feature et FeatureRecipe, et porte les entités Plugin des deux moteurs. Ils sont résolus depuis hub.aggrega.ai, le registre par défaut que nomme .aggrega-config.yaml. Avec un checkout du catalogue (où en obtenir un) nommé avec --catalog, rien n’est récupéré depuis un registre, si bien que les builds s’exécutent hors ligne. --auto-pull remplit le fichier de verrouillage de chaque Release pendant le build ; les fichiers de verrouillage et la sortie rendue sont générés, et non livrés.
La Release témoin Terraform aboutit. La Release piégée s’arrête :
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationChaque message nomme le fichier que la règle a jugé, sous la forme de son chemin sous dist/, et l’élément fautif qu’il contient. Les autres Releases piégées s’arrêtent de la même façon :
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedChaque ligne est celle qui suit [POLICY_ERROR E0005] dans la sortie de son build, affichée depuis la marge gauche. La première provient du moteur Rego et les deux autres du moteur CEL, chacune nommant le moteur qui l’a signalée ; l’autre moteur affiche le même message sous son propre nom.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `policy-render-verdict`, appelez une fois l’outil `scaffold` avec `example` défini sur `policy-render-verdict` et sans `dir` : il écrit l’exemple dans un nouveau dossier `policy-render-verdict`. Appelez ensuite l’outil `cli-build`, qui exécute `aggrega build` et accepte son option `--config`, une fois pour chaque Release, dans cet ordre — `release-terraform.yaml` et `release-terraform-unencrypted.yaml` — en définissant à chaque fois `workspace_root` sur `policy-render-verdict`, `release` sur ce fichier, `auto_pull` sur true et `config` sur `governance-rego.yaml`. Le deuxième doit être refusé : lisez-moi donc le refus. Indiquez-moi quels fichiers le premier build a écrits ; ils se trouvent sous `policy-render-verdict/dist/`.Vérifier chaque build
Cette auto-vérification s’exécute dans un checkout du dépôt de la documentation, qui contient l’utilitaire de build partagé qu’elle utilise ; une copie écrite par aggrega scaffold --example ne contient pas cet utilitaire.
./check.shcheck.sh effectue le build de chaque Release témoin une fois sans aucune politique rattachée, comme référence, puis des huit Releases sous chaque moteur, via l’assistant build-release. Une Release témoin doit se terminer et écrire les mêmes fichiers, octet pour octet, que sa référence ; une Release piégée doit s’arrêter avec E0005 et le message attendu pour elle, sans aucun autre refus à côté, et n’écrire aucun dist/. Les deux moteurs sont tenus au même message. Il affiche une ligne par build et se termine avec 1 si un résultat diffère, en affichant la sortie de ce build :
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.Il utilise le binaire que résout ./build-release.sh, si bien que AGGREGA_BIN le choisit, et les arguments après -- parviennent à chaque build. Il refuse de démarrer tant qu’un dist/ se trouve dans ce répertoire, car il déplace l’arborescence de chaque build pour la comparer, et il n’en laisse aucune derrière lui ; les builds remplissent les fichiers de verrouillage de ce répertoire, comme le fait tout build. Son code de sortie constitue tout le verdict.
Là où le compilateur n’interprète pas
Le compilateur rend les fichiers de chaque cible, les remet au moteur rattaché sous forme de texte avec le format que leur fournisseur a déclaré, et agit selon le niveau de gravité que porte chaque verdict. Il ne sait pas ce qu’est un tag d’image, que latest se déplace, ni qu’une instance RDS devrait être chiffrée : ces significations appartiennent à la règle. Pour les rôles, les charges utiles et les clés de décision, voir le socket de gouvernance.
Fichiers
aggregate.yaml— la base de données et le job de rapport câblé à celle-ci.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— lient chaque type de composant et la Feature de déclenchement manuel à leurs Recipes sur une cible.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— une Release témoin et une violation piégée par cible..aggrega-config.yaml— le registre par défaut ; aucun rattachement de gouvernance.governance-rego.yaml,governance-cel.yaml— la règle rattachée àrender-verdictvia chaque moteur, chacun nommé avec--config.policies/house-rule.rego,policies/house-rule.cel— la règle, une fois par moteur.build-release.sh— construit une Release, en affichant la commandeaggrega buildéquivalente.check.sh— effectue les vingt builds et vérifie chaque résultat.