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

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

InstanzKatalog-Componentwas sie in release.yaml trägt
apiexample/compute/servicenichts
workerexample/compute/servicenichts
gatewayexample/compute/serviceihre 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_arn

Eine 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.targets listet jede Komponente auf, die sie annotieren darf. Jedes Ziel hat einen boundary_path, einen component_name und die annotations, die das Release auf diese Komponente schreibt, jeden Wert so, wie er geschrieben ist.
  • input.binding_keys listet 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:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

schreibt 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: /metrics

Der 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: v1
kind: ServiceAccount
metadata:
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,

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

schreibt 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

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

bricht 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,

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

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

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

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

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

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

Terminal window
cd policy-annotation-transform

Build

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

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

Terminal window
./check.sh

check.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.yaml ohne Richtlinie ist die Referenz. Es muss die sechs Dateien rendern, zu denen die Annotationen expandiert werden.
  • release.yaml ohne Richtlinie muss mit E0162 für api und worker abbrechen, und für keine andere Komponente.
  • release.yaml mit 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.yaml mit 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' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string 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; nur gateway schreibt 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 bei annotation-transform angebunden, jeweils mit --config benannt.
  • governance-monitoring-as-string.yaml — der eingeschleuste Fehler, mit --config benannt.
  • 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 entsprechenden aggrega build-Befehl aus.
  • check.sh — führt die fünf Builds aus und prüft jedes Ergebnis.