Una policy sull’output renderizzato: una regola interna, quattro target, due motori
Una regola interna, associata al ruolo render-verdict, giudica i file che una build scrive per quattro target e rifiuta una violazione piazzata su ciascuno. La regola ha due clausole:
Ogni immagine di container indica una versione fissa — un tag diverso da
latest, oppure un digest. Ogni istanza di database memorizza i propri dati cifrati.
Questo workspace esegue la build di un Aggregate per quattro target — Kubernetes tramite Helm, Docker Compose, Terraform e CloudFormation. Il ruolo render-verdict giudica i file che una build scrive, dopo che ogni target li ha renderizzati, e la regola legge la struttura di output propria di ciascun target: le immagini negli oggetti Kubernetes e in un file Compose, l’istanza RDS in un file Terraform e in un template CloudFormation. Ogni target ha una Release che passa e una Release con una violazione piazzata, che la regola rifiuta.
La regola è scritta due volte, una per ciascun motore di policy compilato nella CLI — Rego e CEL — e le due copie concordano su ogni build qui. Uno script accanto alle Releases esegue la build di tutte e sedici le combinazioni e verifica ciascun esito.
aggrega buildla tua policy
inserita nel compilatore
esito positivo
file scritti
pronti da revisionare e distribuire
esito negativo
compilazione interrotta
Una policy può interrompere una compilazione e indicare cosa correggere. Non modifica mai i tuoi file per farli passare.
Che cosa costruisce
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
db | core/datastore/postgres | il database degli ordini |
report | core/compute/task | un job di report che legge db, avviato a mano: porta core/manual-trigger, quindi nessuna esecuzione parte quando la Release viene distribuita |
report legge l’indirizzo, la porta e il nome del database tramite la sua connessione database, come DB_HOST, DB_PORT e DB_NAME. L’Aggregate è lo stesso file per ogni build; ogni Release nomina il Manifest che sceglie il target:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, uno StatefulSet | helm/task, un CronJob mantenuto sospeso |
manifest-compose.yaml | compose/postgres, un servizio | compose/task, un servizio dietro un profilo |
manifest-terraform.yaml | terraform/postgres-rds, un’istanza RDS | terraform/task-ecs, una definizione di task Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, un’istanza RDS | cloudformation/task-ecs, una definizione di task Amazon ECS |
Ogni Recipe qui renderizza dal solo catalogo: il database Kubernetes è sintetizzato anziché scaricato come chart, il corpo del database Terraform è scritto dalla sua Recipe, e il modulo del task Terraform è tenuto accanto alla sua Recipe. Così ogni build viene eseguita offline.
Le otto Releases
| Release | destinazione | che cosa trova la regola | il build |
|---|---|---|---|
release-helm.yaml | Kubernetes | report esegue registry.example.com/orders-report:1.4.2 | va a buon fine |
release-helm-unpinned.yaml | Kubernetes | report esegue la stessa immagine con il tag latest | si arresta |
release-compose.yaml | Docker Compose | report esegue registry.example.com/orders-report:1.4.2 | va a buon fine |
release-compose-unpinned.yaml | Docker Compose | report esegue l’immagine senza tag | si arresta |
release-terraform.yaml | Terraform | l’istanza è cifrata con la chiave che la Release nomina | va a buon fine |
release-terraform-unencrypted.yaml | Terraform | la Release non nomina alcuna chiave, quindi l’istanza non è cifrata | si arresta |
release-cloudformation.yaml | CloudFormation | la Release attiva StorageEncrypted | va a buon fine |
release-cloudformation-unencrypted.yaml | CloudFormation | la Release lo lascia disattivato | si arresta |
L’immagine è della Release: core/compute/task non impacchetta alcun software, quindi la Release nomina sotto infra.image l’immagine che un’esecuzione usa, tag incluso. Sui due target AWS anche la cifratura del database è della Release. La Recipe Terraform legge infra.overrides.kms_key_id e, quando è impostato, renderizza storage_encrypted = true accanto alla chiave; la Recipe CloudFormation legge infra.overrides.StorageEncrypted e KmsKeyId con i nomi propri delle proprietà della risorsa. Una Release che non imposta nessuno dei due renderizza un’istanza priva di qualsiasi attributo di cifratura, ed è ciò che fanno le Releases con la violazione piazzata.
I database Kubernetes e Compose eseguono l’immagine postgres:16, un tag fisso, quindi la regola li giudica e li lascia passare in ogni Release.
Associare la regola
.aggrega-config.yaml indica l’hub come proprio registry e nessuna directory del catalogo, e nessuna associazione di governance. La regola viene associata dal file che una 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: render-verdict with: sources: - policies/house-rule.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. Un elenco plugins.governance nel file del workspace sostituirebbe quello contenuto nel file nominato, ed è per questo che il file del workspace non ne dichiara alcuno. 0.9.0 è la versione dell’entità Plugin di ciascun motore nel catalogo della libreria standard. Entrambi i motori sono compilati nella CLI — aggrega plugin list elenca governance/rego e governance/cel tra i plugin integrati incorporati — quindi nessuna build qui scarica un plugin.
Che cosa legge una policy render-verdict
Una policy in render-verdict legge i file che la build scrive in input.artifacts, una voce per file, ordinate per percorso. Ciascuna porta:
path— il percorso del file sottodist/, ad esempioterraform/modules/db/main.tf;content— il testo del file, così come è scritto;format— il formato che il provider del target ha dichiarato per il file:yamlper il file Compose,jsonper il template CloudFormation,hclper ogni file Terraform, compreso il corpo del database scritto dalla sua Recipe. Dove nessuno ne ha dichiarato uno, è la stringa vuota, come per i file Kubernetes qui;documents— il contenuto del file analizzato in una struttura, come elenco di documenti: uno per ciascun file qui;parse_error— presente solo su un file che non è stato possibile analizzare, al posto didocuments.
Accanto ai file, input.sources contiene il file di policy proprio dell’associazione, e input.settings le sue impostazioni — qui l’oggetto vuoto, poiché questa associazione non ne dichiara alcuna.
aggrega build --release <release> --dry-run --policy-input <dir> scrive in <dir> il payload che ciascun ruolo riceve e non scrive nient’altro. In render-verdict quel file è ciò che il motore riceve anziché ciò che la policy legge: ogni file al suo interno porta il proprio path e content e il format dichiarato dal suo provider, e il motore analizza i documents dal contenuto una volta ricevuto il payload. Quindi il file elenca i file che verranno mostrati a una regola, ma non i loro documenti. Dopo che una build di release-terraform.yaml ha riempito il suo lockfile:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Un percorso che una regola legge all’interno di documents viene verificato in una build, dove il motore li ha analizzati. Nessun file scritto da queste Recipes fallisce l’analisi, quindi nessun file qui porta parse_error. Ogni clausola di questa regola legge documents, quindi un file non analizzato la supererebbe senza essere esaminato; una regola che non deve permetterlo aggiunge una clausola che rifiuta un file che porta parse_error.
Come ogni clausola legge la struttura del proprio target
Ogni clausola nomina la struttura che legge, e un file di un’altra struttura non porta ciò che la clausola nomina: in Rego il percorso è indefinito e la clausola non vale. Così una regola viene eseguita sull’output di ogni target e ogni clausola trova solo il proprio.
Compose scrive un file il cui documento indicizza ogni servizio per nome sotto services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Gli oggetti Kubernetes portano i propri container in un template del pod, che un CronJob contiene un livello più in profondità rispetto agli altri carichi di lavoro, sotto spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform in HCL nativo annida un blocco sotto il suo tipo e poi sotto ciascuna delle sue etichette, e l’ultima etichetta contiene un elenco di blocchi, perché i blocchi che condividono tipo ed etichette si raccolgono in un unico elenco. Così gli attributi di un’istanza si trovano un indice sotto il suo nome, e la clausola scorre l’elenco:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}L’elenco conta più qui che per una regola che cerca un valore, perché questa clausola rifiuta su un’assenza. Scritta per un singolo blocco — some name, block in doc.resource.aws_db_instance — block è l’elenco, block.storage_encrypted è indefinito su di esso, e not vale per qualsiasi cosa indefinita: la clausola rifiuta anche release-terraform.yaml, la cui istanza è cifrata, con lo stesso messaggio della Release con la violazione piazzata.
Un file .tf.json si legge così come la sua Recipe lo ha scritto, con il nome che contiene direttamente il blocco, quindi una regola scritta per una forma non legge l’altra. Ecco perché la clausola legge prima format: native_hcl accetta un file il cui formato è hcl, o il cui formato è vuoto e il cui nome termina in .tf — un file per cui nessun provider ha dichiarato un formato viene analizzato in base al nome, quindi anche la regola lo riconosce dal nome, anziché ignorarlo. Ogni file Terraform compilato qui è dichiarato hcl, quindi nessun file qui viene riconosciuto dal nome. Queste Recipes non scrivono alcun file .tf.json, quindi la regola non legge nessun’altra forma. Che cosa espone il payload di ciascun ruolo illustra entrambe le forme.
CloudFormation scrive un template le cui risorse sono indicizzate per ID logico sotto Resources, ciascuna con il proprio Type e le proprie Properties:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Un’istanza senza la proprietà StorageEncrypted, o con essa impostata su un valore diverso da true, viene rifiutata: not … == true vale in entrambi i casi.
Perché la regola CEL è scritta in modo diverso
policies/house-rule.cel esprime le stesse due clausole e raggiunge lo stesso verdetto su ogni build qui. È scritto in modo diverso in tre punti, ciascuno per una ragione legata al motore.
Verifica ogni chiave prima di leggerla. Leggere una chiave che un valore non porta è in CEL un’anomalia di valutazione anziché un percorso indefinito, e un’anomalia arresta la build. I file di ciascun target mancano di chiavi che quelli di un altro portano — un oggetto Kubernetes non ha services, un file Compose non ha kind — quindi ogni clausola verifica prima con has() le chiavi che legge:
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Senza la verifica has(d.services), aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull si arresta, qualunque siano le immagini eseguite dagli oggetti Kubernetes, esce con 1 e non scrive alcun dist/, e la riga che segnala l’anomalia nomina il file di policy e la chiave:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesSegnala un solo elemento in violazione per file. Una chiave di decisione raccoglie messaggi, e un’espressione CEL non ha alcun modo di unire in un unico elenco gli elenchi che costruisce per file. Così ogni clausola CEL segnala un elemento in violazione in ciascun file: il primo container di un template del pod oppure, tra i servizi, le istanze e le risorse che un file indicizza per nome, quello il cui nome viene per primo nell’ordinamento. Una comprensione scorre una mappa senza un ordine fisso, quindi scegliere per nome è ciò che mantiene il messaggio uguale da una build all’altra. La regola Rego segnala ogni elemento in violazione. Con due servizi non fissati in un file Compose, il motore Rego si arresta con due messaggi e il motore CEL con uno, per il servizio il cui nome viene per primo nell’ordinamento; con uno solo, come in ogni Release qui, i due si arrestano con lo stesso messaggio.
Si ripete. CEL non offre alcun modo di dare un nome a una sottoespressione, quindi un test usato due volte è scritto due volte, e il test sull’immagine è scritto per intero in ciascuna clausola anziché essere richiamato come lo è unpinned in Rego.
I due file sono un quasi-duplicato deliberato, ciascuno scritto a sé a partire dalla regola riportata sopra anziché generato l’uno dall’altro, così che una build su cui i motori non concordano mostri il disaccordo.
Un verdetto non cambia mai l’output
Una policy in render-verdict accetta la build o la rifiuta. Riceve i file che la build ha scritto e restituisce verdetti; nulla di ciò che restituisce viene applicato a essi. Così una Release di controllo produce gli stessi file, byte per byte, con la regola associata e senza, e check.sh confronta i due alberi a ogni esecuzione. Una build rifiutata non scrive alcun dist/. Per risolvere un rifiuto, si modifica la Release — un tag fissato, una chiave di cifratura — e la build successiva viene giudicata di nuovo.
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-render-verdictPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd policy-render-verdictBuild
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Sostituisci governance-rego.yaml con governance-cel.yaml per eseguire la stessa regola sul motore CEL, e terraform nel nome del file della Release con helm, compose o cloudformation, con le rispettive Releases con violazione piazzata release-helm-unpinned.yaml, release-compose-unpinned.yaml e release-cloudformation-unencrypted.yaml.
Il catalogo della libreria standard fornisce ogni Component, Recipe, Feature e FeatureRecipe usato qui e contiene 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 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.
La Release di controllo Terraform si completa. La Release con la violazione piazzata si arresta:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationOgni messaggio nomina il file che la regola ha giudicato, come suo percorso sotto dist/, e l’elemento in violazione al suo interno. Le altre Releases con violazione piazzata si arrestano allo stesso modo:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedOgni riga è quella che segue [POLICY_ERROR E0005] nell’output della sua build, mostrata dal margine sinistro. La prima proviene dal motore Rego e le altre due dal motore CEL, ciascuna con il nome del motore che l’ha segnalata; l’altro motore stampa lo stesso messaggio con il proprio nome.
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-render-verdict`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-render-verdict` e senza `dir`: scrive l’esempio in una nuova cartella `policy-render-verdict`. Poi chiama lo strumento `cli-build`, che esegue `aggrega build` e accetta il suo flag `--config`, una volta per ogni Release, in quest’ordine — `release-terraform.yaml` e `release-terraform-unencrypted.yaml` — ogni volta con `workspace_root` impostato a `policy-render-verdict`, `release` impostato a quel file, `auto_pull` impostato a true e `config` impostato a `governance-rego.yaml`. La seconda deve essere rifiutata, quindi leggimi il rifiuto. Dimmi quali file ha scritto la prima build; si trovano in `policy-render-verdict/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 la build di ciascuna Release di controllo una volta senza alcuna policy associata, come riferimento, e poi di tutte e otto le Releases con ciascun motore, tramite l’helper build-release. Una Release di controllo deve completarsi e scrivere gli stessi file, byte per byte, del suo riferimento; una Release con la violazione piazzata deve arrestarsi con E0005 e il messaggio atteso per essa, senza nessun altro rifiuto accanto, e non scrivere alcun dist/. Entrambi i motori sono tenuti allo stesso messaggio. Stampa una riga per build ed esce con 1 se un esito differisce, stampando l’output di quella build:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.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é sposta altrove l’albero di ciascuna build per confrontarlo, e non ne lascia nessuno dietro di sé; le build riempiono i lockfile di questa directory, come fa qualsiasi build. Il suo stato di uscita è l’intero verdetto.
Dove il compilatore non interpreta
Il compilatore renderizza i file di ciascun target, li passa al motore associato come testo con il formato che il loro provider ha dichiarato, e agisce in base alla severità che ciascun verdetto porta. Non sa che cos’è il tag di un’immagine, che latest si sposta, né che un’istanza RDS dovrebbe essere cifrata: quei significati sono della regola. Per i ruoli, i payload e le chiavi di decisione, vedi il socket di governance.
File
aggregate.yaml— il database e il job di report cablato a esso.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— legano ogni tipo di componente e la Feature di avvio manuale alle rispettive Recipes su un unico target.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— una Release di controllo e una violazione piazzata per target..aggrega-config.yaml— il registry predefinito; nessuna associazione di governance.governance-rego.yaml,governance-cel.yaml— la regola associata arender-verdicttramite ciascun motore, ognuno indicato con--config.policies/house-rule.rego,policies/house-rule.cel— la regola, una volta per motore.build-release.sh— esegue il build di una Release, mostrando il comandoaggrega buildequivalente.check.sh— esegue le venti build e verifica ciascun esito.