Una policy che associa Features che nessuno ha scritto: annotazioni iniettate in `annotation-transform`
Una policy di governance fornisce a ogni componente di un negozio il monitoraggio della piattaforma e un ruolo AWS IAM. Lo fa aggiungendo annotazioni. Il Manifest lega due chiavi di annotazione a due Features, e un’annotazione sotto una chiave legata si espande in un’associazione di Feature. Così le annotazioni che la policy aggiunge portano a ciascun componente un ServiceMonitor di Prometheus e un ServiceAccount di Kubernetes, e né l’Aggregate né la Release ne scrivono alcuno.
La policy è associata al ruolo annotation-transform, una volta per ciascun motore di policy compilato nella CLI: Rego e CEL. La prova centrale è una Release di controllo che scrive a mano le stesse annotazioni. Compilata senza alcuna policy, renderizza gli stessi file, byte per byte, della Release che la policy annota.
Che cosa costruisce
| istanza | Component del catalogo | che cosa porta in release.yaml |
|---|---|---|
api | example/compute/service | nulla |
worker | example/compute/service | nulla |
gateway | example/compute/service | la propria annotazione di monitoraggio, con un intervallo di 10 secondi |
Tutti e tre sono compilati per Kubernetes tramite Helm, in dist/shop/helm/. example/compute/service è un Component dimostrativo nel catalogo della libreria standard. Ogni sua istanza deve portare un’associazione core/prometheus-exporter, un requisito che il Component dichiara e il build verifica.
I due binding delle annotazioni
manifest.yaml dà un significato a due chiavi di annotazione:
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_arnUn binding che instrada più sottochiavi prende come valore un oggetto che le nomina ciascuna, quindi feature.aggrega.ai/monitoring prende {interval: …, port: …, path: …}. Un binding che instrada una sola sottochiave prende una stringa, quindi aws-role prende l’ARN del ruolo. L’associazione in cui un’annotazione si espande prende il nome dalla sua chiave. core/aws-irsa dà al proprio ServiceAccount il nome dell’associazione, ed è per questo che quella chiave non contiene né punti né barre.
Associare la policy
.aggrega-config.yaml indica l’hub come proprio registry e nessuna directory di catalogo, e nessuna associazione di governance. La policy viene associata dal file che un build nomina con --config: governance-rego.yaml per il motore Rego, governance-cel.yaml per il motore CEL. Quello Rego recita:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config nomina il file di configurazione globale per quell’esecuzione, al posto di quello che la macchina leggerebbe altrimenti, e il .aggrega-config.yaml di questo workspace vi si sovrappone comunque.
0.9.0 è una versione in cui l’hub pubblica l’entità Plugin di ciascun motore, quindi l’associazione viene risolta dal registry che il workspace legge, oppure dal binario aggrega di quella release, che la contiene. Il motore che viene eseguito è quello compilato nel binario aggrega che esegue il build, qualunque sia la versione che l’associazione nomina. L’oggetto che l’annotazione di monitoraggio prende richiede un motore che inietti un oggetto di sottochiavi, e i motori delle versioni precedenti alla 0.8.7 non lo fanno.
Che cosa legge una policy annotation-transform
Una policy in annotation-transform legge due cose:
input.targetselenca ogni componente che può annotare. Ogni target ha unboundary_path, uncomponent_namee leannotationsche la Release scrive su quel componente, ciascun valore così come è scritto.input.binding_keyselenca le chiavi di annotazione che il Manifest lega.
aggrega build --release <release> --dry-run --policy-input <dir> scrive in <dir> il payload che ciascun ruolo riceve e non scrive nient’altro. Dopo che un build di release.yaml ha riempito il suo lockfile:
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"}}}Le annotations di un target contengono ciò che la Release scrive sul componente stesso. Il valore aggrega.ai/namespace del confine non è tra queste.
La policy
policies/platform-defaults.rego raccoglie una decisione per annotazione sotto annotations. Ogni decisione nomina il target con i due campi sotto cui è stato letto, poi la chiave e il valore:
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)}Ogni regola scatta solo per una chiave in input.binding_keys, quindi la policy non aggiunge nulla a cui un Manifest non abbia dato un significato. Ogni regola salta anche un target che porta già la chiave. Una decisione sotto una chiave che il componente porta già sostituisce il valore che la Release ha scritto. Senza quel test, gateway perderebbe il suo intervallo di 10 secondi a favore dei 30 secondi della policy.
policies/platform-defaults.cel esprime le stesse due decisioni come un’unica espressione, unendo due liste con +. Una chiave di mappa viene testata con in anziché con object.keys, e l’ARN del ruolo viene composto con +, poiché il linguaggio delle espressioni non ha sprintf. La metà dell’espressione relativa al ruolo recita:
+ 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, }),Che cosa renderizza il build
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullscrive dodici file sotto dist/shop/helm/: un Deployment e un Service per ciascun componente, il ServiceMonitor in cui si espande la sua annotazione di monitoraggio e il ServiceAccount in cui si espande la sua annotazione aws-role. Lo spec del ServiceMonitor di api, dall’annotazione che la policy ha iniettato:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsQuello di gateway porta interval: 10s, il valore che scrive la sua voce nella Release. Il ServiceAccount con cui viene eseguito api, dall’annotazione aws-role iniettata:
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]Iniettate o scritte a mano: gli stessi file
release-by-hand.yaml è release.yaml con le annotazioni che la policy inietta scritte a mano su ciascun componente. Compilato senza alcuna policy associata,
aggrega build --release release-by-hand.yaml --auto-pullscrive gli stessi dodici file, byte per byte, di release.yaml con la policy associata sull’uno o sull’altro motore. Nulla è escluso da quel confronto: il fatto che un’annotazione sia stata iniettata non viene registrato in alcun file renderizzato. check.sh confronta gli alberi a ogni esecuzione.
Il build legge un valore iniettato esattamente come legge lo stesso valore scritto nella Release, quindi il valore si espande nella stessa associazione.
Dove viene registrata l’iniezione
Lo registra il grafo di build, e --ir-graph stampa il grafo. Ogni componente che ha ricevuto un’annotazione iniettata porta aggrega.ai/injected-by, che nomina il plugin, tra le sue annotazioni di Release. Dopo aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api riporta:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},La registrazione è per componente, non per chiave: anche gateway la porta, per il suo aws-role. Ogni associazione in cui le annotazioni si sono espanse ha "origin": "annotation" nel grafo, come avverrebbe per un’annotazione scritta a mano.
Il target Helm non renderizza alcuna annotazione aggrega.ai/injected-by, e lo dice. In questo build, ogni componente che ha ricevuto un’iniezione aggiunge tre avvisi all’output. Il primo di quelli di api recita:
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 silenzia quella classe di avvisi e non cambia nulla di ciò che il build scrive.
Il ruolo aggiunge annotazioni, e nient’altro
Una decisione nomina un componente, una chiave di annotazione e il suo valore. Nulla in una decisione aggiunge un componente, cambia un’etichetta o associa direttamente una Feature. La policy raggiunge una Feature solo tramite una chiave che il Manifest lega, ed è il Manifest a decidere quale Feature sia.
Una decisione non può nemmeno rimuovere un’annotazione. Il suo valore è una stringa o un oggetto di sottochiavi, e un null viene rifiutato, con il nome dell’iniezione, perché null è il modo in cui un autore esclude un componente da un’annotazione che erediterebbe.
Una stringa dove il binding instrada tre sottochiavi
governance-monitoring-as-string.yaml associa policies/monitoring-as-string.rego, che inietta la stringa "30s" sotto la chiave di monitoraggio. Quel binding instrada tre sottochiavi, e una stringa non ne nomina nessuna, quindi
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullsi arresta, esce con 1 e non scrive alcun dist/. La policy ha iniettato la stringa su api e su worker, e ciascuna viene rifiutata. Ogni rifiuto nomina il plugin che ha iniettato il valore e il ruolo a cui è associato, così il valore viene ricondotto alla policy che lo ha deciso, anziché a una riga della Release che nessuno ha scritto:
[… 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")Senza la policy
release.yaml compilato senza alcuna associazione di governance,
aggrega build --release release.yaml --auto-pullsi arresta. Il suo Component richiede un’associazione core/prometheus-exporter, e nulla ne fornisce una ad api o a worker:
[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 non viene nominato, perché la sua voce nella Release scrive il proprio monitoraggio. Con la policy associata, la stessa Release viene compilata: un’associazione in cui si espande un’annotazione iniettata soddisfa il requisito, proprio come una scritta a mano.
Che cosa registra il lockfile
Un’associazione annotation-transform cambia ciò che il build renderizza, quindi il lockfile la fissa. Dopo il build Rego, release.lock contiene l’associazione sotto mutators:, con il suo plugin, il suo ruolo, e il contenuto e il digest del suo file di policy:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoFissa anche il plugin sotto 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.0L’associazione nomina una versione che l’hub pubblica, quindi il pin si risolve attraverso il registry che il workspace legge, oppure dal binario aggrega di quella release.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example policy-annotation-transformPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
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-pullIl catalogo della libreria standard fornisce ogni Component, Feature, Recipe e FeatureRecipe usato qui, e le entità Plugin di entrambi i motori. Vengono risolti da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml nomina. Con un checkout del catalogo (dove ottenerne uno) nominato con --catalog, nulla viene scaricato da un registry, quindi i build vengono eseguiti offline. --auto-pull riempie il lockfile di ciascuna Release durante il build. I lockfile e l’output renderizzato sono generati, non forniti.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `policy-annotation-transform`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-annotation-transform` e senza `dir`: scrive l’esempio in una nuova cartella `policy-annotation-transform`. Poi chiama lo strumento `cli-build`, che esegue `aggrega build` e accetta il suo flag `--config`, con `workspace_root` impostato a `policy-annotation-transform`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `config` impostato a `governance-rego.yaml`; poi richiamalo allo stesso modo con `config` impostato a `governance-cel.yaml`. Infine, chiama lo strumento `build` con `workspace_root` impostato a `policy-annotation-transform`, `release` impostato a `release-by-hand.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `policy-annotation-transform/dist/`.Verificare ogni build
Questo controllo automatico viene eseguito in un checkout del repository della documentazione, che contiene lo script di build condiviso che usa; una copia scritta da aggrega scaffold --example non porta con sé quello script.
./check.shcheck.sh esegue cinque build tramite l’helper build-release e verifica ciascun esito rispetto a quello che questa pagina descrive:
release-by-hand.yamlsenza policy è il riferimento. Deve renderizzare i sei file in cui si espandono le annotazioni.release.yamlsenza policy deve arrestarsi conE0162perapieworker, e per nessun altro componente.release.yamlcon la policy viene compilato una volta su ciascun motore. Ogni build deve scrivere byte per byte i file del riferimento, fissare il plugin nel proprio lockfile e registrare tutti e tre i componenti come iniettati da quel plugin.release.yamlcon la stringa piazzata deve arrestarsi con il rifiuto descritto sopra.
Stampa una riga per build, poi i file che i due binding hanno renderizzato, ed esce con 1 se un esito differisce, stampando l’output di quel build:
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.Ogni build viene eseguito in una propria copia di questo workspace, creata in una directory temporanea, con il percorso del catalogo nel suo .aggrega-config.yaml reso assoluto, così che si risolva ancora da lì. In questa directory non viene scritto nulla. Usa il binario che l’helper build-release risolve, quindi AGGREGA_BIN lo sceglie, e gli argomenti dopo -- arrivano a ogni build. Il suo stato di uscita è l’intero verdetto.
Dove il compilatore non interpreta
Il compilatore passa alla policy i componenti e le chiavi legate. Aggiunge le annotazioni che la policy decide e le espande attraverso i binding del Manifest come espande qualsiasi annotazione. Non sa che un servizio dovrebbe essere monitorato, che cos’è un intervallo di scrape o con quale ruolo IAM un componente dovrebbe essere eseguito: quei significati appartengono alla policy e al Manifest. Per i ruoli, i payload e le chiavi di decisione, vedi il socket di governance. Per l’espansione delle annotazioni senza policy, vedi annotation-driven-monitoring.
File
aggregate.yaml— i tre servizi, senza alcuna annotazione.manifest.yaml— lega il tipo di componente e le due Features alle loro Recipes Helm, e le due chiavi di annotazione alle due Features.release.yaml— la Release che la policy annota; sologatewayscrive un’annotazione.release-by-hand.yaml— il controllo: ogni annotazione scritta a mano..aggrega-config.yaml— il registry predefinito; nessuna associazione di governance.governance-rego.yaml,governance-cel.yaml— la policy associata inannotation-transformtramite ciascun motore, ciascuno nominato con--config.governance-monitoring-as-string.yaml— l’errore piazzato, nominato con--config.policies/platform-defaults.rego,policies/platform-defaults.cel— la policy, una volta per motore.policies/monitoring-as-string.rego— l’errore piazzato.build-release.sh— esegue il build di una Release, mostrando il comandoaggrega buildequivalente.check.sh— esegue i cinque build e verifica ciascun esito.