Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

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-injector und selector-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

InstanzKatalog-Componentwas es hier ist
dbcore/datastore/mariadbdie Datenbank des Shops
cachecore/datastore/redisihr Session-Cache
webcore/devtool/adminereine 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:

PluginRollewas es schreibt
1governance/rego:0.9.0, mit policies/support-tier.regolabel-transformops.example.com/environment auf jedem Knoten; ops.example.com/support-tier auf jedem Knoten, dessen Kategorie seine Einstellungen auflisten
2governance/label-injector:0.9.0label-transformops.example.com/owner auf jedem Knoten; backup.example.com/schedule auf jedem Knoten der Kategorie datastore
3governance/selector-tagger:0.9.0label-transformtag, aus der Zuordnung in policies/tags.yaml
4governance/rego:0.9.0, mit policies/production-support.regoir-verdictnichts: 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, etwa core/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 nur db einen, 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:

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

schreibt 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-hours

Was 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: orders
core/datastore/redis: sessions

und 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 sandbox

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

Terminal window
aggrega scaffold --example policy-label-transform

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

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

Der 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: untagged

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

Der 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.0

Die 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.rego

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

Terminal window
./check.sh

check.sh führt vier Builds über den Build-Release-Helfer aus und prüft jedes Ergebnis gegen das, was diese Seite beschreibt:

  • release-production.yaml in einer Kopie dieses Workspace ohne Governance-Anbindung, als Referenz;
  • release-staging.yaml und release-production.yaml hier, 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.yaml in einer Kopie, deren Richtlinie nur die Kategorie datastore abdeckt, die mit E0005 und 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 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.

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 entsprechenden aggrega build-Befehl aus.
  • check.sh — führt die vier Builds aus und prüft jedes Ergebnis.