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

Des politiques qui façonnent les labels : un niveau de support par environnement, et un verdict qui le lit

Des plugins de gouvernance apposent sur chaque composant que cet espace de travail déploie des labels indiquant son propriétaire, le niveau de support que lui vaut son environnement, sa planification de sauvegarde et un tag court, si bien qu’aucun développeur n’en saisit aucun. Les labels sont dérivés pendant le build, par quatre rattachements de gouvernance :

  • trois au rôle label-transform, qui façonnent les labels sur les nœuds du build : une politique Rego qui lit l’environnement de la Release, et les deux plugins de marquage compilés dans la CLI, label-injector et selector-tagger ;
  • un au rôle ir-verdict, une politique Rego sur le graphe de build qui arrête un build de production dans lequel un nœud est resté sans niveau de support.

Deux Releases d’un Aggregate diffèrent par leur environnement, staging et production, et leurs nœuds finissent avec des labels différents. Un troisième build, que check.sh effectue à partir d’une copie de cet espace de travail dont la politique couvre une catégorie de moins, s’arrête et nomme le nœud qu’elle a laissé de côté.

Ce qu’il construit

instanceComponent du cataloguece qu’il est ici
dbcore/datastore/mariadbla base de données de la boutique
cachecore/datastore/redisson cache de session
webcore/devtool/adminerune interface d’administration de base de données, câblée à db

Les trois sont compilés pour Docker Compose, dans dist/compose/docker-compose.yaml. L’Aggregate et les deux Releases ne nomment aucun label qui leur soit propre : chaque label ci-dessous est écrit par un rattachement.

Les quatre rattachements

Ils sont rattachés dans le .aggrega-config.yaml de cet espace de travail, sous plugins.governance, si bien que chaque build exécuté ici les applique :

pluginrôlece qu’il écrit
1governance/rego:0.9.0, avec policies/support-tier.regolabel-transformops.example.com/environment sur chaque nœud ; ops.example.com/support-tier sur chaque nœud dont ses paramètres listent la catégorie
2governance/label-injector:0.9.0label-transformops.example.com/owner sur chaque nœud ; backup.example.com/schedule sur chaque nœud de la catégorie datastore
3governance/selector-tagger:0.9.0label-transformtag, à partir de la table de correspondance de policies/tags.yaml
4governance/rego:0.9.0, avec policies/production-support.regoir-verdictrien : il arrête le build ou le laisse se terminer

0.9.0 est la version des trois entités Plugin du catalogue de la bibliothèque standard ; les plugins eux-mêmes sont compilés dans la CLI, et un build les sert depuis celle-ci. aggrega build --release release-production.yaml --auto-pull --detail liste les deux, pour chacun des trois :

[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry]
in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0
in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance
in-binary Plugin governance/rego ← governance/rego:0.9.0
in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance
in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0
in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance
[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]

Les rattachements à un même rôle s’exécutent dans l’ordre où ils sont listés, et chacun lit les labels que les précédents ont écrits : l’injecteur de labels reçoit les deux labels que la politique Rego a écrits, et le tagueur de sélecteurs reçoit ceux-ci ainsi que ceux de l’injecteur de labels. Le verdict s’exécute après les trois, sur le graphe qu’ils laissent.

Ce que lit une politique label-transform

Une politique à label-transform lit les nœuds sous input.graph.nodes, indexés par identifiant de nœud, chacun avec :

  • component — le Component que le nœud instancie, tel que core/datastore/mariadb ;
  • resolved_version — la version vers laquelle ce Component a été résolu ;
  • labels — les labels que porte le nœud lorsque la politique s’exécute : ceux propres au Component, et ceux qu’une transformation antérieure a écrits ;
  • values — les valeurs que l’instance du nœud déclare dans l’Aggregate, absentes là où elle n’en déclare aucune. Ici, seul db en déclare une, database: appdb.

Elle lit la Release sous input.compilation_context : release_name et environment. C’est ce qui permet à une même politique de décider différemment selon l’environnement.

Une politique à ir-verdict lit plutôt le graphe de build entier, et ses nœuds se trouvent un niveau plus bas, sous input.graph.spec.nodes. Une règle déplacée d’un rôle à l’autre se modifie, elle ne se copie pas : avec le mauvais chemin, elle ne lit rien et ne se déclenche jamais. La charge utile de ir-verdict ne porte aucun compilation_context, si bien qu’un verdict ne peut pas lire l’environnement depuis la Release. C’est pourquoi la première politique ici écrit aussi ops.example.com/environment sur chaque nœud : le verdict lit l’environnement depuis ce label.

Pour voir les charges utiles plutôt que de lire leur description, construisez une fois pour que le fichier de verrouillage existe, puis :

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

écrit la charge utile que reçoit chaque rattachement dans payloads/, un fichier par rattachement lorsque plusieurs rattachements à un même rôle reçoivent des charges utiles différentes — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — à côté d’un fichier pour chaque autre rôle, et n’écrit rien d’autre.

La politique Rego

policies/support-tier.rego rassemble ses décisions sous labels, une par label, chacune nommant le nœud, la clé du label et la valeur :

env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if {
some id, _ in input.graph.nodes
}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] in data.supported_categories
}

Ses paramètres sont le document data de la politique, et ils contiennent le vocabulaire du parc informatique :

settings:
# The categories whose components get a support tier.
supported_categories: [datastore, devtool]
# The tier each environment gives them.
support_tiers:
production: on-call
staging: office-hours

Ce qu’écrit chaque plugin intégré

label-injector applique une liste de règles. Un nœud dont les labels incluent chaque paire sous le match d’une règle reçoit chaque paire sous son set, ajoutée, ou remplaçant la valeur d’un label que le nœud porte déjà. Un match sans paire correspond à tous les nœuds. Il lit les règles depuis son paramètre rules, comme ici, ou, lorsque les paramètres n’en contiennent pas, depuis le premier fichier sous sources qui en contient. Ses deux règles donnent ici à chaque nœud ops.example.com/owner: shop-team, et à db et cache, les deux nœuds de la catégorie datastore, backup.example.com/schedule: nightly. web est dans la catégorie devtool et ne reçoit aucune planification de sauvegarde.

selector-tagger écrit un label, toujours sous la clé tag. Sa valeur provient d’une table de correspondance entre noms de Component et tags, lue depuis les fichiers sous sources. Un nœud dont la table ne liste pas le Component prend le paramètre default, et sans default, il reste sans tag. policies/tags.yaml fait correspondre la base de données et le cache :

core/datastore/mariadb: orders
core/datastore/redis: sessions

et le default du rattachement est untagged, si bien que web reçoit le tag untagged.

Les deux décident à partir des seuls labels d’un nœud et de son Component. Aucun ne lit l’environnement, si bien qu’ils écrivent les mêmes labels dans les deux Releases.

Les deux servent label-transform uniquement. Rattaché à ir-verdict, chacun est refusé avant de s’exécuter ; selector-tagger rattaché à cet endroit arrête le build avec :

[E0085]
ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox

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-label-transform

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

Terminal window
cd policy-label-transform

Build

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

Le catalogue de la bibliothèque standard fournit ici chaque Component, Recipe et Feature, ainsi que les trois entités Plugin. 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.

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-label-transform`, appelez une fois l’outil `scaffold` avec `example` défini sur `policy-label-transform` et sans `dir` : il écrit l’exemple dans un nouveau dossier `policy-label-transform`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-staging.yaml` et `release-production.yaml` — en définissant à chaque fois `workspace_root` sur `policy-label-transform`, `release` sur ce fichier, `auto_pull` sur true et `write` sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `policy-label-transform/dist/`.

Les labels avec lesquels finit chaque nœud

--ir-graph affiche le graphe de build sur la sortie standard, avant le résumé du build, et le graphe porte les labels de chaque nœud tels que les transformations les ont laissés. Après aggrega build --release release-production.yaml --auto-pull --ir-graph, web se lit ainsi :

"web": {
"labels": {
"component.aggrega.ai/type": "server",
"component.aggrega.ai/category": "devtool",
"component.aggrega.ai/upstream-licensing": "osi-approved",
"ops.example.com/environment": "production",
"ops.example.com/support-tier": "on-call",
"ops.example.com/owner": "shop-team",
"tag": "untagged"
},
[… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]
}

Les trois premiers labels sont ceux propres au Component ; les quatre derniers ont été écrits par les trois transformations. check.sh lit le graphe de chaque build et liste les labels que les rattachements ont écrits :

labels the attachments wrote, release-staging.yaml:
db ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: orders
cache ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: sessions
web ops.example.com/environment: staging
ops.example.com/support-tier: office-hours
ops.example.com/owner: shop-team
tag: untagged
labels the attachments wrote, release-production.yaml:
db ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: orders
cache ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
backup.example.com/schedule: nightly
tag: sessions
web ops.example.com/environment: production
ops.example.com/support-tier: on-call
ops.example.com/owner: shop-team
tag: untagged

Seuls les deux labels de la politique Rego changent d’une Release à l’autre.

Une fois qu’un build a rempli le fichier de verrouillage, aggrega inspect release-production.yaml --ir-graph affiche le même graphe sans construire, avant sa vue lisible de la Release, car les transformations lisent leurs fichiers depuis le fichier de verrouillage. Sans le fichier de verrouillage, le graphe qu’il affiche ne porte aucun des labels que ces fichiers décident : ni ops.example.com/environment ni ops.example.com/support-tier, et tag: untagged sur chaque nœud.

Une transformation change les labels, et rien d’autre

Une décision à label-transform nomme un nœud, une clé de label et sa valeur, ou demande qu’un label soit supprimé. Aucune décision n’ajoute un nœud, ne change le Component ou la version d’un nœud, ni ne touche à ses valeurs, si bien qu’une transformation ne peut rien exprimer de tout cela. Une décision nommant un nœud que le build n’a pas n’est pas ignorée : le build s’arrête avec E0069 et nomme le nœud et le label qu’il n’a pas pu définir.

Les deux builds de release-production.yaml, avec ces rattachements et sans aucun, le montrent. Leurs graphes de build diffèrent par les labels listés ci-dessus et par rien d’autre. Leur sortie rendue ne diffère pas du tout : les Recipes Compose ici ne rendent aucun de ces labels, si bien que dist/compose/docker-compose.yaml est le même fichier, octet par octet, avec les rattachements et sans eux, et check.sh compare les deux arborescences à chaque exécution. Les labels vivent dans le graphe de build, où le verdict les lit.

Le verdict, et le build qu’il arrête

policies/production-support.rego est rattachée à ir-verdict, après les transformations, et lit les labels qu’elles ont écrits :

deny contains msg if {
some id, node in input.graph.spec.nodes
node.labels["ops.example.com/environment"] == "production"
not node.labels["ops.example.com/support-tier"]
msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])
}

Les deux Releases se construisent : en staging, le verdict ne demande rien, et en production, chaque nœud porte un niveau. Réduisez la couverture de la politique, et le verdict repère le nœud qu’elle laisse de côté. Avec supported_categories écrit [datastore] dans .aggrega-config.yaml, web ne reçoit aucun niveau de support, et aggrega build --release release-production.yaml --auto-pull s’arrête :

[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label
caused by: policy violation

Le build se termine avec 1 et n’écrit aucun dist/. release-staging.yaml se construit toujours avec la politique réduite : ses nœuds portent le label staging, et le verdict ne leur demande rien. check.sh effectue ce build dans une copie de l’espace de travail, si bien qu’il n’y a rien à modifier ici pour le voir.

Un verdict accepte ou refuse et ne fait rien d’autre : il ne peut pas ajouter le label manquant pour faire passer le build. Le label qu’un nœud de production doit porter relève de la règle du parc informatique, écrite dans sa politique ; le compilateur achemine les labels jusqu’au graphe comme des chaînes et n’y lit aucun sens.

Ce qu’enregistre le lockfile

Le fichier de verrouillage consigne les deux sortes de rattachement différemment. Après un build de production, release-production.lock porte chaque rattachement de transformation sous mutators: — son plugin, son rôle, ses paramètres, ainsi que le contenu et le digest de chacun de ses fichiers — et épingle chaque plugin de transformation sous plugins: :

plugins:
- uri: governance/label-injector
[… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice]
referenced_from:
- governance/label-injector:0.9.0
- uri: governance/rego
[… omitted: the artifact digest, recorded twice]
referenced_from:
- governance/rego:0.9.0
- uri: governance/selector-tagger
[… omitted: the artifact digest, recorded twice]
referenced_from:
- governance/selector-tagger:0.9.0

Le rattachement du verdict n’apparaît que sous verdict_inputs:, par le sha256 de son fichier :

verdict_inputs:
- plugin: governance/rego:0.9.0
role: ir-verdict
sources:
- digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8
path: production-support.rego

Un rattachement de verdict n’est pas épinglé. Avec le verdict rattaché seul — les trois transformations retirées de .aggrega-config.yaml — le fichier de verrouillage porte mutators: [] et plugins: [], et le fichier du verdict sous verdict_inputs:. Une transformation change le build à partir duquel travaille le reste du pipeline, si bien que le fichier de verrouillage conserve le plugin qui a effectué le changement ; un verdict décide seulement si le build se termine.

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 quatre builds via l’assistant build-release et vérifie chaque résultat par rapport à celui que décrit cette page :

  • release-production.yaml dans une copie de cet espace de travail sans aucun rattachement de gouvernance, comme référence ;
  • release-staging.yaml et release-production.yaml ici, chacun devant se terminer avec les labels listés ci-dessus sur chaque nœud, l’arborescence de production étant identique octet pour octet à celle de la référence ;
  • release-production.yaml dans une copie dont la politique ne couvre que la catégorie datastore, qui doit s’arrêter avec E0005 et la phrase ci-dessus, sans aucun autre refus à côté.

Il affiche une ligne par build, puis les labels, et se termine avec 1 si un résultat diffère, en affichant la sortie de ce build :

RELEASE GOVERNANCE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
release-production.yaml none 0 reference OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-production.yaml narrowed 1 halt OK: E0005, the expected sentence
[… omitted: the two label listings shown above]
check: every build ended as expected.

Les deux copies sont créées dans un répertoire temporaire, avec le chemin du catalogue dans leur .aggrega-config.yaml rendu absolu afin qu’il se résolve toujours depuis cet emplacement. Aucun fichier de ce répertoire n’est modifié ; les deux builds effectués ici remplissent ses fichiers de verrouillage, comme le fait tout build. 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 compare les arborescences qu’écrivent les builds, et il n’en laisse aucune derrière lui. Son code de sortie constitue tout le verdict.

Là où le compilateur n’interprète pas

Le compilateur remet à chaque transformation les nœuds et l’environnement de la Release, applique les labels qu’elle décide, et remet le résultat au verdict. Il ne sait pas ce qu’est un niveau de support, que on-call l’emporte sur office-hours, ni qu’un devtool en a besoin d’un : ces significations sont les paramètres et les règles des politiques. Pour les rôles, les charges utiles et la façon dont une politique nomme un label, voir le socket de gouvernance, et pour la place de la politique dans le produit, Gouvernance et conformité.

Fichiers

  • aggregate.yaml — la base de données, le cache et l’interface d’administration câblée à la base de données ; aucun label.
  • manifest.yaml — lie chaque type de composant et la Feature de secret à sa Recipe Docker Compose. Partagé par les deux Releases.
  • release-staging.yaml, release-production.yaml — les deux environnements.
  • .aggrega-config.yaml — le registre par défaut et les quatre rattachements de gouvernance.
  • policies/support-tier.rego — la politique label-transform.
  • policies/production-support.rego — le verdict.
  • policies/tags.yaml — la correspondance entre composants et tags du tagueur de sélecteurs.
  • build-release.sh — construit une Release, en affichant la commande aggrega build équivalente.
  • check.sh — effectue les quatre builds et vérifie chaque résultat.