Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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 build

la tua policy

inserita nel compilatore

esito positivo

file scritti

pronti da revisionare e distribuire

esito negativo

compilazione interrotta

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

Una policy può interrompere una compilazione e indicare cosa correggere. Non modifica mai i tuoi file per farli passare.

Che cosa costruisce

istanzaComponent del catalogoche cosa è qui
dbcore/datastore/postgresil database degli ordini
reportcore/compute/taskun 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:

Manifestdbreport
manifest-helm.yamlhelm/postgres, uno StatefulSethelm/task, un CronJob mantenuto sospeso
manifest-compose.yamlcompose/postgres, un serviziocompose/task, un servizio dietro un profilo
manifest-terraform.yamlterraform/postgres-rds, un’istanza RDSterraform/task-ecs, una definizione di task Amazon ECS
manifest-cloudformation.yamlcloudformation/postgres-rds, un’istanza RDScloudformation/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

Releasedestinazioneche cosa trova la regolail build
release-helm.yamlKubernetesreport esegue registry.example.com/orders-report:1.4.2va a buon fine
release-helm-unpinned.yamlKubernetesreport esegue la stessa immagine con il tag latestsi arresta
release-compose.yamlDocker Composereport esegue registry.example.com/orders-report:1.4.2va a buon fine
release-compose-unpinned.yamlDocker Composereport esegue l’immagine senza tagsi arresta
release-terraform.yamlTerraforml’istanza è cifrata con la chiave che la Release nominava a buon fine
release-terraform-unencrypted.yamlTerraformla Release non nomina alcuna chiave, quindi l’istanza non è cifratasi arresta
release-cloudformation.yamlCloudFormationla Release attiva StorageEncryptedva a buon fine
release-cloudformation-unencrypted.yamlCloudFormationla Release lo lascia disattivatosi 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 sotto dist/, ad esempio terraform/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: yaml per il file Compose, json per il template CloudFormation, hcl per 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 di documents.

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:

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

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

Terminal window
aggrega scaffold --example policy-render-verdict

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd policy-render-verdict

Build

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Sostituisci 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 violation

Ogni 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 latest
policy 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 latest
policy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted

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

Terminal window
./check.sh

check.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 OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel 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 a render-verdict tramite 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 comando aggrega build equivalente.
  • check.sh — esegue le venti build e verifica ciascun esito.