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

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

instanceComponent du cataloguece qu’il est ici
dbcore/datastore/mariadbla base de données de la boutique
webcore/devtool/adminerune 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

quifichiercomment un build le litoù le rattachement est écrit
l’équipe.aggrega-config.yamlil marque ce répertoire comme espace de travail, si bien que chaque build ici le litplugins.governance
l’organisationorg/config.yamlcomme fichier de configuration global, nommé pour un seul build avec --config org/config.yamlplugins.governance_append
le pipelinepipeline/.aggrega-config-append-ci.yamlune fois copié dans ce répertoire, comme surcouche du pipelineplugins.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 :

Terminal window
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
halts’arrête, se termine avec 1 et n’écrit aucun dist/
warnse termine, affiche le message et écrit dist/
infose 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: info

Le 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: halt

Ainsi, 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 :

Terminal window
aggrega scaffold --example policy-org-overlay

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

Terminal window
cd policy-org-overlay

Build

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 :

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

le build affiche l’avertissement de l’équipe et se termine. Avec en plus le fichier de l’organisation :

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

il 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 ship
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]

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 :

Terminal window
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 violation

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

Terminal window
./check.sh

check.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 OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + 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 commande aggrega build équivalente.
  • check.sh — effectue les cinq builds et vérifie chaque résultat.