Policy che modellano le etichette: un livello di supporto per ambiente, e un verdetto che lo legge
I plugin di governance etichettano ogni componente che questo workspace distribuisce con il suo proprietario, il livello di supporto che il suo ambiente gli assegna, la sua pianificazione dei backup e un tag breve, così che nessuno sviluppatore ne digiti alcuno. Le etichette vengono derivate durante la build, da quattro associazioni di governance:
- tre al ruolo
label-transform, che modellano le etichette sui nodi della build: una policy Rego che legge l’ambiente della Release, e i due plugin di tagging compilati nella CLI,label-injectoreselector-tagger; - una al ruolo
ir-verdict, una policy Rego sul grafo di build che arresta una build di produzione in cui un nodo è rimasto senza livello di supporto.
Due Releases di un Aggregate differiscono per il loro ambiente, staging e production, e i loro nodi finiscono con etichette diverse. Una terza build, che check.sh esegue da una copia di questo workspace la cui policy copre una categoria in meno, si arresta e nomina il nodo che ha lasciato fuori.
Che cosa costruisce
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
db | core/datastore/mariadb | il database del negozio |
cache | core/datastore/redis | la sua cache di sessione |
web | core/devtool/adminer | un’interfaccia di amministrazione del database, cablata a db |
Tutti e tre sono compilati per Docker Compose, in dist/compose/docker-compose.yaml. L’Aggregate ed entrambe le Releases non nominano alcuna etichetta propria: ogni etichetta riportata sotto è scritta da un’associazione.
Le quattro associazioni
Sono associate nel .aggrega-config.yaml di questo workspace, sotto plugins.governance, quindi ogni build eseguita qui le applica:
| plugin | ruolo | che cosa scrive | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, con policies/support-tier.rego | label-transform | ops.example.com/environment su ogni nodo; ops.example.com/support-tier su ogni nodo la cui categoria è elencata nelle sue impostazioni |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner su ogni nodo; backup.example.com/schedule su ogni nodo della categoria datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, dalla mappa in policies/tags.yaml |
| 4 | governance/rego:0.9.0, con policies/production-support.rego | ir-verdict | nulla: arresta la build, o la lascia completare |
0.9.0 è la versione delle tre entità Plugin nel catalogo della libreria standard; i plugin stessi sono compilati nella CLI, e una build li serve da lì. aggrega build --release release-production.yaml --auto-pull --detail elenca entrambi, per ciascuno dei tre:
[… 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]Le associazioni a uno stesso ruolo vengono eseguite nell’ordine in cui sono elencate, e ciascuna legge le etichette scritte da quelle che la precedono: l’iniettore di etichette riceve le due etichette scritte dalla policy Rego, e il tagger dei selettori riceve quelle e quelle dell’iniettore di etichette. Il verdetto viene eseguito dopo tutte e tre, sul grafo che lasciano.
Che cosa legge una policy label-transform
Una policy in label-transform legge i nodi in input.graph.nodes, indicizzati per id di nodo, ciascuno con:
component— il Component che il nodo istanzia, comecore/datastore/mariadb;resolved_version— la versione a cui quel Component si è risolto;labels— le etichette che il nodo porta quando la policy viene eseguita: quelle proprie del Component, e quelle scritte da qualsiasi trasformazione precedente;values— i valori che l’istanza del nodo dichiara nell’Aggregate, assente dove non ne dichiara nessuno. Qui solodbne dichiara uno,database: appdb.
Legge la Release in input.compilation_context: release_name e environment. È questo che permette a una sola policy di decidere in modo diverso per ambiente.
Una policy in ir-verdict legge invece l’intero grafo di build, e i suoi nodi si trovano un livello più in profondità, in input.graph.spec.nodes. Una regola spostata da un ruolo all’altro va modificata, non copiata: con il percorso sbagliato non legge nulla e non scatta mai. Il payload di ir-verdict non porta alcun compilation_context, quindi un verdetto non può leggere l’ambiente dalla Release. Per questo la prima policy qui scrive anche ops.example.com/environment su ogni nodo: il verdetto legge l’ambiente da quell’etichetta.
Per vedere i payload anziché leggerne la descrizione, esegui una build una volta perché il lockfile esista, poi:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsscrive il payload che ciascuna associazione riceve in payloads/, un file per associazione dove più associazioni a uno stesso ruolo ricevono payload diversi — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — accanto a un file per ciascun altro ruolo, e non scrive nient’altro.
La policy Rego
policies/support-tier.rego raccoglie le sue decisioni sotto labels, una per etichetta, ciascuna con il nodo, la chiave dell’etichetta e il valore:
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}Le sue impostazioni sono il documento data della policy, e contengono il vocabolario del parco IT:
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-hoursChe cosa scrive ciascun plugin integrato
label-injector applica un elenco di regole. Un nodo le cui etichette includono ogni coppia sotto il match di una regola riceve ogni coppia sotto il suo set, aggiunta, o in sostituzione del valore di un’etichetta che il nodo porta già. Un match senza coppie corrisponde a ogni nodo. Legge le regole dalla sua impostazione rules, come qui, oppure, quando le impostazioni non ne contengono, dal primo file sotto sources che ne contiene. Le sue due regole qui danno a ogni nodo ops.example.com/owner: shop-team, e a db e cache, i due nodi della categoria datastore, backup.example.com/schedule: nightly. web è nella categoria devtool e non riceve alcuna pianificazione dei backup.
selector-tagger scrive un’etichetta, sempre sotto la chiave tag. Il suo valore proviene da una mappa di nomi di Component a tag, letta dai file sotto sources. Un nodo il cui Component non è elencato nella mappa prende l’impostazione default, e senza default resta senza tag. policies/tags.yaml mappa il database e la cache:
core/datastore/mariadb: orderscore/datastore/redis: sessionse il default dell’associazione è untagged, quindi web riceve il tag untagged.
Entrambi decidono solo in base alle etichette di un nodo e al suo Component. Nessuno dei due legge l’ambiente, quindi scrivono le stesse etichette in entrambe le Releases.
Entrambi servono solo label-transform. Associato in ir-verdict, ciascuno dei due viene rifiutato prima di essere eseguito; selector-tagger associato lì arresta la build con:
[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 sandboxGenerare 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-label-transformPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd policy-label-transformBuild
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullIl catalogo della libreria standard fornisce ogni Component, Recipe e Feature usato qui, e le tre entità Plugin. Vengono risolti da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml nomina. Con un checkout del catalogo (dove ottenerne uno) indicato con --catalog, nulla viene scaricato da un registry, quindi le build vengono eseguite offline. --auto-pull riempie il lockfile di ciascuna Release durante la build; i lockfile e l’output renderizzato sono generati, non distribuiti.
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-label-transform`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-label-transform` e senza `dir`: scrive l’esempio in una nuova cartella `policy-label-transform`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-staging.yaml` e `release-production.yaml` — ogni volta con `workspace_root` impostato a `policy-label-transform`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `policy-label-transform/dist/`.Le etichette con cui finisce ciascun nodo
--ir-graph stampa il grafo di build sullo standard output, prima del riepilogo della build, e il grafo porta le etichette di ciascun nodo così come le trasformazioni le hanno lasciate. Dopo aggrega build --release release-production.yaml --auto-pull --ir-graph, web riporta:
"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]}Le prime tre etichette sono quelle proprie del Component; le ultime quattro sono state scritte dalle tre trasformazioni. check.sh legge il grafo di ciascuna build ed elenca le etichette scritte dalle associazioni:
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: untaggedSolo le due etichette della policy Rego cambiano tra le Releases.
Una volta che una build ha riempito il lockfile, aggrega inspect release-production.yaml --ir-graph stampa lo stesso grafo senza eseguire la build, prima della sua vista leggibile della Release, perché le trasformazioni leggono i propri file dal lockfile. Senza il lockfile, il grafo che stampa non porta nessuna delle etichette che quei file decidono: nessun ops.example.com/environment o ops.example.com/support-tier, e tag: untagged su ogni nodo.
Una trasformazione cambia le etichette e nient’altro
Una decisione in label-transform nomina un nodo, una chiave di etichetta e il suo valore, oppure chiede che un’etichetta venga eliminata. Non esiste alcuna decisione che aggiunga un nodo, cambi il Component o la versione di un nodo, o tocchi i suoi valori, quindi una trasformazione non può esprimere nessuna di queste cose. Una decisione che nomina un nodo che la build non ha non viene ignorata: la build si arresta con E0069 e nomina il nodo e l’etichetta che non ha potuto impostare.
Le due build di release-production.yaml, con queste associazioni e senza alcuna, lo mostrano. I loro grafi di build differiscono nelle etichette elencate sopra e in nient’altro. Il loro output renderizzato non differisce affatto: le Recipes Compose qui non renderizzano nessuna di queste etichette, quindi dist/compose/docker-compose.yaml è lo stesso file, byte per byte, con le associazioni e senza, e check.sh confronta i due alberi a ogni esecuzione. Le etichette vivono nel grafo di build, dove il verdetto le legge.
Il verdetto, e la build che arresta
policies/production-support.rego è associata in ir-verdict, dopo le trasformazioni, e legge le etichette che queste hanno scritto:
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])}Entrambe le Releases vengono compilate: in staging il verdetto non chiede nulla, e in produzione ogni nodo porta un livello. Restringi la copertura della policy, e il verdetto coglie il nodo che lascia fuori. Con supported_categories scritto [datastore] in .aggrega-config.yaml, web non riceve alcun livello di supporto, e aggrega build --release release-production.yaml --auto-pull si arresta:
[… 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 violationLa build esce con 1 e non scrive alcun dist/. release-staging.yaml viene ancora compilato con la policy ristretta: i suoi nodi sono etichettati staging, e il verdetto non chiede loro nulla. check.sh esegue questa build in una copia del workspace, quindi qui non occorre modificare nulla per vederla.
Un verdetto accetta o rifiuta e non fa nient’altro: non può aggiungere l’etichetta mancante per far passare la build. Quale etichetta debba portare un nodo di produzione è una regola del parco IT, scritta nella sua policy; il compilatore porta le etichette nel grafo come stringhe e non vi attribuisce alcun significato.
Che cosa registra il lockfile
Il lockfile registra i due tipi di associazione in modo diverso. Dopo una build di produzione, release-production.lock porta ciascuna associazione di trasformazione sotto mutators: — il suo plugin, il suo ruolo, le sue impostazioni, e il contenuto e il digest di ciascuno dei suoi file — e fissa ciascun plugin di trasformazione sotto 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.0L’associazione del verdetto compare solo sotto verdict_inputs:, tramite lo sha256 del suo file:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoUn’associazione di verdetto non viene fissata. Con il verdetto associato da solo — le tre trasformazioni rimosse da .aggrega-config.yaml — il lockfile porta mutators: [] e plugins: [], e il file del verdetto sotto verdict_inputs:. Una trasformazione cambia la build su cui lavora il resto della pipeline, quindi il lockfile contiene il plugin che ha fatto la modifica; un verdetto decide solo se la build si completa.
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 quattro build tramite l’helper build-release e verifica ciascun esito rispetto a quello che questa pagina descrive:
release-production.yamlin una copia di questo workspace senza alcuna associazione di governance, come riferimento;release-staging.yamlerelease-production.yamlqui, ciascuna delle quali deve completarsi con le etichette elencate sopra su ogni nodo, con l’albero di produzione identico byte per byte a quello del riferimento;release-production.yamlin una copia la cui policy copre solo la categoriadatastore, che deve arrestarsi conE0005e la frase riportata sopra, senza nessun altro rifiuto accanto.
Stampa una riga per build, poi le etichette, ed esce con 1 se un esito differisce, stampando l’output di quella build:
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.Le due copie vengono create in una directory temporanea, con il percorso del catalogo nel loro .aggrega-config.yaml reso assoluto così che si risolva ancora da lì. Nessun file in questa directory viene modificato; le due build eseguite qui ne riempiono i lockfile, come fa qualsiasi build. Usa il binario che ./build-release.sh risolve, quindi AGGREGA_BIN lo sceglie, e gli argomenti dopo -- arrivano a ogni build. Si rifiuta di partire finché in questa directory si trova un dist/, perché confronta gli alberi che le build scrivono, e non ne lascia nessuno dietro di sé. Il suo stato di uscita è l’intero verdetto.
Dove il compilatore non interpreta
Il compilatore passa a ciascuna trasformazione i nodi e l’ambiente della Release, applica le etichette che questa decide e passa il risultato al verdetto. Non sa che cos’è un livello di supporto, che on-call è superiore a office-hours, né che un devtool ne richiede uno: quei significati sono le impostazioni e le regole delle policy. Per i ruoli, i payload e il modo in cui una policy nomina un’etichetta, vedi il socket di governance, e per la collocazione delle policy nel prodotto, Governance e conformità.
File
aggregate.yaml— il database, la cache e l’interfaccia di amministrazione cablata al database; nessuna etichetta.manifest.yaml— lega ogni tipo di componente e la Feature dei secret alla sua Recipe Docker Compose. Condiviso da entrambe le Releases.release-staging.yaml,release-production.yaml— i due ambienti..aggrega-config.yaml— il registry predefinito e le quattro associazioni di governance.policies/support-tier.rego— la policy label-transform.policies/production-support.rego— il verdetto.policies/tags.yaml— la mappa dai componenti ai tag del tagger dei selettori.build-release.sh— esegue il build di una Release, mostrando il comandoaggrega buildequivalente.check.sh— esegue le quattro build e verifica ciascun esito.