Politique à l’échelle de l’organisation : la règle d’une équipe, celle d’une organisation et celle d’un pipeline
La politique d’une équipe, celle de son organisation et celle de son pipeline s’exécutent ensemble sur un même build, chacune rattachée dans un fichier de configuration qui lui est propre. L’équipe rattache sa règle dans son espace de travail ; l’organisation en ajoute une sur chaque build, et le pipeline en ajoute une de plus, sans que ni l’organisation ni le pipeline ne modifient le fichier de l’équipe. Un build lit tous les fichiers qui s’appliquent à lui et exécute chaque rattachement qu’ils portent.
Les règles signalent aux trois niveaux de gravité des verdicts : info et warn laissent le build se terminer, et halt l’arrête. L’une d’elles, celle de l’organisation, est rattachée deux fois et signalée à un niveau de gravité différent à chaque fois, via un bloc translation.
Ce qu’il construit
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
db | core/datastore/mariadb | la base de données de la boutique |
web | core/devtool/adminer | une interface d’administration de base de données, câblée à db |
Les deux sont compilés pour Docker Compose, dans dist/compose/docker-compose.yaml. Un Aggregate, un Manifest et une Release, release.yaml ; aucun d’eux ne nomme de politique.
Les trois fichiers
| qui | fichier | comment un build le lit | où le rattachement est écrit |
|---|---|---|---|
| l’équipe | .aggrega-config.yaml | il marque ce répertoire comme espace de travail, si bien que chaque build ici le lit | plugins.governance |
| l’organisation | org/config.yaml | comme fichier de configuration global, nommé pour un seul build avec --config org/config.yaml | plugins.governance_append |
| le pipeline | pipeline/.aggrega-config-append-ci.yaml | une fois copié dans ce répertoire, comme surcouche du pipeline | plugins.governance_append |
Les trois rattachements sont le moteur Rego, governance/rego:0.9.0, au rôle ir-verdict, qui juge le graphe de build avant que quoi que ce soit ne soit rendu. 0.9.0 est la version de son entité Plugin dans le catalogue de la bibliothèque standard. Le moteur lui-même est compilé dans la CLI — aggrega plugin list liste governance/rego parmi les built-ins embarqués — si bien qu’aucun build ici ne récupère de plugin.
Le fichier de l’organisation est un fichier de configuration global. Une machine en a un, lu à chaque build : depuis son emplacement par défaut, ou le fichier que nomme la variable d’environnement AGGREGA_CONFIG. --config <path> en nomme un pour une seule exécution à la place, et les propres fichiers de l’espace de travail sont toujours lus par-dessus. Dans une organisation, le fichier se trouverait à l’emplacement par défaut sur la machine de chaque développeur et dans chaque pipeline ; ici, il se trouve dans org/, et les builds qui doivent le lire le nomment. Nommer explicitement le fichier global expose l’ordre dans lequel les trois façons sont essayées.
Le fichier du pipeline est une surcouche. Un build lit .aggrega-config-append-ci.yaml dans les répertoires où il lit .aggrega-config.yaml, à côté de celui-ci. Il est conservé ici dans pipeline/, où un build exécuté dans ce répertoire ne le lit pas, car il arrête chaque build qui le lit ; l’étape du pipeline consiste à l’y copier :
cp pipeline/.aggrega-config-append-ci.yaml .Chaque fichier ajoute, et la surcouche du pipeline ne fait qu’ajouter
L’organisation et le pipeline écrivent tous deux leur rattachement sous plugins.governance_append, le pendant d’ajout de la liste plugins.governance. Les entrées sous un pendant sont concaténées à la liste résolue après la lecture des propres listes de chaque fichier, si bien que le plugins.governance de l’équipe et l’entrée de l’organisation s’exécutent tous deux, et qu’aucun des deux fichiers ne nomme l’autre. L’organisation écrit le pendant, et non plugins.governance lui-même, car une liste plugins.governance dans le fichier de l’espace de travail remplace celle du fichier global : une règle de l’organisation écrite là est abandonnée par la liste de l’équipe, et le build n’en affiche rien. Étendre une liste au lieu de la remplacer liste le pendant de chaque paramètre de type liste.
La surcouche du pipeline ne peut qu’ajouter. Ce qu’elle écrit pour un paramètre de type liste est ajouté à ce que les autres fichiers ont résolu ; elle ne retire rien, et elle ne remplace pas un paramètre qui contient une seule valeur, comme auto_pull. Celle-ci porte auto_pull: true, et un build qui la lit ignore la clé et le signale par un avertissement. Avec <workspace> désignant le chemin absolu du répertoire dans lequel le build s’est exécuté, la ligne se lit ainsi :
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)Les règles, et le niveau de gravité auquel chacune est signalée
Une politique Rego rassemble chaque décision sous une clé de décision, et la clé choisit le niveau de gravité auquel la décision est signalée. Sans translation, les clés sont deny, warn et audit, signalées à halt, warn et info :
| niveau de gravité | ce que fait le build |
|---|---|
halt | s’arrête, se termine avec 1 et n’écrit aucun dist/ |
warn | se termine, affiche le message et écrit dist/ |
info | se termine, affiche le message et écrit dist/ |
La règle de l’équipe, policies/team.rego, rassemble sous warn, et son rattachement ne déclare aucune translation, si bien qu’elle est signalée à warn :
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}La règle de l’organisation, org/policies/estate.rego, refuse les composants d’une catégorie que listent ses paramètres, et consigne ce que chaque composant exécute :
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories est un paramètre de chaque rattachement, et une politique lit les paramètres de son rattachement comme son document data.
Traduction : une règle, deux niveaux de gravité
Un bloc translation dans les paramètres d’un rattachement déclare quelles clés de décision sont lues et le niveau de gravité auquel chacune est signalée. Il remplace la correspondance par défaut au lieu de l’étendre : une clé qu’il ne nomme pas n’est pas lue.
Le fichier de l’organisation introduit sa règle à titre de conseil. Son rattachement signale deny à warn, et audit à info :
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoLe pipeline rattache le même fichier et fait en sorte que la même règle arrête le build. Sa traduction ne nomme que deny, si bien que son rattachement ne signale pas une seconde fois les enregistrements audit :
settings: refused_categories: [devtool] translation: - key: deny severity: haltAinsi, une même règle, sur le même web, est un avertissement sur le build d’un développeur et la raison pour laquelle le build d’un pipeline s’arrête.
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-org-overlayElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd policy-org-overlayBuild
Le catalogue de la bibliothèque standard fournit les Components, les Recipes, la Feature et sa FeatureRecipe. 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 pendant le build ; le fichier de verrouillage et la sortie rendue sont générés, et non livrés.
Avec le fichier de l’équipe seul :
aggrega build --release release.yaml --auto-pullle build affiche l’avertissement de l’équipe et se termine. Avec en plus le fichier de l’organisation :
aggrega build --release release.yaml --auto-pull --config org/config.yamlil affiche les enregistrements de l’organisation à info et sa règle à warn, à côté de l’avertissement de l’équipe, et se termine tout de même :
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull 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]Chaque verdict nomme le plugin qui l’a signalé, rego, et non le fichier qui l’a rattaché, si bien que l’avertissement de l’équipe et celui de l’organisation se lisent de la même façon ; un message qui dit à qui appartient la règle, comme le fait celui de l’organisation, est le moyen de les distinguer.
Avec la surcouche du pipeline copiée, la même commande s’arrête :
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violationLe build se termine avec 1 et n’écrit aucun dist/. La règle de l’organisation est signalée deux fois, une fois par chaque rattachement : à warn par celui de l’organisation et à halt par celui du pipeline. Les enregistrements audit apparaissent une fois, depuis le seul rattachement de l’organisation. Supprimez .aggrega-config-append-ci.yaml de ce répertoire pour construire à nouveau sans elle.
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-org-overlay`, appelez une fois l’outil `scaffold` avec `example` défini sur `policy-org-overlay` et sans `dir` : il écrit l’exemple dans un nouveau dossier `policy-org-overlay`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `policy-org-overlay`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true, et dites-moi ce que la politique a signalé. Appelez ensuite l’outil `cli-build`, qui exécute `aggrega build` et accepte son option `--config`, avec `workspace_root` défini sur `policy-org-overlay`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `config` défini sur `org/config.yaml`, et dites-moi ce que la politique a signalé cette fois. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `policy-org-overlay/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 construit release.yaml cinq fois, via l’assistant build-release, chaque fois dans une copie de cet espace de travail : avec le fichier de l’équipe seul, avec le fichier de l’organisation nommé par --config, avec la surcouche du pipeline copiée, avec les deux, et avec une copie du fichier de l’organisation qui écrit son rattachement sous plugins.governance au lieu du pendant — où la liste de l’équipe le remplace, et seul le verdict de l’équipe est affiché. Pour chacun, il vérifie le code de sortie, si dist/ a été écrit, et chaque verdict que le build a affiché — son niveau de gravité et son message, sans rien de manquant ni rien de plus — et, là où la surcouche est lue, l’avertissement qui nomme auto_pull. Il affiche une ligne par build, puis les verdicts que chacun a affichés, et se termine avec 1 si un résultat diffère, en affichant la sortie de ce build :
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.Les 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é ni écrit. 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. Son code de sortie constitue tout le verdict.
Là où le compilateur n’interprète pas
Le compilateur lit les trois fichiers, concatène les rattachements qu’ils portent, remet à chaque politique le graphe de build et ses paramètres, et agit selon le niveau de gravité auquel chaque décision est signalée. Il ne sait pas ce qu’est un devtool, pourquoi une organisation n’en livrerait pas, ni que la haute disponibilité compte pour une équipe : ces significations sont les règles et les paramètres des politiques. 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 l’interface d’administration câblée à celle-ci.manifest.yaml— lie chaque type de composant et la Feature de secret à sa Recipe Docker Compose.release.yaml— l’unique Release..aggrega-config.yaml— le fichier de l’équipe : le registre par défaut et le rattachement de l’équipe.policies/team.rego— la règle de l’équipe.org/config.yaml— le fichier de configuration global de l’organisation et son rattachement.org/policies/estate.rego— la règle de l’organisation.pipeline/.aggrega-config-append-ci.yaml— la surcouche du pipeline, lue une fois copiée dans ce répertoire.build-release.sh— construit la Release, en affichant la commandeaggrega buildéquivalente.check.sh— effectue les cinq builds et vérifie chaque résultat.