Eine Richtlinie, die Features anbindet, die niemand geschrieben hat: Annotationen, injiziert bei `annotation-transform`
Eine Governance-Richtlinie gibt jeder Komponente eines Shops das Monitoring der Plattform und eine AWS-IAM-Rolle. Sie tut das, indem sie Annotationen hinzufügt. Das Manifest bindet zwei Annotationsschlüssel an zwei Features, und eine Annotation unter einem gebundenen Schlüssel wird zu einer Feature-Anbindung expandiert. So bringen die Annotationen, die die Richtlinie hinzufügt, jeder Komponente einen Prometheus-ServiceMonitor und einen Kubernetes-ServiceAccount, und weder das Aggregate noch das Release schreibt eines davon.
Die Richtlinie wird an der Rolle annotation-transform angebunden, einmal für jede in die CLI kompilierte Richtlinien-Engine: Rego und CEL. Der zentrale Nachweis ist ein Kontroll-Release, das dieselben Annotationen von Hand schreibt. Ohne Richtlinie gebaut, rendert es dieselben Dateien, Byte für Byte, wie das Release, das die Richtlinie annotiert.
Was es baut
| Instanz | Katalog-Component | was sie in release.yaml trägt |
|---|---|---|
api | example/compute/service | nichts |
worker | example/compute/service | nichts |
gateway | example/compute/service | ihre eigene Monitoring-Annotation, mit einem Intervall von 10 Sekunden |
Alle drei werden über Helm für Kubernetes kompiliert, nach dist/shop/helm/. example/compute/service ist eine Demonstrations-Component im Katalog der Standardbibliothek. Jede ihrer Instanzen muss eine Anbindung core/prometheus-exporter tragen — eine Anforderung, die die Component angibt und der Build prüft.
Die beiden Annotations-Bindungen
manifest.yaml gibt zwei Annotationsschlüsseln eine Bedeutung:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnEine Bindung, die mehrere Unterschlüssel weiterleitet, nimmt als Wert ein Objekt, das jeden von ihnen benennt, daher nimmt feature.aggrega.ai/monitoring {interval: …, port: …, path: …}. Eine Bindung, die einen einzigen Unterschlüssel weiterleitet, nimmt einen String, daher nimmt aws-role den ARN der Rolle. Die Anbindung, zu der eine Annotation expandiert wird, ist nach ihrem Schlüssel benannt. core/aws-irsa benennt seinen ServiceAccount nach der Anbindung, weshalb dieser Schlüssel weder Punkt noch Schrägstrich enthält.
Die Richtlinie anbinden
.aggrega-config.yaml nennt den Hub als seine Registry und kein Katalogverzeichnis, und keine Governance-Anbindung. Die Richtlinie wird durch die Datei angebunden, die ein Build mit --config benennt: governance-rego.yaml für die Rego-Engine, governance-cel.yaml für die CEL-Engine. Die Rego-Datei lautet:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config benennt die globale Konfigurationsdatei für diesen Lauf, anstelle derjenigen, die die Maschine sonst lesen würde, und die .aggrega-config.yaml dieses Workspace legt sich weiterhin darüber.
0.9.0 ist eine Version, in der der Hub die Plugin-Entität jeder Engine veröffentlicht, sodass die Anbindung aus der Registry aufgelöst wird, die der Workspace liest, oder aus der Binärdatei aggrega dieser Version, die sie enthält. Die Engine, die läuft, ist diejenige, die in die Binärdatei aggrega kompiliert ist, die den Build ausführt, unabhängig davon, welche Version die Anbindung nennt. Das Objekt, das die Monitoring-Annotation nimmt, benötigt eine Engine, die ein Objekt aus Unterschlüsseln injiziert, und die Engines von Versionen vor 0.8.7 tun das nicht.
Was eine annotation-transform-Richtlinie liest
Eine Richtlinie bei annotation-transform liest zwei Dinge:
input.targetslistet jede Komponente auf, die sie annotieren darf. Jedes Ziel hat einenboundary_path, einencomponent_nameund dieannotations, die das Release auf diese Komponente schreibt, jeden Wert so, wie er geschrieben ist.input.binding_keyslistet die Annotationsschlüssel auf, die das Manifest bindet.
aggrega build --release <release> --dry-run --policy-input <dir> schreibt die Payload, die jede Rolle erhält, nach <dir> und schreibt sonst nichts. Nachdem ein Build von release.yaml seine Lockfile gefüllt hat:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}Die annotations eines Ziels enthalten, was das Release auf die Komponente selbst schreibt. Der Wert aggrega.ai/namespace der Boundary gehört nicht dazu.
Die Richtlinie
policies/platform-defaults.rego sammelt eine Entscheidung pro Annotation unter annotations. Jede Entscheidung benennt das Ziel über die beiden Felder, unter denen es gelesen wurde, dann den Schlüssel und den Wert:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Jede Regel greift nur für einen Schlüssel in input.binding_keys, daher fügt die Richtlinie nichts hinzu, dem ein Manifest keine Bedeutung gegeben hat. Jede Regel überspringt außerdem ein Ziel, das den Schlüssel bereits trägt. Eine Entscheidung unter einem Schlüssel, den die Komponente bereits trägt, ersetzt den Wert, den das Release geschrieben hat. Ohne diese Prüfung würde gateway sein 10-Sekunden-Intervall an die 30 Sekunden der Richtlinie verlieren.
policies/platform-defaults.cel drückt dieselben beiden Entscheidungen als einen einzigen Ausdruck aus und verbindet zwei Listen mit +. Ein Map-Schlüssel wird mit in statt mit object.keys geprüft, und der ARN der Rolle wird mit + zusammengesetzt, da die Ausdruckssprache kein sprintf hat. Die Hälfte des Ausdrucks für die Rolle lautet:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),Was der Build rendert
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullschreibt zwölf Dateien unter dist/shop/helm/: ein Deployment und einen Service für jede Komponente, den ServiceMonitor, zu dem ihre Monitoring-Annotation expandiert wird, und den ServiceAccount, zu dem ihre Annotation aws-role expandiert wird. Die spec des ServiceMonitor von api, aus der Annotation, die die Richtlinie injiziert hat:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsDer von gateway trägt interval: 10s, den Wert, den sein Release-Eintrag schreibt. Der ServiceAccount, unter dem api läuft, aus der injizierten Annotation aws-role:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Injiziert oder von Hand geschrieben: dieselben Dateien
release-by-hand.yaml ist release.yaml mit den Annotationen, die die Richtlinie injiziert, von Hand auf jede Komponente geschrieben. Ohne angebundene Richtlinie gebaut,
aggrega build --release release-by-hand.yaml --auto-pullschreibt es dieselben zwölf Dateien, Byte für Byte, wie release.yaml mit der auf einer der beiden Engines angebundenen Richtlinie. Nichts ist von diesem Vergleich ausgenommen: Ob eine Annotation injiziert wurde, wird in keiner gerenderten Datei festgehalten. check.sh vergleicht die Bäume bei jedem Lauf.
Der Build liest einen injizierten Wert genau so, wie er denselben im Release geschriebenen Wert liest, daher wird der Wert zu derselben Anbindung expandiert.
Wo die Injektion festgehalten wird
Der Build-Graph hält sie fest, und --ir-graph gibt den Graphen aus. Jede Komponente, die eine injizierte Annotation erhalten hat, trägt unter ihren Release-Annotationen aggrega.ai/injected-by, das das Plugin benennt. Nach aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph lautet api:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},Der Eintrag gilt pro Komponente, nicht pro Schlüssel: Auch gateway trägt ihn, für seine aws-role. Jede Anbindung, zu der die Annotationen expandiert wurden, hat "origin": "annotation" im Graphen, wie es auch bei einer von Hand geschriebenen Annotation der Fall wäre.
Das Helm-Ziel rendert keine Annotation aggrega.ai/injected-by, und es sagt das. In diesem Build fügt jede Komponente, die eine Injektion erhalten hat, der Ausgabe drei Warnungen hinzu. Die erste von api lautet:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings unterdrückt diese Klasse von Warnungen und ändert nichts an dem, was der Build schreibt.
Die Rolle fügt Annotationen hinzu, und sonst nichts
Eine Entscheidung benennt eine Komponente, einen Annotationsschlüssel und seinen Wert. Nichts in einer Entscheidung fügt eine Komponente hinzu, ändert ein Label oder bindet direkt ein Feature an. Die Richtlinie erreicht ein Feature nur über einen Schlüssel, den das Manifest bindet, und das Manifest entscheidet, welches Feature das ist.
Eine Entscheidung kann auch keine Annotation entfernen. Ihr Wert ist ein String oder ein Objekt aus Unterschlüsseln, und ein null wird unter Nennung der Injektion zurückgewiesen, weil null die Art ist, wie ein Autor eine Komponente von einer Annotation ausnimmt, die sie erben würde.
Ein String, wo die Bindung drei Unterschlüssel weiterleitet
governance-monitoring-as-string.yaml bindet policies/monitoring-as-string.rego an, das den String "30s" unter dem Monitoring-Schlüssel injiziert. Diese Bindung leitet drei Unterschlüssel weiter, und ein String benennt keinen davon, daher
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullbricht ab, endet mit 1 und schreibt kein dist/. Die Richtlinie hat den String auf api und auf worker injiziert, und jeder wird zurückgewiesen. Jede Zurückweisung benennt das Plugin, das den Wert injiziert hat, und die Rolle, an der es angebunden ist, sodass der Wert auf die Richtlinie zurückgeführt wird, die ihn entschieden hat, statt auf eine Zeile des Release, die niemand geschrieben hat:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Ohne die Richtlinie
release.yaml, ohne Governance-Anbindung gebaut,
aggrega build --release release.yaml --auto-pullbricht ab. Seine Component erfordert eine Anbindung core/prometheus-exporter, und nichts gibt api oder worker eine:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway wird nicht genannt, weil sein Release-Eintrag sein eigenes Monitoring schreibt. Mit angebundener Richtlinie wird dasselbe Release gebaut: Eine Anbindung, zu der eine injizierte Annotation expandiert wird, erfüllt die Anforderung, genau wie eine von Hand geschriebene.
Was das Lockfile festhält
Eine Anbindung annotation-transform ändert, was der Build rendert, daher fixiert die Lockfile sie. Nach dem Rego-Build trägt release.lock die Anbindung unter mutators:, mit ihrem Plugin, ihrer Rolle sowie dem Inhalt und dem Digest ihrer Richtliniendatei:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoSie fixiert außerdem das Plugin unter plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0Die Anbindung nennt eine Version, die der Hub veröffentlicht, daher wird die Fixierung über die Registry aufgelöst, die der Workspace liest, oder aus der Binärdatei aggrega dieser Version.
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:
aggrega scaffold --example policy-annotation-transformDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd policy-annotation-transformBuild
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullDer Katalog der Standardbibliothek liefert hier jede Component, jedes Feature, Recipe und FeatureRecipe sowie die Plugin-Entitäten beider Engines. 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-annotation-transform` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `policy-annotation-transform` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `policy-annotation-transform`. Rufen Sie dann das Tool `cli-build` auf, das `aggrega build` ausführt und dessen Flag `--config` annimmt, mit `workspace_root` auf `policy-annotation-transform`, `release` auf `release.yaml`, `auto_pull` auf true und `config` auf `governance-rego.yaml` gesetzt; rufen Sie es anschließend auf dieselbe Weise erneut auf, mit `config` auf `governance-cel.yaml` gesetzt. Rufen Sie zuletzt das Tool `build` auf, mit `workspace_root` auf `policy-annotation-transform`, `release` auf `release-by-hand.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `policy-annotation-transform/dist/`.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 fünf Builds über den Build-Release-Helfer aus und prüft jedes Ergebnis gegen das, was diese Seite beschreibt:
release-by-hand.yamlohne Richtlinie ist die Referenz. Es muss die sechs Dateien rendern, zu denen die Annotationen expandiert werden.release.yamlohne Richtlinie muss mitE0162fürapiundworkerabbrechen, und für keine andere Komponente.release.yamlmit der Richtlinie wird einmal auf jeder Engine gebaut. Jeder Build muss die Dateien der Referenz Byte für Byte schreiben, das Plugin in seiner Lockfile fixieren und alle drei Komponenten als von diesem Plugin injiziert festhalten.release.yamlmit dem eingeschleusten String muss mit der oben gezeigten Zurückweisung abbrechen.
Es gibt eine Zeile pro Build aus, dann die Dateien, die die beiden Bindungen gerendert haben, und endet mit 1, wenn ein Ergebnis abweicht, wobei es die Ausgabe dieses Builds ausgibt:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Jeder Build läuft in einer eigenen Kopie dieses Workspace, die in einem temporären Verzeichnis angelegt wird, wobei der Katalogpfad in ihrer .aggrega-config.yaml absolut gemacht wird, damit er von dort aus weiterhin aufgelöst wird. In diesem Verzeichnis wird nichts geschrieben. Es verwendet die Binärdatei, die der Build-Release-Helfer auflöst, daher wählt AGGREGA_BIN sie aus, und Argumente nach -- erreichen jeden Build. Sein Exit-Status ist das gesamte Urteil.
Wo der Compiler nicht interpretiert
Der Compiler übergibt der Richtlinie die Komponenten und die gebundenen Schlüssel. Er fügt die Annotationen hinzu, die die Richtlinie entscheidet, und expandiert sie über die Bindungen des Manifest, so wie er jede Annotation expandiert. Er weiß nicht, dass ein Service überwacht werden sollte, was ein Scrape-Intervall ist oder unter welcher IAM-Rolle eine Komponente laufen sollte: Diese Bedeutungen gehören der Richtlinie und dem Manifest. Zu den Rollen, den Payloads und den Entscheidungsschlüsseln siehe den Governance-Socket. Zur Expansion von Annotationen ohne Richtlinie siehe annotation-driven-monitoring.
Dateien
aggregate.yaml— die drei Services, ohne Annotation.manifest.yaml— bindet den Komponententyp und die beiden Features an ihre Helm-Recipes und die beiden Annotationsschlüssel an die beiden Features.release.yaml— das Release, das die Richtlinie annotiert; nurgatewayschreibt eine Annotation.release-by-hand.yaml— die Kontrolle: jede Annotation von Hand geschrieben..aggrega-config.yaml— die Standard-Registry; keine Governance-Anbindung.governance-rego.yaml,governance-cel.yaml— die Richtlinie, über jede Engine beiannotation-transformangebunden, jeweils mit--configbenannt.governance-monitoring-as-string.yaml— der eingeschleuste Fehler, mit--configbenannt.policies/platform-defaults.rego,policies/platform-defaults.cel— die Richtlinie, einmal pro Engine.policies/monitoring-as-string.rego— der eingeschleuste Fehler.build-release.sh— baut ein Release und gibt dabei den entsprechendenaggrega build-Befehl aus.check.sh— führt die fünf Builds aus und prüft jedes Ergebnis.