Richtlinien, die Labels gestalten: eine Support-Stufe pro Umgebung und ein Verdikt, das sie liest
Governance-Plugins versehen jede Komponente, die dieser Workspace bereitstellt, mit Labels für ihren Eigentümer, die Support-Stufe, die ihre Umgebung ihr einbringt, ihren Backup-Zeitplan und ein kurzes Tag, sodass kein Entwickler eines davon eintippt. Die Labels werden während des Builds abgeleitet, durch vier Governance-Anbindungen:
- drei an der Rolle
label-transform, die die Labels auf den Knoten des Builds gestalten: eine Rego-Richtlinie, die die Umgebung des Release liest, und die beiden in die CLI kompilierten Tagging-Plugins,label-injectorundselector-tagger; - eine an der Rolle
ir-verdict, eine Rego-Richtlinie über den Build-Graphen, die einen Produktions-Build abbricht, in dem ein Knoten ohne Support-Stufe geblieben ist.
Zwei Releases eines Aggregate unterscheiden sich in ihrer Umgebung, staging und production, und ihre Knoten enden mit unterschiedlichen Labels. Ein dritter Build, den check.sh aus einer Kopie dieses Workspace erstellt, deren Richtlinie eine Kategorie weniger abdeckt, bricht ab und nennt den Knoten, den sie ausgelassen hat.
Was es baut
| Instanz | Katalog-Component | was es hier ist |
|---|---|---|
db | core/datastore/mariadb | die Datenbank des Shops |
cache | core/datastore/redis | ihr Session-Cache |
web | core/devtool/adminer | eine Oberfläche zur Datenbankverwaltung, verdrahtet mit db |
Alle drei werden für Docker Compose kompiliert, nach dist/compose/docker-compose.yaml. Das Aggregate und beide Releases nennen kein eigenes Label: Jedes Label unten wird von einer Anbindung geschrieben.
Die vier Anbindungen
Sie sind in der .aggrega-config.yaml dieses Workspace unter plugins.governance angebunden, sodass jeder hier ausgeführte Build sie anwendet:
| Plugin | Rolle | was es schreibt | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, mit policies/support-tier.rego | label-transform | ops.example.com/environment auf jedem Knoten; ops.example.com/support-tier auf jedem Knoten, dessen Kategorie seine Einstellungen auflisten |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner auf jedem Knoten; backup.example.com/schedule auf jedem Knoten der Kategorie datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, aus der Zuordnung in policies/tags.yaml |
| 4 | governance/rego:0.9.0, mit policies/production-support.rego | ir-verdict | nichts: Es bricht den Build ab oder lässt ihn abschließen |
0.9.0 ist die Version der drei Plugin-Entitäten im Katalog der Standardbibliothek; die Plugins selbst sind in die CLI kompiliert, und ein Build stellt sie von dort bereit. aggrega build --release release-production.yaml --auto-pull --detail listet beides auf, für jedes der drei:
[… 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]Die Anbindungen an einer Rolle laufen in der Reihenfolge, in der sie aufgelistet sind, und jede liest die Labels, die die vorherigen geschrieben haben: Der Label-Injector erhält die beiden Labels, die die Rego-Richtlinie geschrieben hat, und der Selector-Tagger erhält diese und die des Label-Injectors. Das Verdikt läuft nach allen dreien, über den Graphen, den sie hinterlassen.
Was eine label-transform-Richtlinie liest
Eine Richtlinie bei label-transform liest die Knoten unter input.graph.nodes, nach Knoten-ID geschlüsselt, jeder mit:
component— die Component, die der Knoten instanziiert, etwacore/datastore/mariadb;resolved_version— die Version, zu der diese Component aufgelöst wurde;labels— die Labels, die der Knoten trägt, wenn die Richtlinie läuft: die eigenen der Component und die, die eine frühere Transformation geschrieben hat;values— die Werte, die die Instanz des Knotens im Aggregate deklariert, fehlend, wo sie keine deklariert. Hier deklariert nurdbeinen,database: appdb.
Sie liest das Release unter input.compilation_context: release_name und environment. Das ist es, was eine Richtlinie pro Umgebung anders entscheiden lässt.
Eine Richtlinie bei ir-verdict liest stattdessen den ganzen Build-Graphen, und ihre Knoten liegen eine Ebene tiefer, unter input.graph.spec.nodes. Eine Regel, die von einer Rolle in die andere verschoben wird, wird angepasst, nicht kopiert: Mit dem falschen Pfad liest sie nichts und greift nie. Die Payload von ir-verdict trägt keinen compilation_context, daher kann ein Verdikt die Umgebung nicht aus dem Release lesen. Deshalb schreibt die erste Richtlinie hier auch ops.example.com/environment auf jeden Knoten: Das Verdikt liest die Umgebung aus diesem Label.
Um die Payloads zu sehen, statt darüber zu lesen, bauen Sie einmal, damit die Lockfile existiert, dann:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsschreibt die Payload, die jede Anbindung erhält, nach payloads/, eine Datei pro Anbindung, wo mehrere an einer Rolle unterschiedliche Payloads erhalten — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json —, neben einer Datei für jede andere Rolle, und schreibt sonst nichts.
Die Rego-Richtlinie
policies/support-tier.rego sammelt ihre Entscheidungen unter labels, eine pro Label, die jeweils den Knoten, den Label-Schlüssel und den Wert nennt:
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}Ihre Einstellungen sind das Dokument data der Richtlinie, und sie enthalten das Vokabular der IT-Landschaft:
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-hoursWas jedes eingebaute Plugin schreibt
label-injector wendet eine Liste von Regeln an. Ein Knoten, dessen Labels jedes Paar unter dem match einer Regel enthalten, erhält jedes Paar unter ihrem set, hinzugefügt oder als Ersatz für den Wert eines Labels, das der Knoten bereits trägt. Ein match ohne Paare trifft auf jeden Knoten zu. Es liest die Regeln aus seiner Einstellung rules, wie hier, oder, wenn die Einstellungen keine enthalten, aus der ersten Datei unter sources, die welche enthält. Seine beiden Regeln geben hier jedem Knoten ops.example.com/owner: shop-team und db und cache, den beiden Knoten der Kategorie datastore, backup.example.com/schedule: nightly. web gehört zur Kategorie devtool und erhält keinen Backup-Zeitplan.
selector-tagger schreibt ein Label, immer unter dem Schlüssel tag. Sein Wert stammt aus einer Zuordnung von Component-Namen zu Tags, gelesen aus den Dateien unter sources. Ein Knoten, dessen Component die Zuordnung nicht auflistet, übernimmt die Einstellung default, und ohne default bleibt er ohne tag. policies/tags.yaml ordnet die Datenbank und den Cache zu:
core/datastore/mariadb: orderscore/datastore/redis: sessionsund das default der Anbindung ist untagged, daher erhält web das Tag untagged.
Beide entscheiden allein anhand der Labels eines Knotens und seiner Component. Keines liest die Umgebung, daher schreiben sie in beiden Releases dieselben Labels.
Beide dienen nur label-transform. Bei ir-verdict angebunden, wird jedes zurückgewiesen, bevor es läuft; selector-tagger, dort angebunden, bricht den Build ab mit:
[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 sandboxDas Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example policy-label-transformDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd policy-label-transformBuild
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullDer Katalog der Standardbibliothek liefert hier jede Component, jedes Recipe und Feature sowie die drei Plugin-Entitäten. Sie werden aus hub.aggrega.ai aufgelöst, der Standard-Registry, die .aggrega-config.yaml nennt. Mit einem Checkout des Katalogs (wo Sie einen erhalten), der mit --catalog benannt wird, wird nichts aus einer Registry abgerufen, daher laufen die Builds offline. --auto-pull füllt die Lockfile jedes Release während des Builds; Lockfiles und die gerenderte Ausgabe werden erzeugt, nicht mitgeliefert.
Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `policy-label-transform` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `policy-label-transform` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `policy-label-transform`. Rufen Sie dann das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-staging.yaml` und `release-production.yaml` — jedes Mal mit `workspace_root` auf `policy-label-transform`, `release` auf die jeweilige Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `policy-label-transform/dist/`.Die Labels, mit denen jeder Knoten endet
--ir-graph gibt den Build-Graphen auf der Standardausgabe aus, vor der Zusammenfassung des Builds, und der Graph trägt die Labels jedes Knotens so, wie die Transformationen sie hinterlassen haben. Nach aggrega build --release release-production.yaml --auto-pull --ir-graph lautet web:
"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]}Die ersten drei Labels sind die eigenen der Component; die letzten vier wurden von den drei Transformationen geschrieben. check.sh liest den Graphen jedes Builds und listet die Labels auf, die die Anbindungen geschrieben haben:
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: untaggedNur die beiden Labels der Rego-Richtlinie ändern sich zwischen den Releases.
Sobald ein Build die Lockfile gefüllt hat, gibt aggrega inspect release-production.yaml --ir-graph denselben Graphen aus, ohne zu bauen, vor seiner lesbaren Ansicht des Release, weil die Transformationen ihre Dateien aus der Lockfile lesen. Ohne die Lockfile trägt der Graph, den es ausgibt, keines der Labels, die diese Dateien entscheiden: kein ops.example.com/environment oder ops.example.com/support-tier, und tag: untagged auf jedem Knoten.
Eine Transformation ändert Labels und sonst nichts
Eine Entscheidung bei label-transform nennt einen Knoten, einen Label-Schlüssel und seinen Wert oder verlangt, dass ein Label entfernt wird. Es gibt keine Entscheidung, die einen Knoten hinzufügt, die Component oder Version eines Knotens ändert oder seine Werte berührt, daher kann eine Transformation nichts davon ausdrücken. Eine Entscheidung, die einen Knoten nennt, den der Build nicht hat, wird nicht ignoriert: Der Build bricht mit E0069 ab und nennt den Knoten und das Label, das er nicht setzen konnte.
Die beiden Builds von release-production.yaml, mit diesen Anbindungen und ohne, zeigen es. Ihre Build-Graphen unterscheiden sich in den oben aufgeführten Labels und in nichts anderem. Ihre gerenderte Ausgabe unterscheidet sich überhaupt nicht: Die Compose-Recipes hier rendern keines dieser Labels, daher ist dist/compose/docker-compose.yaml mit den Anbindungen und ohne sie Byte für Byte dieselbe Datei, und check.sh vergleicht die beiden Bäume bei jedem Lauf. Die Labels leben im Build-Graphen, wo das Verdikt sie liest.
Das Verdikt und der Build, den es abbricht
policies/production-support.rego ist bei ir-verdict angebunden, nach den Transformationen, und liest die Labels, die sie geschrieben haben:
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])}Beide Releases werden gebaut: In Staging verlangt das Verdikt nichts, und in Produktion trägt jeder Knoten eine Stufe. Verengen Sie die Abdeckung der Richtlinie, und das Verdikt erfasst den Knoten, den sie auslässt. Wenn supported_categories in .aggrega-config.yaml als [datastore] geschrieben ist, erhält web keine Support-Stufe, und aggrega build --release release-production.yaml --auto-pull bricht ab:
[… 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 violationDer Build endet mit 1 und schreibt kein dist/. release-staging.yaml wird mit der verengten Richtlinie weiterhin gebaut: Seine Knoten tragen das Label staging, und das Verdikt verlangt nichts von ihnen. check.sh erstellt diesen Build in einer Kopie des Workspace, daher muss hier nichts bearbeitet werden, um ihn zu sehen.
Ein Verdikt nimmt an oder weist zurück und tut sonst nichts: Es kann das fehlende Label nicht hinzufügen, um den Build bestehen zu lassen. Welches Label ein Produktionsknoten tragen muss, ist die Regel der IT-Landschaft, geschrieben in ihrer Richtlinie; der Compiler trägt die Labels als Strings in den Graphen und liest keine Bedeutung hinein.
Was das Lockfile festhält
Die Lockfile hält die beiden Arten von Anbindung unterschiedlich fest. Nach einem Produktions-Build trägt release-production.lock jede Transformations-Anbindung unter mutators: — ihr Plugin, ihre Rolle, ihre Einstellungen sowie den Inhalt und den Digest jeder ihrer Dateien — und fixiert jedes Transformations-Plugin unter 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.0Die Verdikt-Anbindung erscheint nur unter verdict_inputs:, über den sha256 ihrer Datei:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoEine Verdikt-Anbindung wird nicht fixiert. Wenn das Verdikt allein angebunden ist — die drei Transformationen aus .aggrega-config.yaml entfernt —, trägt die Lockfile mutators: [] und plugins: [] und die Datei des Verdikts unter verdict_inputs:. Eine Transformation ändert den Build, mit dem der Rest der Pipeline arbeitet, daher hält die Lockfile das Plugin fest, das die Änderung vorgenommen hat; ein Verdikt entscheidet nur, ob der Build abgeschlossen wird.
Jeden Build prüfen
Diese Selbstprüfung läuft in einem Checkout des Dokumentations-Repositorys, das das gemeinsame Build-Hilfsskript enthält, das sie verwendet; eine von aggrega scaffold --example geschriebene Kopie enthält dieses Hilfsskript nicht.
./check.shcheck.sh führt vier Builds über den Build-Release-Helfer aus und prüft jedes Ergebnis gegen das, was diese Seite beschreibt:
release-production.yamlin einer Kopie dieses Workspace ohne Governance-Anbindung, als Referenz;release-staging.yamlundrelease-production.yamlhier, die beide mit den oben aufgeführten Labels auf jedem Knoten abschließen müssen, wobei der Produktionsbaum Byte für Byte dem der Referenz entspricht;release-production.yamlin einer Kopie, deren Richtlinie nur die Kategoriedatastoreabdeckt, die mitE0005und dem obigen Satz abbrechen muss, ohne eine weitere Zurückweisung daneben.
Es gibt eine Zeile pro Build aus, dann die Labels, und endet mit 1, wenn ein Ergebnis abweicht, wobei es die Ausgabe dieses Builds ausgibt:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Die beiden Kopien werden in einem temporären Verzeichnis angelegt, wobei der Katalogpfad in ihrer .aggrega-config.yaml absolut gemacht wird, damit er von dort aus weiterhin aufgelöst wird. Keine Datei in diesem Verzeichnis wird bearbeitet; die beiden hier ausgeführten Builds füllen seine Lockfiles, wie es jeder Build tut. Es verwendet die Binärdatei, die ./build-release.sh auflöst, daher wählt AGGREGA_BIN sie aus, und Argumente nach -- erreichen jeden Build. Es verweigert den Start, solange ein dist/ in diesem Verzeichnis liegt, weil es die Bäume vergleicht, die die Builds schreiben, und es hinterlässt keinen. Sein Exit-Status ist das gesamte Urteil.
Wo der Compiler nicht interpretiert
Der Compiler übergibt jeder Transformation die Knoten und die Umgebung des Release, wendet die Labels an, die sie entscheidet, und übergibt das Ergebnis dem Verdikt. Er weiß nicht, was eine Support-Stufe ist, dass on-call über office-hours steht oder dass ein devtool eine braucht: Diese Bedeutungen sind die Einstellungen und Regeln der Richtlinien. Zu den Rollen, den Payloads und dazu, wie eine Richtlinie ein Label benennt, siehe den Governance-Socket, und dazu, wo Richtlinien im Produkt angesiedelt sind, Governance und Compliance.
Dateien
aggregate.yaml— die Datenbank, der Cache und die Administrationsoberfläche, die mit der Datenbank verdrahtet ist; keine Labels.manifest.yaml— bindet jeden Komponententyp und das Secret-Feature an sein Docker-Compose-Recipe. Von beiden Releases gemeinsam genutzt.release-staging.yaml,release-production.yaml— die beiden Umgebungen..aggrega-config.yaml— die Standard-Registry und die vier Governance-Anbindungen.policies/support-tier.rego— die label-transform-Richtlinie.policies/production-support.rego— das Verdikt.policies/tags.yaml— die Zuordnung von Komponenten zu Tags für den Selector-Tagger.build-release.sh— baut ein Release und gibt dabei den entsprechendenaggrega build-Befehl aus.check.sh— führt die vier Builds aus und prüft jedes Ergebnis.