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

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 build

votre politique

branchée sur le compilateur

réussite

fichiers écrits

prêts à être relus et déployés

échec

compilation arrêtée

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

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

instanceComponent du cataloguece qu’il est ici
dbcore/datastore/postgresla base de données des commandes
reportcore/compute/taskune 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 :

Manifestdbreport
manifest-helm.yamlhelm/postgres, un StatefulSethelm/task, un CronJob maintenu suspendu
manifest-compose.yamlcompose/postgres, un servicecompose/task, un service derrière un profil
manifest-terraform.yamlterraform/postgres-rds, une instance RDSterraform/task-ecs, une définition de tâche Amazon ECS
manifest-cloudformation.yamlcloudformation/postgres-rds, une instance RDScloudformation/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

Releaseciblece que la règle trouvele build
release-helm.yamlKubernetesreport exécute registry.example.com/orders-report:1.4.2aboutit
release-helm-unpinned.yamlKubernetesreport exécute la même image avec le tag latests’arrête
release-compose.yamlDocker Composereport exécute registry.example.com/orders-report:1.4.2aboutit
release-compose-unpinned.yamlDocker Composereport exécute l’image sans tags’arrête
release-terraform.yamlTerraforml’instance est chiffrée avec la clé que nomme la Releaseaboutit
release-terraform-unencrypted.yamlTerraformla Release ne nomme aucune clé, donc l’instance n’est pas chiffrées’arrête
release-cloudformation.yamlCloudFormationla Release active StorageEncryptedaboutit
release-cloudformation-unencrypted.yamlCloudFormationla 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 sous dist/, par exemple terraform/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 : yaml pour le fichier Compose, json pour le modèle CloudFormation, hcl pour 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 de documents.

À 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 :

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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: services

Elle 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 :

Terminal window
aggrega scaffold --example policy-render-verdict

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd policy-render-verdict

Build

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Remplacez 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 violation

Chaque 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 latest
policy 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 latest
policy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted

Chaque 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.

Terminal window
./check.sh

check.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 OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel 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-verdict via 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 commande aggrega build équivalente.
  • check.sh — effectue les vingt builds et vérifie chaque résultat.