Il socket di governance
L’intero socket anziché uno solo dei suoi ruoli: i quattro ruoli — due che giudicano una build, due che le danno forma — entrambi i motori di policy inclusi nel compilatore, e come un operatore associa un plugin.
Un operatore associa un plugin di governance Wasm per ispezionare una build e agire in base a ciò che trova. L’host del compilatore resta neutrale rispetto ai contenuti e privo di opinioni: instrada il payload della build al guest e agisce in base a ciò che il guest restituisce, e non interpreta mai la policy in sé. Tutta l’intelligenza di dominio delle policy — il linguaggio delle policy, il suo motore e le regole — risiede all’interno del guest.
Questo è lo stesso contratto di purezza ahead-of-time sotto cui opera ogni socket: il guest valuta il payload che riceve e restituisce un risultato che l’host consuma alla lettera (vedi il contratto della sandbox). L’host non apprende nulla del linguaggio di policy parlato dal guest e non porta alcun codice di motore di policy proprio.
Un plugin di governance viene associato a esattamente un ruolo, ed è il ruolo — non il plugin — a stabilire sia quale payload arriva sia che cosa l’associazione può farne. Due sono ruoli di verdetto: l’associazione giudica la build, e l’host intraprende esattamente una di tre azioni per ogni verdetto che essa restituisce. Due sono ruoli di trasformazione: l’associazione riporta una modifica alle etichette o alle annotazioni della build, e l’host la applica. Un plugin che serve più di un ruolo viene associato una volta per ruolo, e non dichiara alcun ruolo proprio — è l’associazione a portarlo.
Questa pagina è la trattazione completa del socket di governance: i quattro ruoli e il payload che ciascuno porta, le severità dei verdetti in base a cui l’host agisce, il canale di input agnostico rispetto al motore che un operatore fornisce, come scrivere una policy per uno dei due motori di policy inclusi nel compilatore — uno che valuta Rego, uno che valuta CEL — come un guest incapsula un motore di policy esterno, i guest di riferimento distribuiti, e come un operatore associa un plugin a un workspace. Per la collocazione del socket nella pipeline e le sue forme tipizzate dei dati trasmessi, vedi plugin-contract.md; per scrivere e pubblicare un plugin come entità del catalogo, vedi la Guida per sviluppatori di plugin Wasm.
Il modello mentale: l’host instrada, il guest decide
In una build l’host assembla il payload per il ruolo dell’associazione, lo passa attraverso il confine dell’ABI e rilegge ciò che il guest ha restituito. In un ruolo di verdetto si tratta di un elenco di verdetti, ciascuno con una severità e un messaggio leggibile da una persona: l’host fa corrispondere ogni severità a un’azione di build, e non legge il messaggio per ricavarne un significato, non sa che cosa abbia controllato la policy e non sa quale motore abbia prodotto la decisione. In un ruolo di trasformazione si tratta della modifica da apportare, indirizzata alle etichette o alle annotazioni che quel ruolo governa e a nient’altro.
Poiché l’host non interpreta il contenuto delle policy, l’intera superficie delle policy appartiene al guest: in quale linguaggio sono scritte le regole, quale motore le valuta e come una regola che scatta diventa un verdetto o una modifica. Il contratto del socket è ristretto per progettazione — un ruolo, un insieme di input e un risultato — così che qualsiasi tecnologia di policy che compila in Wasm possa servirlo.
Un ruolo di verdetto accetta o rifiuta e non fa nient’altro: l’host legge il suo output solo come una decisione e non lo applica mai come una modifica, quindi una policy non può rendere conforme in silenzio una build non conforme. Un ruolo di trasformazione è l’eccezione deliberata, e ciò che lo rende tale è che l’operatore lo ha associato — associare un plugin per modellare le etichette è una dichiarazione che le etichette vanno modellate. Ciò che un’associazione del genere può modificare è limitato alla superficie del proprio ruolo, e la build si arresta in modo esplicito su qualsiasi cosa al di fuori di essa.
I quattro ruoli
Un plugin è associato a esattamente un ruolo, e il ruolo stabilisce in quale punto della pipeline l’host lo valuta, quale payload riceve e che cosa può restituire. Un plugin che deve servire due ruoli viene associato due volte — una per ruolo.
I ruoli di verdetto: ir-verdict e render-verdict
ir-verdict— il guest ragiona sul grafo della rappresentazione intermedia, prima del rendering. Il payload porta il grafo IR completo, agnostico rispetto alle capacità (ogni nodo, arco e associazione che il compilatore detiene), più i percorsi di instradamento che l’analizzatore enumera, così una policy può ragionare su topologia e raggiungibilità senza ripercorrere il grafo. Quell’elenco di percorsi è limitato per nodo di partenza — una topologia densamente connessa o ciclica può contenere più percorsi distinti di quanti l’enumerazione ne emetta, e una volta raggiunto il limite i percorsi rimanenti da quel nodo di partenza non vengono elencati. Un percorso presente è quindi reale, mentre l’assenza di un percorso non prova che non ne esista nessuno: una policy il cui verdetto dipende dal fatto che qualcosa sia irraggiungibile dovrebbe stabilirlo dai nodi e dagli archi, che il payload porta per intero, anziché dal solo elenco dei percorsi. Una cosa nel grafo non è come è stata scritta: ogni valore che un autore ha dichiarato sensibile — neivalueso nell’infradi un’associazione, nell’infradi un’associazione a livello di confine, neivalueso nell’infrapropri di un nodo, oppure neivalueso nell’infrapropri di una connessione — arriva come il marcatore di trattenimento{"aggrega_withheld": "declared"}, mentre la sua chiave, la sua marcatura di sensibilità e ogni valore non dichiarato accanto a esso arrivano come sono stati scritti. Una policy giudica dove viaggia il materiale dichiarato sensibile e non riceve mai il materiale; vedi i fatti di associazione che una policy di governance legge. Una policyir-verdictviene eseguita al punto di controllo dell’analisi statica, prima che venga prodotto qualsiasi artefatto. Usalo per policy su architettura e cablaggio — invarianti di topologia, autenticazione tra confini diversi, forma del flusso delle credenziali — che dovrebbero arrestare una build prima che renderizzi qualsiasi cosa.render-verdict— il guest ragiona sull’output renderizzato, dopo il rendering. Il payload porta gli artefatti emessi ordinati per percorso, così i dati trasmessi sono identici byte per byte tra esecuzioni con input identico. Ogni artefatto porta il proprio percorso di output e il proprio testo renderizzato; porta inoltre il formato in cui è stato renderizzato, quando il provider che lo ha prodotto ne ha dichiarato uno, e una vista strutturata e analizzata del suo contenuto, quando il contenuto è in un formato che è stato analizzato prima della policy. Una policyrender-verdictvede esattamente ciò che la build ha prodotto, e nulla al suo interno viene trattenuto: un valore che una Recipe ha renderizzato in un artefatto arriva così come è stato renderizzato, perché l’artefatto è ciò che la policy giudica. Usalo per policy sull’output concreto — per esempio una regola che ispeziona servizi Docker Compose o oggetti Kubernetes renderizzati.
I ruoli di trasformazione: annotation-transform e label-transform
-
annotation-transform— il guest riporta le annotazioni da aggiungere, durante la risoluzione e prima dell’espansione delle annotazioni. Il payload porta ogni componente che l’associazione può annotare, ciascuno con le annotazioni che ha già, più le chiavi di annotazione per cui il Manifest registra un binding. Un’annotazione iniettata sotto una chiave registrata prosegue espandendosi in un’associazione di Feature, ed è così che questo ruolo aggiunge a una build una capacità che lo sviluppatore non ha scritto.I componenti che può annotare sono ogni componente che un confine nomina sotto
components:e ogni componente che la voce di instradamentoaggregates:di un confine instrada al suo interno. Una voce di instradamento colloca ogni componente del proprio modulo, compresi i componenti dei moduli annidati al suo interno, sia che il suocomponents:li nomini tutti, alcuni o nessuno, come fadocuments: {}, che non ne nomina nessuno; il payload li porta tutti. Un componente instradato è indirizzato dall’id che porta nel grafo di build — il nome del modulo, un punto e il nome del componente all’interno del modulo, come indocuments.backend, con un nome di modulo e un punto in più per ogni modulo annidato — che è il modo in cui il grafo di build e le sue diagnostiche lo scrivono, quindi anche una decisione lo nomina così. Un componente che la voce di instradamento colloca senza nominarlo non porta annotazioni proprie sul payload, e un’annotazione iniettata su di esso viene applicata come una scritta su di esso sotto la voce di instradamento. -
label-transform— il guest riporta le modifiche alle etichette da applicare, durante la costruzione della topologia: dopo che il grafo è stato costruito e prima che il grafo venga giudicato. Il payload porta una proiezione dei nodi della build — ciascuno con il Component che istanzia, la versione risolta per esso, le etichette che porta attualmente e i valori che la sua istanza dichiara, in sola lettura e con ogni valore che il suo Component dichiara sensibile trattenuto come lo trattiene il verdetto sul grafo — più il nome e l’ambiente della Release. Usalo per metadati derivati che uno sviluppatore non dovrebbe mai dover scrivere (ambito di conformità, proprietà, attribuzione dei costi) e per un’etichetta di capacità che la configurazione dichiarata di uno sviluppatore si guadagna.
I ruoli portano payload diversi perché agiscono in momenti diversi e rispondono a domande diverse. Tutti e quattro portano lo stesso canale di input fornito dall’operatore, descritto più sotto. Per vedere un payload anziché leggerne la descrizione, aggrega build --release <release> --policy-input <dir> scrive il payload che ciascun ruolo consegna a un plugin associato lì — compreso un ruolo a cui non è associato nulla — come un file JSON per ruolo, o per associazione dove le associazioni di un ruolo ricevono payload diversi, e combinato con --dry-run scrive quei file e nient’altro. In annotation-transform, label-transform e ir-verdict il file è il documento input che una policy legge. In render-verdict il motore di policy rimodella il payload prima che una policy lo legga — i documents di ciascun artefatto vengono analizzati a partire da esso — quindi una policy render-verdict su un motore interno al compilatore si testa in una build, associata a warn o info, come mostra Testare una policy prima che blocchi una build. Per un plugin il cui .wasm hai compilato tu stesso, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json lo esegue su quel file.
Verdetti e severità
Le severità qui sotto sono il vocabolario dei ruoli di verdetto. Un ruolo di trasformazione riporta una modifica anziché un verdetto, quindi non porta alcuna severità.
Un guest restituisce un elenco di verdetti. Ogni verdetto porta una severità che determina l’azione di build:
halt— ferma la build; l’host presenta il messaggio del verdetto come motivo. La build non produce artefatti.warn— segnala il verdetto; la build prosegue.info— registra il verdetto; l’esito della build resta invariato.
Queste tre sono l’intero insieme, e sono le stesse tre che usano le diagnostiche di ogni altro socket, quindi una severità significa la stessa cosa ovunque tu la legga.
Un verdetto che porta qualsiasi altro valore è una violazione del contratto anziché una quarta via. La build si arresta, e il messaggio nomina il plugin, il valore portato dal verdetto e i tre che il contratto dichiara — così una severità scritta male viene segnalata come errore di build invece di passare come un verdetto su cui nulla agisce. Un guest che riporta valori tra i tre non è interessato.
Una valutazione che consente non restituisce nulla. Un guest emette un verdetto solo quando una regola scatta, quindi un elenco di verdetti vuoto significa che la policy ha consentito la build. Non esiste alcun verdetto «pass» da emettere — il silenzio è il consenso.
Un guest può restituire molti verdetti in una sola valutazione, mescolando le severità. L’host li esamina tutti: qualsiasi halt ferma la build (e ogni messaggio halt viene presentato), mentre i verdetti warn e info vengono riportati senza bloccare. Questo rispecchia la distinzione tra arresto e avviso che separa una policy che arresta la build da un controllo di lint consultivo.
Il canale with: sorgenti e impostazioni
Un guest di policy è di solito generico rispetto alle regole specifiche che applica — il motore è incorporato nel guest, ma le regole sono fornite per associazione. Il canale with porta quell’input per associazione. Ha due campi agnostici rispetto al motore:
sources— i file di definizione delle policy che il guest carica. L’host legge ogni file nominato al momento della build e ne passa i byte al guest in modo opaco: non analizza mai una sorgente, e il percorso che consegna al guest è il nome base del file, mai un percorso assoluto dell’host. Che cosa significhino i byte è interamente affare del guest — un file.regoper un guest, un altro formato di policy per un altro, e un archivio codificato in base64 di un intero insieme di policy per un guest che ne legge uno.settings— una mappa di configurazione che il guest fa corrispondere al proprio motore. Un guest legge da questa mappa i propri parametri regolabili (un tetto di repliche, una chiave di etichetta obbligatoria). Per impostazione predefinita l’host la consegna alla lettera senza agire su di essa; un guest può inoltre dichiarare uno schema per essa (vedi sotto), nel qual caso l’host convalida la mappa rispetto a quello schema prima di eseguire il guest.
Un guest completamente precompilato — uno le cui regole sono compilate al suo interno anziché fornite al momento dell’associazione — omette del tutto with. Il canale è facoltativo in ogni ruolo.
Impostazioni tipizzate
Un guest può dichiarare un JSON Schema per le settings che si aspetta. Quando lo fa, l’host convalida le settings dell’associazione rispetto a quello schema prima di eseguire il guest. Impostazioni non conformi arrestano la build con un messaggio che nomina la chiave in errore e ciò che lo schema si aspettava — una chiave obbligatoria mancante, un valore del tipo sbagliato, una chiave sconosciuta o un valore fuori intervallo vengono intercettati in anticipo anziché emergere come un oscuro fallimento del guest o, peggio, come una build sbagliata ma riuscita.
Le impostazioni tipizzate sono facoltative e dichiarate dal guest, non dall’host. Un guest che non dichiara alcuno schema delle impostazioni mantiene il comportamento libero: l’host passa le sue settings senza controllarle. L’host esegue una normale validazione JSON Schema rispetto a qualunque schema il guest abbia dichiarato; non interpreta che cosa significhino le impostazioni. Questo mantiene il controllo neutrale rispetto al motore — ogni guest descrive la forma delle impostazioni che legge, e l’host impone esattamente quella forma e nient’altro.
Un’associazione che non dichiara impostazioni viene convalidata come JSON null. È ciò che consente a un guest di rendere obbligatorie le proprie impostazioni: uno schema che ammette solo un oggetto rifiuta un’associazione che non ne fornisce, e la build si arresta. La conseguenza vale anche nell’altro senso, ed è quella per cui scrivere deliberatamente: un guest le cui impostazioni sono davvero facoltative deve dichiarare uno schema che ammette null oltre a un oggetto, altrimenti non può affatto essere associato senza impostazioni. I due motori di policy inclusi nel compilatore dichiarano "type": ["object", "null"] proprio per questo motivo — associane uno senza alcun blocco with: e viene eseguito con i propri valori predefiniti. Un guest che dichiara soltanto "type": "object" ha reso obbligatorie le proprie impostazioni, che fosse o meno l’intenzione.
L’ABI è propria di Aggrega
Il contratto del socket è l’ABI propria di Aggrega, non quella di un motore di policy. È ciò che permette a qualsiasi tecnologia di policy compilata in Wasm di servire come guest intercambiabile: il guest presenta verso l’esterno la superficie di Aggrega — describe(), più l’export chiamato dal ruolo che serve — e qualunque motore usi è un dettaglio di implementazione dietro quella superficie.
Un guest che incapsula un motore di policy esterno assorbe l’ABI di quel motore al proprio interno. Se il motore ha una propria ABI Wasm, propri punti di ingresso o un proprio protocollo di callback verso l’host, il guest che lo incapsula lo istanzia e lo pilota internamente e fa corrispondere la decisione del motore alla forma di verdetto del socket. L’host del compilatore vede solo la superficie standard dei verdetti di governance; non apprende mai quale motore sia coinvolto e non porta alcun codice specifico di un motore. Spostare una policy da un motore a un altro è una modifica dell’associazione, non una modifica dell’host.
Due motori di policy sono inclusi nel compilatore
Due motori di policy sono compilati nel binario della CLI, e un operatore associa l’uno o l’altro — o entrambi — nello stesso modo in cui si associa qualsiasi plugin di governance:
| Coordinata | Linguaggio di policy | Sorgente associata |
|---|---|---|
governance/rego | Rego | File .rego, oppure un archivio codificato in base64 di un intero insieme di policy |
governance/cel | Common Expression Language (CEL) | File di espressioni .cel, oppure documenti di regole .yaml / .yml |
Tutto ciò che circonda il linguaggio è condiviso. Entrambi servono tutti e quattro i ruoli, entrambi leggono lo stesso payload per ruolo sotto gli stessi nomi di campo, entrambi fanno corrispondere le proprie decisioni alle stesse tre severità di verdetto tramite la stessa impostazione translation, ed entrambi falliscono in modo esplicito anziché consentire una build che non sono riusciti a valutare. Ciascuno porta come versione la release del compilatore che lo distribuisce, e nessuno dei due ha bisogno di una toolchain esterna né recupera alcunché al momento della build. Ciò che ciascun linguaggio può dire non è condiviso: una regola che in Rego si risolve in poche regole ausiliarie può richiedere impostazioni e ripetizioni in CEL — vedi Che cosa può dire un’espressione prima di scriverne una che percorre un instradamento.
Ciò che differisce è il linguaggio in cui sono scritte le regole, ed è l’intera base della scelta. Un parco IT che conserva già un corpus Rego — o un team che scrive Rego per l’admission control altrove — associa il motore Rego e le sue policy vengono eseguite così come sono. Un team che esprime le proprie regole come singole espressioni su un documento, come fa una validating admission policy di Kubernetes, associa il motore CEL. I due vengono associati per ruolo, quindi un workspace può eseguire Rego in un ruolo e CEL in un altro, oppure entrambi nello stesso ruolo come due associazioni.
L’host è agnostico rispetto a quale dei due abbia prodotto una decisione: instrada il payload, rilegge un verdetto o una modifica e agisce di conseguenza. Spostare una policy da un linguaggio all’altro è una modifica dell’associazione e una riscrittura delle regole — mai una modifica dell’host.
Policy Rego: due strade
Rego è un linguaggio di policy diffuso, e ci sono due strade per eseguirlo — un motore a basso attrito incluso nel compilatore e una via d’uscita a piena fedeltà.
Il motore Rego nel compilatore è la strada a basso attrito. Contiene un valutatore Rego nativo per Wasm, così un operatore inserisce un file .rego in sources e associa il plugin — nessuna toolchain esterna e nulla recuperato al momento della build. Serve tutti e quattro i ruoli: lo stesso plugin giudica il grafo di build, giudica l’output renderizzato, modella le etichette o inietta annotazioni, a seconda del ruolo a cui è associato. La sua identità di catalogo è il nome semplice rego sotto pluginType: governance — la coordinata governance/rego — e la sua versione è la release del compilatore che lo distribuisce. Scrivere una policy per questo motore è la sezione successiva.
Il valutatore reimplementa Rego in modo indipendente anziché incorporare l’implementazione di riferimento, e non implementa ogni funzione integrata di Rego. Quando una policy chiama una funzione integrata che il valutatore non implementa, l’associazione fallisce in modo esplicito: restituisce un’anomalia, non un consenso. La build si arresta quindi con un’anomalia che nomina il plugin — deliberatamente distinta da un verdetto halt, così che «il motore non riesce a valutare questa policy» non venga mai scambiato per «la policy consente la build». Una policy non valutabile ferma la build; non passa mai in silenzio.
La via d’uscita opa build -t wasm è la strada a piena fedeltà. Quando una policy ha bisogno dell’insieme completo delle funzioni integrate o della semantica esatta del motore di riferimento, compilala con la toolchain propria di OPA in un modulo Wasm ed esegui quel modulo dietro un sottile guest adattatore. L’adattatore assorbe interamente al proprio interno l’ABI Wasm di OPA (come descritto in L’ABI è propria di Aggrega più sopra): istanzia il modulo prodotto da OPA, imposta l’input, invoca la valutazione e fa corrispondere la decisione alla forma del verdetto. L’host vede solo la superficie standard dei verdetti di governance.
Un guest adattatore di riferimento è fornito come esempio completo. Incorpora una policy scritta in Rego e precompilata con opa build -t wasm in un modulo WebAssembly — un artefatto fissato e registrato nel repository, così la valutazione avviene interamente nel guest, senza alcun processo OPA e senza recuperare nulla. A ogni build l’adattatore istanzia al proprio interno quel modulo precompilato con un interprete Wasm incorporato, soddisfa gli import del modulo stesso (la sua memoria lineare e i suoi callback per le funzioni integrate), legge il payload come documento input di OPA e le settings dell’associazione come documento data di OPA, valuta ogni punto di ingresso compilato e fa corrispondere il nome deny / warn / audit di ciascun punto di ingresso a una severità di verdetto — rispettivamente halt, warn e info. Se una policy precompilata ha bisogno di una funzione integrata fornita dall’host che l’adattatore non implementa, l’adattatore fallisce in modo esplicito — rifiutando il modulo anziché restituire un consenso — così una policy non valutabile ferma la build invece di passare in silenzio. Rigenerare il modulo precompilato dalla sua sorgente Rego è un passaggio di authoring eseguito con la CLI di OPA, non una dipendenza al momento della build. ../examples/policy-data-class-route/ costruisce quell’adattatore attorno a un proprio modulo e fornisce i comandi che rigenerano entrambi.
Le due strade condividono lo stesso contratto con l’host, quindi spostare una policy dal motore nel compilatore al motore completo è una modifica dell’associazione.
Scrivere una policy per il motore Rego
Il motore valuta il Rego scritto dall’operatore interamente all’interno del guest, in qualunque dei quattro ruoli sia associato. Associarlo due volte, a due ruoli, con due file di policy diversi, è il modo in cui un solo motore copre due momenti della stessa build.
Il payload per il ruolo dell’associazione è il documento input della policy, e l’oggetto settings dell’associazione è il documento data della policy — così una policy legge una soglia fornita dall’operatore come data.max_replicas. Ogni file che l’associazione dichiara sotto sources diventa un modulo di policy, e ogni package che quei file dichiarano viene valutato.
In quale sintassi di regole è scritta una policy
Rego si scrive in due sintassi di regole e il motore le accetta entrambe, modulo per modulo. Un insieme di policy assemblato prima che esistesse la sintassi attuale viene quindi valutato accanto a uno scritto oggi, nella stessa associazione.
Nella sintassi attuale il corpo di una regola è introdotto da if, una regola che raccoglie valori in un insieme lo dichiara con contains, e il modulo indica in quale sintassi è scritto dichiarando import rego.v1 su una riga a sé sotto la dichiarazione del package:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Nella vecchia sintassi con la testa tra parentesi quadre il valore che una regola raccoglie si trova tra parentesi quadre nella testa della regola e il corpo la segue direttamente. Un modulo in quella sintassi non dichiara nulla, perché viene riconosciuto dal fatto che non si analizza come quella attuale:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Un modulo che si analizza come sintassi attuale senza dichiarare nulla viene rifiutato, per nome. La dichiarazione è ciò che fissa la lettura, e senza di essa lo stesso testo di regola può arrivare alla decisione opposta: il corpo di una regola che non è mai soddisfatto non contribuisce alcuna decisione nella sintassi attuale e ne contribuisce una nella sintassi più vecchia — così una policy che avrebbe dovuto restare silenziosa ferma la build, e il caso speculare lascia passare una build che una regola era stata scritta per fermare. Anziché scegliere una lettura per un modulo del genere, il motore lo rifiuta e dice che cosa aggiungere:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.Il rifiuto è un’anomalia di build che nomina il plugin anziché un verdetto, quindi ferma la build come fa una policy non valutabile e non si legge mai come una policy che l’ha consentita.
Due casi limite meritano di essere conosciuti prima che ti sorprendano. Un modulo senza alcun corpo di regola — uno che dichiara soltanto dati — si analizza come sintassi attuale, quindi anche a esso viene chiesta la dichiarazione, sebbene per esso le due letture non avrebbero potuto differire. E un modulo scritto nella sintassi più vecchia non viene mai rifiutato, perché non si analizza come quella attuale: è il motore stesso a distinguere le due, così una policy deliberatamente scritta con la testa tra parentesi quadre non viene mai scambiata per una nella sintassi attuale che ha dimenticato di dichiararlo.
Una policy raccoglie le proprie decisioni sotto una chiave di decisione
Ogni ruolo legge le decisioni di una policy da una chiave di decisione — una regola con un nome, in cui la policy raccoglie. Quali chiavi vengono lette, e che cosa significa una decisione sotto una di esse, è stabilito dal ruolo.
In un ruolo di verdetto una decisione è un messaggio, e la chiave sotto cui è stata raccolta stabilisce la severità con cui quel messaggio viene riportato. Per impostazione predefinita le chiavi sono i nomi di raccolta convenzionali di Rego:
| Raccolto sotto | Riportato come | Effetto sulla build |
|---|---|---|
deny | halt | ferma la build |
warn | warn | viene mostrato accanto a una build che si completa |
audit | info | registrato; l’esito della build resta invariato |
Tieni separati i due vocabolari, perché sono due: deny, warn e audit sono nomi nella tua policy, e halt, warn e info sono le severità con cui riporta il socket. La colonna di sinistra puoi rinominarla tu; la colonna di destra è l’insieme chiuso che ogni socket condivide.
Una policy che nomina diversamente le proprie decisioni dichiara la corrispondenza nelle impostazioni dell’associazione:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnUna corrispondenza dichiarata sostituisce quella predefinita anziché estenderla: le chiavi che nomina sono esattamente le chiavi lette, quindi una policy che raccoglie ancora in deny non arriva ad alcun verdetto una volta dichiarata la corrispondenza qui sopra. L’ordine in cui sono dichiarate le regole è l’ordine in cui vengono riportati i verdetti. Una chiave che la policy non dichiara è una decisione assente anziché un fallimento, quindi un solo file di policy può servire più associazioni.
Una severità al di fuori delle tre, e una corrispondenza dichiarata vuota, vengono rifiutate dallo schema delle impostazioni che il plugin dichiara — l’host convalida le impostazioni di un’associazione rispetto a esso prima dell’invio. La stessa chiave mappata due volte viene rifiutata quando la corrispondenza viene letta, cioè anch’essa prima che venga eseguita qualsiasi policy. In entrambi i casi la build si arresta prima che si arrivi a una decisione, mai con una corrispondenza applicata a metà.
Per il resto le impostazioni sono i dati propri della policy: la corrispondenza viene letta dall’oggetto e l’oggetto raggiunge invariato il documento data della policy, così una policy scritta per le chiavi predefinite vede esattamente il documento di dati che avrebbe visto senza alcuna corrispondenza configurata.
In un ruolo di trasformazione una decisione è la modifica da apportare anziché un messaggio, quindi non c’è alcuna severità da stabilire e a essere fissata è invece la chiave: labels nel ruolo che modella le etichette, annotations nel ruolo che inietta le annotazioni. Un’impostazione translation viene letta solo dove vengono riportati i verdetti, quindi un’associazione di trasformazione che ne dichiara una porta un’impostazione che il suo ruolo non consuma.
Una chiave di decisione viene letta da ogni package che l’associazione carica, così un insieme di policy può distribuire le proprie regole su più package e ciascuno contribuisce ciò che ha raccolto. L’altra faccia della medaglia merita di essere conosciuta prima che crei problemi: all’interno di un’associazione la chiave di decisione è un nome di regola riservato in ogni package, quindi un package ausiliario che per i propri scopi raccoglie in labels vede le proprie voci lette come decisioni sulle etichette. Questo fallisce in modo esplicito anziché in silenzio — l’associazione segnala che qualcosa raccolto sotto la chiave non è una decisione di quella forma — ma il modo più rapido di leggere un messaggio del genere è come una collisione di nomi, quindi riserva la chiave alla decisione e dai a una regola ausiliaria un nome diverso.
Che cosa espone il payload di ciascun ruolo
Il payload è il documento input della policy, quindi una policy lo legge sotto i nomi che gli assegna il formato di trasmissione.
Il grafo di build si trova in un percorso diverso nei due ruoli che ne portano uno. Un verdetto sul grafo riceve l’intero documento del grafo, quindi i suoi nodi si trovano in input.graph.spec.nodes; il ruolo che modella le etichette riceve una proiezione dei nodi, quindi i suoi nodi si trovano in input.graph.nodes. Una regola spostata tra quei due ruoli va quindi modificata, non copiata — e il sintomo di una dimenticanza è una regola che non scatta mai anziché un errore, perché un percorso che non esiste è semplicemente indefinito.
| Ruolo | Che cosa legge una policy |
|---|---|
ir-verdict | input.graph — l’intero documento del grafo di build: i nodi in input.graph.spec.nodes indicizzati per id di nodo, gli archi in input.graph.spec.edges. Un valore che un autore ha dichiarato sensibile si legge come {"aggrega_withheld": "declared"}. input.precalculated_paths — i percorsi di instradamento enumerati, ciascuno con il proprio elenco ordinato nodes e attached_features, i tipi di Feature associati in un punto qualsiasi del percorso (vedi sotto). L’elenco è sempre presente: una build senza alcun instradamento tra i componenti porta un elenco vuoto. |
render-verdict | input.artifacts — una voce per ogni file emesso, ciascuna con path, content, format e documents, i documenti analizzati del file. format è il formato che il provider che ha renderizzato il file ha dichiarato per esso — il provider Terraform dichiara hcl per ogni file .tf che emette e json per ogni file .tf.json, compresi i file di un modulo vendorizzato — e la stringa vuota dove nessun provider ne ha dichiarato uno, come per un file che una Recipe contribuisce all’output condiviso di un confine. Un file del genere viene comunque analizzato in base alla sua estensione, quindi i suoi documents ci sono in ogni caso. Un artefatto che non è stato possibile leggere in modo strutturato porta parse_error e nessun documento, così una policy può rifiutare in base al fallimento stesso anziché lasciar passare senza esame un file illeggibile. |
label-transform | input.graph.nodes — i nodi della build indicizzati per id di nodo, ciascuno con component, resolved_version, labels e values: i valori che l’istanza del nodo dichiara nell’Aggregate, con i suoi template valutati rispetto ai suoi parametri, assente quando non ne dichiara nessuno. Un valore che il Component del nodo dichiara sensibile si legge come {"aggrega_withheld": "declared"}, come in ir-verdict, e i valori non dichiarati accanto a esso si leggono come sono stati scritti. Una regola legge input.graph.nodes[id].values per decidere un’etichetta; non può modificare un valore. input.compilation_context — il release_name e l’environment della Release, così una policy può decidere diversamente per ambiente. |
annotation-transform | input.targets — ogni componente che l’associazione può annotare, ciascuno con boundary_path, component_name — per un componente che una voce di instradamento colloca, il suo id nel grafo di build, come metrics.query — e le annotations che la Release scrive sul componente stesso, ciascun valore così come è scritto: una stringa, un oggetto di sottochiavi o null dove il componente rinuncia a un’annotazione che erediterebbe. Ogni chiave che il componente porta è presente qualunque sia il suo valore, così una regola può lasciare stare una chiave che qualcuno ha già scritto. input.binding_keys — le chiavi di annotazione per cui il Manifest registra un binding. |
Una risorsa Terraform si legge in un percorso diverso in ciascuna delle due forme di Terraform. Nei documents di un file .tf nativo un blocco è annidato 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 un tipo e le etichette vengono raccolti in un unico elenco nell’ordine del sorgente. Un attributo di risorsa si legge quindi in input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — per un’istanza RDS con qualsiasi nome, input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Un file .tf.json viene letto così come la Recipe lo ha scritto, quindi la sua forma a oggetto convenzionale, in cui il nome contiene il blocco stesso, si legge in resource.<type>.<name>.<attr>, e una policy pensata per entrambe le forme legge entrambi i percorsi. Questo vale per entrambi i motori di policy inclusi nel compilatore. Una regola Rego scritta per l’altra forma trova indefinito il percorso che nomina: una regola che verifica un valore lì non scatta mai, e una che rifiuta su un valore assente, con not, scatta su ogni risorsa; un’espressione CEL che indicizza o seleziona nell’altra forma ferma la build con un’anomalia di valutazione che nomina il proprio file di policy. L’adattatore di rendering Rego di riferimento, descritto in Adattatori di policy per la fase di rendering più sotto, analizza da sé un file .tf nativo e legge un singolo blocco come un oggetto, quindi un percorso Terraform va modificato, non copiato, quando una policy si sposta tra quell’adattatore e un motore incluso nel compilatore.
Ogni ruolo porta inoltre input.sources — i file propri dell’associazione, ciascuno con il proprio nome base come path e il proprio content. Una policy viene eseguita solo come uno di quei file, quindi ovunque una regola legga l’elenco, esso contiene almeno quel file.
input.settings è l’oggetto delle impostazioni dell’associazione, lo stesso oggetto del documento data della policy, ed è presente quando l’associazione dichiara impostazioni. Quando l’associazione non ne dichiara, ciò che una regola trova dipende dal ruolo: in ir-verdict, label-transform e annotation-transform il campo è assente, quindi input.settings è indefinito come qualsiasi percorso che il payload non porta, e in render-verdict è l’oggetto vuoto. Quindi una regola che dipende dal fatto che un’impostazione sia stata configurata verifica l’impostazione che legge anziché l’oggetto, il che si comporta allo stesso modo in ogni ruolo — un max_nodes configurato viene letto, e uno non configurato lascia input.settings.max_nodes indefinito e la regola silenziosa:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}Il motore CEL tratta diversamente un oggetto delle impostazioni non dichiarato, e lo spiega nella propria sezione più sotto.
attached_features e binding_keys sono elenchi anziché oggetti, quindi una policy verifica l’appartenenza con in:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features è l’unione dei tipi di Feature di ogni associazione detenuta da qualsiasi nodo del percorso — compresa un’associazione scritta su una delle connessioni di quel nodo, qualunque sia la connessione su cui è stata scritta — quindi la regola è soddisfatta da un’associazione core/data-masking sul gateway stesso, che è dove quella Feature si associa: seleziona in base alla capacità di mascheramento dei contenuti che il gateway dichiara. Ciò che l’associazione maschera è il testo di chat e di completamento che passa attraverso quel gateway; la regola verifica che l’associazione esista, non che cosa elenca.
Poiché è un’unione sull’intero percorso, l’elenco dice che una Feature è associata da qualche parte su un instradamento e mai dove. Una regola che deve sapere se una Feature si trova tra due componenti particolari di un instradamento — quello che detiene dati riservati e quello che esso raggiunge — legge in ordine i nodes dell’instradamento e le associazioni proprie di ciascun nodo, in input.graph.spec.feature_values_mapping[<node>]; posta ad attached_features, la stessa domanda lascia passare un instradamento su cui la Feature si trova oltre il secondo componente. ../examples/policy-data-class-route/ è scritto in questo modo, per il motore Rego, il motore CEL e OPA.
Un oggetto nodo non porta un id proprio: l’id è la chiave sotto cui si trova in input.graph.spec.nodes, ed è per questo che la regola qui sopra porta nel suo messaggio gli id che ha letto da path.nodes anziché leggere un campo id.
L’ordine in cui una policy incontra le chiavi di una mappa
Il grafo mantiene l’ordine scritto dal suo autore: i nodi nell’ordine in cui i componenti sono stati dichiarati, e le etichette di ciascun nodo nell’ordine in cui il nodo le porta. Quell’ordine arriva intatto al guest — il payload porta entrambi come voci ordinate (vedi mappe che mantengono il loro ordine). Se una policy lo incontri o no dipende da come il motore che valuta la policy conserva un oggetto, non dal payload:
- Il motore Rego conserva le chiavi di un oggetto ordinate. Una regola che itera su
input.graph.spec.nodes, sullelabelsdi un nodo o su qualsiasi altro oggetto — compreso uno scritto nella policy stessa — incontra le chiavi ordinate: i componenti dichiaratiweb,api,metricsvengono incontrati comeapi,metrics,web. - Il motore CEL non fissa alcun ordine per una mappa. Una comprensione su
input.graph.spec.nodeso sullelabelsdi un nodo può incontrare le chiavi in un ordine diverso in due build con input identico, e due visite della stessa mappa all’interno di una sola espressione possono differire l’una dall’altra. Ecco perché i messaggi sotto una stessa chiave di decisione vengono ordinati: scrivi una regola la cui decisione non dipenda dalla posizione in cui si trova una chiave. - Un guest scritto con un kit per plugin incontra l’ordine dell’autore. Decodificati tramite il suo kit, i nodi e le etichette di ciascun nodo arrivano nel contenitore del kit che mantiene l’ordine, nell’ordine in cui il payload li porta, e lo scheletro di adattatore di governance che ogni kit fornisce passa al proprio motore un documento JSON scritto in quello stesso ordine. Un motore che converte quel documento in un tipo di valore proprio incontra invece l’ordine di quel tipo, come descrive mappe che mantengono il loro ordine.
Modellare le etichette: una policy nomina l’etichetta e il motore la indirizza
Nel ruolo che modella le etichette una policy raccoglie una decisione per etichetta sotto labels, nominando il nodo, la chiave dell’etichetta e il valore che l’etichetta assume:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Impostare una chiave già presente ne sostituisce il valore. Una decisione può invece chiedere che una chiave venga rimossa:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Una policy nomina l’etichetta invece di scrivere l’istruzione di modifica che la build applica, e il motivo merita di essere conosciuto: l’istruzione indirizza un’etichetta per percorso, e una chiave di etichetta Aggrega contiene abitualmente un /, che è il separatore di percorso — quindi un percorso scritto a mano indirizzerebbe una posizione annidata invece di una singola etichetta. Il motore indirizza l’etichetta che la decisione nomina, così l’escaping viene scritto una volta sola anziché in ogni policy, e una policy resta leggibile come un’affermazione sulle etichette anziché sui percorsi.
Una decisione può soltanto modificare un’etichetta. Ogni istruzione che il motore emette indirizza un’etichetta su un nodo, quindi una policy non ha modo di esprimere una modifica al Component di un nodo, alla sua versione risolta, all’insieme dei nodi o a un valore di etichetta che non sia una stringa. Una decisione che nomina un nodo che la build non ha, o che rimuove un’etichetta che il nodo non porta, viene rifiutata dalla build con un messaggio che nomina l’istruzione — mai ignorata in silenzio.
../examples/policy-label-transform/ associa una policy del genere accanto ai due plugin di tagging integrati, insieme a un verdetto sul grafo che legge le etichette che essi scrivono. Ciò che ciascuno di quei plugin legge e scrive si trova in I plugin di tagging integrati.
Iniettare annotazioni
Nel ruolo che inietta le annotazioni una policy raccoglie una decisione per annotazione sotto annotations, nominando la destinazione tramite la coordinata che la destinazione stessa porta, più la chiave e il suo valore:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}I nomi di campo che una decisione scrive sono i nomi di campo sotto cui ha letto le sue destinazioni, quindi la convenzione si può apprendere dal solo payload. Leggere input.binding_keys consente a una policy di iniettare solo chiavi per cui il Manifest ha registrato un significato — sono quelle che si espandono in un’associazione di Feature.
Il valore di una decisione è uno che potresti scrivere tu stesso su quell’annotazione: una stringa, o un oggetto di sottochiavi. Un binding che instrada una sola sottochiave accetta una stringa; un binding che ne instrada diverse accetta un oggetto che nomina ciascuna di esse, esattamente come un operatore lo scrive nella Release:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}La build legge un valore iniettato esattamente come legge lo stesso valore scritto nella Release, quindi si espande allo stesso modo e viene verificato allo stesso modo rispetto alla Feature collegata. Il motore conserva le chiavi di un oggetto ordinate, quindi le sottochiavi raggiungono la build in ordine. Un valore di qualsiasi altra forma — null, una lista, un numero, un booleano o un oggetto senza sottochiavi — viene rifiutato dalla build, che nomina l’iniezione: il ruolo aggiunge annotazioni, e null o un oggetto vuoto si legge come la rinuncia che un autore scrive per rimuoverne una. Una decisione che nomina un componente che il payload non porta viene rifiutata allo stesso modo, nominando la coordinata e l’annotazione.
Quando la build rifiuta un’annotazione iniettata per il modo in cui viene instradata o per ciò che porta — una stringa fornita a un binding che instrada diverse sottochiavi, un valore di sottochiave che lo schema della Feature collegata non ammette, o una sottochiave instradata attraverso il pilastro values, che un’annotazione lato Release non può usare — il rifiuto nomina il plugin che l’ha iniettata e il ruolo di governance a cui è associato, così il valore viene ricondotto alla policy che lo ha deciso anziché a una riga della Release che nessuno ha scritto.
../examples/policy-annotation-transform/ associa una policy del genere, che inietta una stringa sotto un binding e un oggetto di sottochiavi sotto un altro, e con la build produce gli stessi file di una Release che scrive quelle annotazioni a mano.
Associare un intero insieme di policy come un unico archivio
Un insieme di policy si associa file per file, oppure come un unico archivio che porta insieme i suoi file di policy e i suoi documenti di dati — la forma che costruisce una toolchain Rego. Il contenuto di un file associato viaggia verso il guest come testo, e un archivio compresso è fatto di byte arbitrari anziché di testo, quindi un archivio si associa codificato in base64, con un nome che termina in .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64Il nome è ciò che contrassegna un file come archivio anziché come testo di policy, il che fa della scelta una dichiarazione esplicita dell’operatore stesso: un archivio danneggiato viene allora segnalato come archivio danneggiato, nominando il file e il passaggio non riuscito, invece di essere letto come un file di policy che non si riesce ad analizzare. Codificare l’archivio è un passaggio che l’operatore aggiunge dopo che la propria toolchain lo ha costruito.
All’interno dell’archivio, ogni membro .rego è un modulo di policy e ogni membro data.json o data.yaml è un documento di dati annidato sotto la directory in cui si trova — un limits/data.json che contiene {"max": 3} viene letto da una policy come data.limits.max. I membri di qualsiasi altro tipo sono portati dall’archivio per la sua toolchain e non sono input di policy.
Un archivio che non può essere aperto è un errore che nomina il file associato: una codifica che non si decodifica, un flusso che non si decomprime, un archivio troncato, un file di dati che non si legge, o un archivio che non contiene alcuna policy. Nessuno di questi produce un insieme di policy vuoto, perché un insieme di policy vuoto non raggiunge alcuna decisione — e «l’archivio era illeggibile» non deve mai essere indistinguibile da «la policy ha consentito la build».
Scrivere una policy per il motore CEL
Il motore valuta il CEL scritto dall’operatore interamente all’interno del guest, in qualunque dei quattro ruoli a cui è associato. La sua identità nel catalogo è il nome semplice cel sotto pluginType: governance — la coordinata governance/cel — e la sua versione è la release del compilatore che lo distribuisce. Associarlo due volte, in due ruoli, con due file di policy diversi, è il modo in cui un solo motore copre due momenti della stessa build.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Una policy accede all’intero payload tramite un solo nome, input, quindi i nomi che legge sono quelli che dà loro il formato di trasmissione: il grafo di build in input.graph, i percorsi di instradamento enumerati in input.precalculated_paths, i file renderizzati in input.artifacts, le destinazioni delle annotazioni in input.targets. Quei percorsi per ruolo sono quelli riportati nella tabella di Che cosa espone il payload di ciascun ruolo più sopra, e sono identici per entrambi i motori — un solo formato di trasmissione, letto sotto un solo nome radice.
I file propri dell’associazione si trovano in input.sources e le sue impostazioni in input.settings, quindi una soglia fornita dall’operatore si legge come input.settings.max_nodes. Non c’è un secondo documento da imparare: le impostazioni fanno parte di input come tutto il resto. Entrambi sono sempre presenti come valore — le impostazioni sono l’oggetto vuoto in ogni ruolo quando l’associazione non ne dichiara — quindi un’espressione che vi accede non deve proteggersi dalla loro assenza, e se una certa impostazione sia stata configurata è un test sulla sua chiave: has(input.settings.max_nodes).
Le due forme scritte dall’autore, e il nome del file che sceglie tra esse
Una policy si associa in una di due forme, e è il nome del file a dire quale:
| Il nome del file termina in | Letto come |
|---|---|
.cel | un’espressione, valutata così com’è |
.yaml o .yml | un documento di regole — un elenco di regole |
| qualsiasi altra cosa | un’espressione |
Il nome è l’intera regola. Nessuna impostazione seleziona una forma, e il testo del file non viene esaminato per indovinarne una — non potrebbe comunque rispondere alla domanda, perché il valore più esterno di un’espressione è una mappa e lo è anche quello di un documento di regole, il che rende le due forme indistinguibili per struttura.
Quindi la regola vale in entrambi i sensi, ed entrambi gli errori vengono rifiutati anziché letti male. Un documento di regole chiamato policy.cel viene rifiutato, perché un elenco di regole YAML non è un’espressione; un’espressione chiamata policy.yaml viene rifiutata, perché un’espressione non è un elenco di regole. Ogni rifiuto nomina il file. Rinominare il file è la correzione in entrambe le direzioni.
Un insieme di policy è composto da tutti i file di cui ha bisogno, e le due forme si mescolano liberamente all’interno di una stessa associazione.
Un’espressione, in un file chiamato .cel
Un linguaggio di espressioni non ha nomi di regole sotto cui raccogliere le decisioni, quindi le decisioni sono il valore che l’espressione produce: una mappa dalla chiave di decisione a ciò che quella chiave raccoglie. In un ruolo di verdetto una chiave raccoglie i messaggi raggiunti sotto di essa; in un ruolo che modella la build raccoglie le decisioni da applicare.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Una chiave che il file omette non ha raggiunto alcuna decisione lì, quindi un file non deve nominare ogni chiave — e ogni ruolo legge solo la chiave che lo riguarda, così un insieme di policy può servire un ruolo di verdetto e un ruolo che modella la build dagli stessi file. Una chiave porta un elenco di ciò che raccoglie, un singolo elemento, o il valore null per nessuno.
Un’espressione che si valuta in qualcosa di diverso da una mappa viene rifiutata, con un messaggio che nomina la forma da scrivere. Un semplice size(input.graph.spec.nodes) <= 5 è l’errore da aspettarsi: è un booleano, e leggere false come un arresto significherebbe inventare un messaggio che l’autore non ha mai scritto.
Un documento di regole, in un file chiamato .yaml o .yml
Un documento di regole è un elenco di regole, ciascuna delle quali nomina la chiave di decisione che raggiunge, l’espressione che decide se viene raggiunta e ciò che viene riportato quando lo è:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentCiò che una regola riporta segue la chiave di decisione che raggiunge, esattamente come in un’espressione. Il testo è il messaggio che un verdetto porta. Una mappatura sono i campi dell’unica decisione che legge un ruolo che modella la build:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldQuale dei due una regola scriva è deciso dalla sola regola — non esiste un’impostazione che lo selezioni — e una regola che scrive quello sbagliato per la propria chiave viene rifiutata, per nome.
Un dettaglio YAML che vale la pena conoscere prima che crei problemi: un’espressione che inizia con un doppio apice deve essere racchiusa tra virgolette per il lettore del documento, perché un valore che inizia con " viene letto come uno scalare tra virgolette anziché come testo che inizia con un apice.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyUn documento di regole viene letto come l’espressione che rappresenta prima che venga valutato alcunché. Ogni regola diventa la propria chiave di decisione, che porta il resoconto della regola quando l’espressione è vera e nulla quando non lo è, e le regole che condividono una chiave vengono unite. Così un solo valutatore esegue entrambe le forme, e un documento di regole decide esattamente ciò che decide l’espressione che rappresenta — in ogni ruolo, verdetti e decisioni che modellano la build allo stesso modo. Ne seguono due conseguenze. Un documento e l’espressione scritta a mano che esso rappresenta raggiungono le stesse decisioni, perché sono la stessa valutazione. E le regole di ordinamento descritte più sotto sono quelle della forma valutata anziché del documento — le regole di un documento non vengono riportate nell’ordine in cui sono state scritte.
Quale forma scegliere — non sono intercambiabili
Entrambe le forme passano per un solo valutatore, quindi nessuna delle due è più veloce o più affidabile dell’altra. Ciò che differisce è ciò che ciascuna può dire, e poiché due forme sono due cose da imparare, la distinzione merita di essere enunciata chiaramente anziché lasciata al gusto personale. Scegli in base a ciò che la regola riporta.
- Un documento di regole, quando il resoconto è fisso. Il messaggio o la decisione viene scritto una volta, accanto all’espressione che lo raggiunge, e il file si legge come un elenco di condizioni di guardia. È la forma più breve per «se questo è vero, di’ esattamente questo».
- Un’espressione, quando il resoconto nomina ciò che ha trovato. Una sola espressione filtra i componenti di una build e produce un messaggio — o una decisione — per componente, così chi legge ottiene
component payments tracks the latest version; pin itper ciascun elemento in violazione anziché una frase su un conteggio.
Quel secondo compito è quello che un documento di regole non può svolgere: ciascuna delle sue regole porta un solo resoconto, scritto in anticipo, quindi non ha nulla da dire su quale componente l’abbia fatta scattare. Ricorrere alla forma a documento e poi volere il nome dell’elemento in violazione nel messaggio è la strada che finisce con il riscrivere la regola come un’espressione, quindi conviene scegliere in base a quella domanda fin dall’inizio.
Che cosa può dire un’espressione
Le espressioni che questo motore valuta usano le comprensioni filter, map ed exists, + sulle stringhe e sulle liste, size, in, startsWith, string(), l’operatore condizionale e una lista indicizzata da un intero calcolato. Non offrono le funzioni di estensione che alcuni ambienti CEL aggiungono: join, split, substring, indexOf, flatten, cel.bind e lists.range vengono rifiutate, ciascuna, come riferimento non dichiarato, e una comprensione accetta una sola variabile, quindi una forma a due variabili come exists(i, v, …) viene rifiutata allo stesso modo. Un rifiuto è un’anomalia di build che nomina il file e il riferimento:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Tre conseguenze danno forma a una regola che percorre un instradamento:
- Non c’è modo di dare un nome a un valore intermedio. Una sottoespressione usata due volte si scrive due volte, oppure si lega mappando una lista di un solo elemento:
[value].map(name, …)[0]valuta il proprio corpo una volta connamelegato avalue. - Non c’è modo di percorrere le posizioni di una lista. Una regola che confronta per posizione i componenti di un instradamento prende le posizioni dalle proprie impostazioni — una lista
positionscome[0, 1, 2, …]— e indicizza l’instradamento in ciascuna di esse, quindi deve proteggersi da un instradamento più lungo della lista stessa, fermando la build su un instradamento del genere, anziché leggerlo solo in parte. - Una chiave di decisione raccoglie messaggi, non liste di messaggi. Un’espressione che produce una lista di messaggi per ogni instradamento viene rifiutata sotto una chiave di decisione — l’anomalia dice che ha raccolto un valore di tipo lista anziché un messaggio — quindi una regola produce un record per instradamento e costruisce il messaggio a partire da esso. E un messaggio che l’espressione produce due volte viene riportato due volte: l’ordinamento descritto più sotto ordina ciò che una chiave ha raccolto, e non rimuove una ripetizione.
../examples/policy-data-class-route/ contiene una regola CEL scritta tenendo conto di tutte e tre, accanto alla stessa regola per il motore Rego.
Chiavi di decisione e severità
Le chiavi di decisione, la corrispondenza predefinita con le severità e l’impostazione translation che le rinomina sono le stesse del motore Rego — vedi Una policy raccoglie le proprie decisioni sotto una chiave di decisione più sopra. Per impostazione predefinita deny viene riportato come halt, warn come warn e audit come info; una translation dichiarata sostituisce quella corrispondenza predefinita anziché estenderla, e l’ordine che dichiara è l’ordine in cui vengono riportati i verdetti.
Entrambi i motori dichiarano lo stesso schema delle impostazioni per questa impostazione, quindi un blocco translation significa la stessa cosa qualunque sia il linguaggio che esprime le decisioni, e uno malformato viene rifiutato prima che venga eseguita qualsiasi policy.
In un ruolo che modella la build la chiave è fissa anziché mappata: labels nel ruolo che modella le etichette, annotations nel ruolo che inietta le annotazioni.
Ordinamento: ordinati all’interno di una chiave, e un ordine totale sulle decisioni
I messaggi sotto una stessa chiave di decisione vengono riportati ordinati. Questo fa parte del contratto anziché essere una scelta di presentazione, e vale la pena tenerne presente il motivo: una comprensione su una mappa — .filter(...) e .map(...) su input.graph.spec.nodes, che è il modo più naturale di scrivere una regola per componente — percorre quella mappa in un ordine che il valutatore non fissa. Senza intervento, un input identico riporterebbe gli stessi messaggi in una sequenza diversa a ogni build. L’ordinamento lo elimina.
Ne seguono due cose che è facile leggere come bug e che non lo sono:
- Anche le regole di un documento di regole vengono riportate ordinate, non nell’ordine in cui sono state scritte — perché il documento viene valutato come l’espressione che rappresenta, e l’ordinamento si applica a ciò che una chiave ha raccolto.
- Anche una lista scritta a mano viene ordinata. Una chiave che porta
["second", "first"]riportafirstprima disecond. Nulla in un risultato valutato distingue una lista che l’autore ha digitato da una prodotta da una comprensione, quindi non esiste un ordine dell’autore da preservare.
Tra chiavi diverse l’ordine è quello dichiarato da translation. Tra file diversi è l’ordine dei nomi dei file, perché i sorgenti di un’associazione arrivano ordinati per nome anziché nell’ordine in cui l’associazione li elenca.
In un ruolo che modella la build lo stesso ragionamento si applica alle decisioni stesse, e l’ordine è più forte: le decisioni vengono riportate in ordine crescente di tutto ciò che nominano, che è un ordine totale su ciò che una decisione può esprimere — il nodo, poi la chiave dell’etichetta, poi se l’etichetta viene aggiunta o rimossa, poi il valore; e per un’iniezione, il confine, poi il componente, poi la chiave dell’annotazione, poi il suo valore. Una modifica a etichette o annotazioni raggiunge l’output renderizzato, quindi un ordine arbitrario significherebbe che un input identico viene renderizzato in modo diverso da una build all’altra.
Modellare le etichette
Nel ruolo che modella le etichette una policy raccoglie una decisione per etichetta sotto labels, nominando il nodo, la chiave dell’etichetta e il valore che l’etichetta assume:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Impostare una chiave già presente ne sostituisce il valore. Una decisione può invece chiedere che una chiave venga rimossa, indicando op come remove:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Una sola decisione non ha bisogno di una lista attorno, e un file che non nomina alcuna chiave labels non decide alcuna etichetta.
Una policy nomina l’etichetta invece di scrivere l’istruzione di modifica che la build applica, per il motivo spiegato nella sezione sulla modellazione delle etichette del motore Rego: una chiave di etichetta Aggrega contiene abitualmente un /, e un percorso scritto a mano indirizzerebbe una posizione annidata invece di una singola etichetta. Il motore indirizza l’etichetta che la decisione nomina.
Leggere un’etichetta che un nodo potrebbe non portare è un fallimento anziché un valore vuoto, ed è per questo che il secondo esempio verifica se la chiave è presente prima di leggerla. È la regola propria del linguaggio di espressioni sulla lettura di una chiave assente, e si manifesta in modo esplicito: una policy che cerca un’etichetta che nessun nodo porta segnala che non è stato possibile valutarla anziché non decidere nulla in silenzio.
Una decisione può soltanto modificare un’etichetta. Una decisione che nomina un nodo che la build non ha, o che rimuove un’etichetta che il nodo non porta, viene rifiutata dalla build con un messaggio che nomina l’istruzione — mai ignorata in silenzio.
Raggiungi una sola decisione per nodo e chiave di etichetta. Una regola che può produrre due valori diversi per la stessa etichetta sullo stesso nodo è sottospecificata: risolvi il valore all’interno dell’espressione — con un condizionale, o con un filtro che ammette un solo ramo — anziché emettere entrambe le decisioni.
../examples/policy-label-transform/ mostra dall’inizio alla fine il ruolo che modella le etichette, con la sua policy scritta per il motore Rego.
Iniettare annotazioni sotto una chiave registrata
Nel ruolo che inietta le annotazioni una policy raccoglie una decisione per annotazione sotto annotations, nominando la destinazione tramite la coordinata che la destinazione stessa porta, più la chiave e il suo valore:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}I nomi di campo che una decisione scrive sono i nomi di campo sotto cui ha letto le sue destinazioni, quindi la convenzione si può apprendere dal solo payload. Leggere input.binding_keys consente a una policy di iniettare solo chiavi per cui il Manifest ha registrato un significato — sono quelle che si espandono in un’associazione di Feature. Ogni campo è obbligatorio: un’annotazione con una chiave vuota o un nome di componente vuoto non è qualcosa che una policy intendesse chiedere. Il confine sotto cui si trova un componente può legittimamente essere nominato dalla stringa vuota, quindi quel campo deve essere presente ma può essere vuoto.
Il valore è uno che potresti scrivere tu stesso su quell’annotazione: una stringa, o una mappa di sottochiavi, che è ciò che alimenta un binding che instrada diverse sottochiavi contemporaneamente — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Il motore scrive le sottochiavi di una mappa in ordine, poiché il linguaggio di espressioni non fissa alcun ordine per una mappa, e trasmette il valore così come l’espressione lo ha prodotto; un valore che il modello JSON non può contenere — byte, un timestamp, una durata — viene rifiutato anziché trasformato in testo. La build legge poi il valore esattamente come legge lo stesso valore scritto nella Release, e rifiuta null, una lista, un numero, un booleano o una mappa vuota, nominando l’iniezione. Due decisioni per uno stesso componente e una stessa chiave con valori diversi vengono ordinate in base al JSON del valore. Le annotations di una destinazione portano ciascun valore esistente così come è scritto — una stringa, una mappa o null per una rinuncia — quindi verificare "feature.aggrega.ai/monitoring" in t.annotations trova una chiave qualunque sia il suo valore.
Una decisione che nomina un componente che il payload non porta viene rifiutata dalla build, nominando la coordinata e l’annotazione. Quando la build rifiuta un’annotazione iniettata per il suo instradamento, per i valori delle sue sottochiavi o per il suo pilastro, il rifiuto nomina il plugin che l’ha iniettata e il ruolo a cui è associato. Come per le etichette, raggiungi una sola decisione per componente e chiave di annotazione, risolvendo il valore all’interno dell’espressione anziché emettere due decisioni per una stessa chiave.
../examples/policy-annotation-transform/ mostra dall’inizio alla fine il ruolo che inietta le annotazioni, con la sua policy scritta per entrambi i motori.
Quando una policy o una decisione non può essere letta
Una policy che il motore non riesce a leggere, non riesce a valutare, o che produce qualcosa di diverso da decisioni nella forma documentata fa fallire la build anziché restituire un verdetto o una modifica. Il fallimento viene segnalato come un’anomalia di build che nomina il file e, dove l’anomalia appartiene a una parte del file, la posizione al suo interno — deliberatamente distinta da un verdetto halt, così che «non è stato possibile valutare questa policy» non venga mai scambiato per «questa policy consente la build».
Per un’espressione, ciò copre un sorgente che non si analizza — segnalato con la riga e la colonna proprie del parser e un caret sotto la posizione che causa l’errore — e un sorgente che si valuta in qualcosa di diverso da una mappa dalla chiave di decisione a ciò che quella chiave raccoglie.
Per un documento di regole, copre un testo che non è un elenco di regole, un elenco senza regole, una regola a cui manca un campo o che ne porta uno vuoto, un campo che la forma non definisce, un resoconto che non è né testo né una mappatura da testo a testo, e un’espressione che non può essere letta. Un’anomalia che appartiene a una regola nomina la posizione di quella regola — contata a partire da uno, come un autore conta il proprio file — e la sua chiave di decisione. Una regola la cui espressione non si analizza viene rifiutata prima della valutazione, così il caret cade all’interno dell’espressione che l’autore ha scritto anziché in una posizione di un testo tradotto che non ha mai visto.
Per una decisione in un ruolo che modella la build, copre un messaggio dove spetta una decisione, una coordinata mancante e un campo che la forma di decisione di questo motore non definisce. Quest’ultimo caso merita di essere evidenziato a parte: un annotation_valu scritto male viene rifiutato, non ignorato, così l’errore viene segnalato anziché iniettare silenziosamente un valore vuoto e lasciare una build che si completa senza la modifica. Ogni rifiuto di questo tipo nomina il file e termina nominando ciò che una decisione di quel tipo deve nominare.
Adattatori di policy per la fase di rendering
Un adattatore per la fase di rendering ragiona sull’output renderizzato della build anziché sul suo grafo IR. Il payload di rendering porta gli artefatti emessi — ciascuno con il proprio percorso di output e il proprio contenuto renderizzato e, dove si applicano, il formato in cui è stato renderizzato e una sua vista strutturata e analizzata — più i sorgenti e le impostazioni propri dell’associazione, ciascuno dove l’associazione lo dichiara. Un adattatore legge quel contenuto per la forma di output a cui è destinato, valuta una policy sul risultato strutturato e fa corrispondere l’esito a verdetti halt / warn / info. Poiché il payload non nomina alcuna forma di output propria, un solo schema di adattatore serve qualsiasi destinazione di rendering; una nuova forma di output è un nuovo adattatore, non una modifica dell’host.
Ogni adattatore per la fase di rendering è un adattatore nel senso visto sopra: verso l’esterno parla l’ABI di Aggrega e al proprio interno assorbe un formato specifico della destinazione o il contratto di un motore di policy esterno, così il compilatore resta libero da qualsiasi logica di formato di output o di policy. I motori Rego e CEL nel compilatore servono direttamente il ruolo render-verdict; oltre a essi, due adattatori di riferimento per la fase di rendering sono forniti come esempi completi tra gli esempi Rust del kit di sviluppo per plugin, uno per ciascuna forma di output comune.
../examples/policy-render-verdict/ associa una regola a render-verdict sull’output di quattro destinazioni — oggetti Kubernetes, un file Docker Compose, una configurazione radice Terraform e un template CloudFormation — scritta una volta per ciascun motore nel compilatore, e verifica che la violazione inserita apposta in ciascuna destinazione provochi un arresto e che il suo caso di controllo passi.
Per scrivere un adattatore tuo, in questo ruolo o in qualsiasi altro, parti dallo scheletro di adattatore di governance che ogni kit di sviluppo per plugin fornisce: Scrivere un proprio plugin di governance lo percorre dallo scheletro fino a una build che esso rifiuta.
Output YAML, JSON e Terraform HCL — l’adattatore di rendering Rego di riferimento
L’adattatore di rendering Rego di riferimento esegue Rego fornito dall’operatore su qualsiasi output di rendering YAML o JSON, e sull’output HCL nativo di Terraform. È un esempio completo della forma per la fase di rendering: lo stesso valutatore Rego nativo per Wasm del motore nel compilatore, e la stessa convenzione di raccolta deny / warn / audit fatta corrispondere alle stesse tre severità di verdetto, ragionando sui file renderizzati anziché sul grafo di build.
È indipendente dalla forma dell’output tra le destinazioni YAML/JSON. L’adattatore analizza il contenuto di ogni artefatto come uno o più documenti YAML o JSON — YAML è un sovrainsieme di JSON, quindi un template JSON come uno stack CloudFormation viene analizzato tramite lo stesso parser — ed espone alla policy i documenti analizzati insieme al contenuto grezzo. Una policy ragiona sull’output di rendering strutturato di qualsiasi destinazione del genere con Rego ordinario: input.artifacts[_].documents[_] restituisce i documenti analizzati (i services di un file Docker Compose, le Resources di un template CloudFormation), input.artifacts[_].content restituisce il testo grezzo, e l’oggetto settings dell’associazione è il documento data di Rego. Una policy che richiede un registry approvato sull’output Docker Compose, ad esempio, nega qualsiasi servizio la cui immagine non porta alcun prefisso di registry.
L’adattatore ragiona anche sull’output di rendering HCL nativo di Terraform. Un file .tf nativo non è né YAML né JSON, quindi l’adattatore lo proietta nello stesso oggetto canonico in cui già si analizza un file Terraform-JSON (.tf.json): una policy legge un attributo di risorsa in input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — per un’istanza RDS, input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — allo stesso modo qualunque sia la forma Terraform emessa dal compilatore. I tipi degli attributi vengono preservati (un numero resta un numero, un booleano un booleano), e un’espressione Terraform non risolta resta una stringa nella sua forma ${ ... }. I corpi Terraform-JSON (.tf.json, .auto.tfvars.json) vengono analizzati tramite il percorso YAML/JSON senza modifiche, e un file template Terraform (.tftpl) — testo di template anziché configurazione autonoma — non viene proiettato e fa emergere parse_error come qualsiasi contenuto non strutturato.
Quell’elenco dice che cosa accetta il parser dell’adattatore, non che cosa emette il compilatore. I due non sono lo stesso insieme, e un file di variabili caricato automaticamente è il caso in cui differiscono: il compilatore non emette un overlay del genere su alcun percorso — gli input di un modulo referenziato sono gli argomenti del blocco module di quel componente nella configurazione radice del confine — quindi quella forma raggiunge la vista di una policy solo quando un modulo vendorizzato ne include uno proprio, che il percorso dei moduli referenziati copia nell’output così com’è. Una policy scritta aspettandosi che il compilatore ne produca uno non scatterà mai.
Quando il contenuto di un artefatto non si analizza, l’adattatore non lo lascia passare in silenzio: conserva il contenuto grezzo, non espone alcun documento analizzato per quell’artefatto e registra il messaggio del parser sotto input.artifacts[_].parse_error, così una policy può fermare esplicitamente la build su un artefatto malformato. Come per il motore Rego nel compilatore, una policy che chiama una funzione integrata che il valutatore incorporato non implementa fallisce in modo esplicito — un’anomalia che nomina il plugin, mai un consenso silenzioso.
Output Kubernetes — l’adattatore di rendering Kubewarden
L’adattatore di rendering Kubewarden esegue policy di ammissione in stile Kubewarden sui manifest Kubernetes renderizzati. Assorbe al proprio interno il contratto di admission review di Kubernetes: una policy Kubewarden riceve una richiesta che avvolge un singolo oggetto e restituisce una risposta di accettazione o di rifiuto. Nella fase di rendering l’output della build è già un insieme di risorse Kubernetes, il che rende quella fase il luogo naturale in cui eseguire una policy a forma di ammissione. Per ogni oggetto renderizzato l’adattatore ricava i campi di ammissione dall’oggetto analizzato stesso, avvolge l’oggetto in una richiesta a forma di admission review all’interno del guest, esegue la policy e fa corrispondere la risposta a un verdetto: un rifiuto diventa un verdetto; un’accettazione non emette nulla. La policy di riferimento inclusa è una regola che richiede un’etichetta — ogni oggetto deve portare una chiave di etichetta nominata da settings — un modello comune di Kubewarden.
Ambito comune agli adattatori per la fase di rendering
- Fase di rendering, una forma di output per adattatore. Un adattatore per la fase di rendering ragiona sugli artefatti renderizzati, non sul grafo IR, e si rivolge alla forma di output che analizza — YAML/JSON e HCL nativo di Terraform per l’adattatore di rendering Rego di riferimento, oggetti Kubernetes per l’adattatore Kubewarden. Una policy per la fase del grafo, o una policy su una forma di output che nessun adattatore fornito analizza, è un guest diverso.
- Solo validazione. Un adattatore per la fase di rendering accetta o rifiuta; non restituisce mai un oggetto modificato. L’oggetto modificato di una policy di mutazione viene ignorato — il compilatore non riscrive mai l’output renderizzato a partire da un verdetto di policy. Una policy decide; non modifica.
Associare una policy
Un operatore associa un plugin di governance tramite l’elenco plugins.governance nella configurazione del workspace (.aggrega-config.yaml). Ogni voce nomina un plugin, il role a cui è associato e, facoltativamente, il canale with che fornisce le sue regole e i suoi parametri regolabili:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3L’uri si risolve nel plugin. L’host legge ogni file di sources al momento della build e ne passa i byte al guest, e trasmette settings così com’è. Una build senza alcun plugin di governance associato esegue il socket come un’operazione nulla, quindi l’associazione è puramente additiva per un workspace.
Un plugin che serve più ruoli viene associato una volta per ruolo, ciascuna associazione con le proprie regole e le proprie impostazioni:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltQuale versione nomina un’associazione. Un uri nomina un’entità Plugin — la coordinata <pluginType>/<name> e, dopo i due punti, una versione — e la versione partecipa alla risoluzione. Per i due motori compilati nella CLI, l’entità proviene da uno di due luoghi. Ogni release del compilatore pubblica le entità Plugin di governance/rego e governance/cel alla propria versione, e il catalogo della libreria standard le contiene, ciascuna alla versione della release che l’ha pubblicata; un workspace le legge dalle directory di catalogo che elenca. Il binario aggrega contiene un’entità di ciascuno, alla versione della propria release e a nessun’altra. Un’associazione che nomina una versione che nessuno dei due contiene, e che nessun pull ha recuperato nella cache dei contenuti, arresta la build con E0137, nominando il riferimento.
Quindi un’associazione nomina una versione contenuta nel catalogo letto dal workspace. Quella versione si risolve dal catalogo anche con una release di aggrega diversa dalla sua, mentre una versione contenuta solo nel binario — quella della sua stessa release — si risolve soltanto con quella release, sia in un ruolo di verdetto sia in un ruolo di trasformazione. In un ruolo di trasformazione il pull fissa nel lockfile la versione che ha risolto, e rifiuta con E0103 una versione che non è contenuta né in un catalogo letto dal workspace né nel binario. La versione seleziona l’entità Plugin, che registra gli export e i limiti di runtime del plugin, e non il motore: una volta risolto il riferimento, il motore che viene eseguito è quello compilato nel binario che esegue la build, perché i plugin integrati nel binario sono il primo luogo da cui viene letto il modulo di un plugin. Un plugin di governance dichiarato dal workspace stesso — un’entità Plugin nella sua directory di catalogo, con il suo .wasm accanto — viene nominato alla versione registrata da quell’entità.
Ogni ruolo seleziona una funzione di ingresso predefinita — verdict_ir per il ruolo che giudica il grafo, verdict_render per il ruolo che giudica gli artefatti renderizzati, mutate per il ruolo che modella le etichette, transform_annotations per il ruolo che inietta le annotazioni — e un’associazione può indirizzare un ruolo verso un export diverso con function:. L’host rifiuta un invio a un export che il guest non ha dichiarato nella sua autodescrizione describe(), quindi un’associazione che nomina un ruolo che il suo guest non serve viene segnalata per nome, prima che il guest venga eseguito, anziché non fare nulla in silenzio.
function: nomina un export del plugin nominato dall’uri. Un’associazione in un ruolo di verdetto — ir-verdict o render-verdict — che nomina una function: e nessun uri: nomina una funzione di nessun plugin, quindi la configurazione viene rifiutata già in lettura, con E0224, nominando il file e la posizione della voce nel suo elenco: aggiungi l’uri del plugin che esporta la funzione.
L’elenco plugins.governance ha una controparte additiva, plugins.governance_append: le voci della controparte vengono accodate all’elenco governance risolto a ogni livello di configurazione, così un workspace o una configurazione globale compone le associazioni di policy anziché oscurare un elenco di base.
L’overlay di proprietà della CI
Accanto al .aggrega-config.yaml scritto a mano, una pipeline automatizzata può possedere un file di overlay separato, .aggrega-config-append-ci.yaml. Esiste perché una pipeline possa associare policy (o altra configurazione con valori di tipo elenco) che controlla senza mai modificare la configurazione di base scritta a mano dallo sviluppatore — la pipeline può sovrascrivere per intero il proprio file di overlay.
L’overlay è strettamente additivo. Viene validato rispetto allo stesso schema di configurazione del file di base, e per ogni campo con valori di tipo elenco le sue voci vengono accodate all’elenco risolto. Può solo aggiungere: non può rimuovere una voce di base e non può sovrascrivere un valore scalare di base — una chiave scalare o di mappa che contiene non ha alcun significato additivo e viene ignorata (e nominata in un avviso di risoluzione) anziché applicata. E non stabilisce mai la radice di un workspace: lo fa solo un .aggrega-config.yaml che porta un blocco workspace:, quindi inserire l’overlay in una directory aggiunge associazioni senza cambiare il punto in cui inizia il workspace.
Questo offre a una pipeline un punto di giunzione pulito per imporre policy a livello di organizzazione: la pipeline deposita un .aggrega-config-append-ci.yaml che nomina i plugin di policy obbligatori, e quelle associazioni si fondono sopra qualunque cosa lo sviluppatore abbia scritto, mai al suo posto.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ costruisce un workspace con l’associazione di un team, quella di un’organizzazione aggiunta tramite il governance_append di un file di configurazione globale e quella di una pipeline aggiunta tramite questo overlay, e verifica che cosa stampa ciascuna combinazione e se si completa.
Testare una policy prima che blocchi una build
Una regola Rego che nomina un percorso che il payload del suo ruolo non porta non è un errore: il percorso è indefinito, la regola non vale mai, e la build si completa come se la policy l’avesse consentita. Quindi una nuova policy si guadagna halt in tre mosse: associarla a una severità che segnala senza arrestare, verificare ogni percorso che nomina rispetto al payload che riceve il suo ruolo, e leggere che cosa segnala sulle build che giudicherà.
I comandi seguenti vengono eseguiti in una copia di examples/policy-org-overlay/ il cui .aggrega-config.yaml associa una nuova policy al posto di quella del team. Ha lo scopo di rifiutare un datastore che funziona con l’alta disponibilità disattivata, e la sua regola è stata copiata da una policy che modella le etichette:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Associala in modo che segnali. La policy raccoglie sotto deny, che per impostazione predefinita arresta la build. Una translation che nomina solo deny, a warn, segnala ciascuna delle sue decisioni come avviso e lascia completare la build; info invece le registra. La policy stessa resta come verrà applicata:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnScrivi il payload e cercaci i percorsi. Una volta che una build ha riempito il lockfile della Release,
aggrega build --release release.yaml --dry-run --policy-input payloadsscrive in payloads/ il payload che ciascun ruolo passa alle proprie associazioni, e nient’altro, riportando, con <workspace> al posto della directory in cui è stata eseguita la build:
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]I quattro sono annotation-transform.json, ir-verdict.json, label-transform.json e render-verdict.json; viene scritto anche un ruolo senza nulla di associato, così una policy può essere verificata rispetto al proprio ruolo prima di essere associata da qualche parte. In ir-verdict, label-transform e annotation-transform il file è il documento input che una policy legge, quindi ogni percorso nominato da una regola può esserne estratto con qualsiasi strumento JSON prima di fidarsi della regola:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}I nodi della regola non sono lì: input.graph.nodes è dove li porta il ruolo che modella le etichette, e in ir-verdict si trovano in input.graph.spec.nodes (vedi Che cosa espone il payload di ciascun ruolo). Il file dice anche che cosa deve decidere la regola corretta: db è un datastore, la sua alta disponibilità è disattivata e deve essere segnalato.
Dove OPA è installato, una policy Rego viene valutata direttamente rispetto allo stesso file, opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Il motore Rego nel compilatore è un’implementazione indipendente, quindi la valutazione che decide resta la build: una funzione integrata che non implementa arresta la build anziché essere valutata.
In render-verdict il file non è l’input della policy. Ogni artefatto al suo interno porta il proprio path, content e format; i documents che una regola legge vengono ricavati dal contenuto dal motore di policy una volta ricevuto il payload, quindi una regola su documents non trova nulla nel file. Una policy in quel ruolo si testa dove il motore li ricava: in una build, come mostra il passo successivo.
Esegui la build e confronta ciò che segnala con ciò che dice il payload. Con il percorso copiato,
aggrega build --release release.yaml --auto-pullsi completa e non segnala nulla:
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]Il payload contiene un datastore con l’alta disponibilità disattivata, e la policy non ha detto nulla al riguardo: quel silenzio è l’errore, e nient’altro nella build lo indica. Con la regola che legge input.graph.spec.nodes, lo stesso comando segnala db e si completa:
policy plugin "rego" warning: db is a datastore running with high availability offPull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]Aggiungere --dry-run segnala gli stessi verdetti e non scrive alcuna dist/, così il ciclo viene eseguito su un workspace senza alterarne l’output.
La stessa regola scritta per il motore CEL non fallisce in silenzio. Lì leggere una chiave che il payload non porta è un’anomalia di valutazione, quindi il percorso copiato, in policies/datastore-ha.cel associato con la stessa translation,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}arresta la build anche a warn. Termina con 1, e la sua ultima riga nomina il file della policy e la chiave:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesUna policy render-verdict si testa allo stesso modo. Associata a render-verdict nello stesso workspace, con la stessa translation, una regola che rifiuta un servizio Compose che pubblica una porta sull’host,
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}segnala l’unico servizio che lo fa:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Poi applicala. Rimuovere la translation riporta deny a halt, e la build che segnalava db ora si arresta su di esso, termina con 1 e non scrive alcuna dist/:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationL’associazione che segnala non deve essere rimossa ovunque in una volta. Un file di configurazione può mantenere la translation della propria associazione a warn mentre l’overlay di una pipeline associa la stessa policy con deny a halt, ed è così che examples/policy-org-overlay/ introduce la regola di un’organizzazione: un avviso sulla build di uno sviluppatore, e il motivo per cui la build di una pipeline si arresta.
Eseguire le policy in CI, sull’output della build
Tutto ciò che precede associa una policy all’interno di una build. Esiste una seconda strada, e non richiede nulla dal socket: eseguire il tuo strumento nella pipeline, sui file che la build ha scritto.
Funziona grazie a ciò che una build emette. I target Kubernetes e Compose scrivono YAML; il target Terraform scrive HCL nativo, o JSON nella sua forma .tf.json. Sono i formati che gli strumenti di configurazione dell’ecosistema leggono già — e aggrega build scrive file semplici in una directory, senza alcun formato contenitore, nessun indice e nulla da estrarre. Quindi uno strumento che legge YAML, JSON o HCL viene eseguito sull’output di una build nello stesso modo in cui viene eseguito su una configurazione scritta a mano da una persona, e Aggrega non aggiunge alcun socket, alcun tipo di plugin né alcuna chiave di configurazione per questo.
Quindi un corpus di regole esistente non richiede alcun porting. Se mantieni già regole in Conftest, nella CLI di Kyverno, in kubeconform, in Checkov o in OPA, quelle regole vengono eseguite sull’output di una build di Aggrega così come sono, e lo strumento che le valuta è quello che la tua pipeline installa già.
Due script di regole pronti all’uso, ciascuno con il passo della pipeline che lo invoca ed entrambi i rifiuti che hanno prodotto su build reali, si trovano in examples/policy-in-ci/. Usano yq e nient’altro, quindi vengono eseguiti senza alcuna toolchain di policy installata; la forma che mostrano — leggere la directory di output, decidere, terminare con un codice diverso da zero nominando gli artefatti in violazione — è la forma che assume qualsiasi strumento in questa posizione.
A quale strada appartiene una regola
Entrambe le strade sono di prima classe, e un workspace usa comunemente entrambe. Ciò che decide è che cosa la regola ha bisogno di vedere e quando deve agire.
Associala al socket quando:
- la build non deve produrre affatto l’artefatto. Una policy
ir-verdictviene eseguita al controllo di analisi statica, prima che qualcosa venga renderizzato, quindi un arresto lì non lascia nulla di scritto — nessun file di output da revisionare, mettere in quarantena o applicare per errore. Un controllo in pipeline viene necessariamente eseguito dopo che i file esistono. - la regola ha bisogno di fatti che solo la build possiede. Il ruolo
ir-verdictlegge il grafo assemblato: nodi, archi e i loro socket, ogni associazione con lo slot che ha riempito, quali valori un autore ha dichiarato sensibili, i percorsi di routing. Niente di tutto ciò sopravvive nell’output renderizzato — un manifest Kubernetes non registra quale socket ha consegnato un valore o quale Feature ha contribuito una risorsa — quindi una regola sulla topologia o sulla provenienza ha una sola sede, ed è il socket. - la regola deve valere ovunque venga eseguita la build. Un’associazione di governance risiede nella configurazione del workspace, quindi si applica alla build locale di uno sviluppatore tanto quanto a quella della pipeline. Un controllo in pipeline si applica dove viene eseguita la pipeline.
- la regola deve modellare la build anziché giudicarla. Solo un ruolo di trasformazione lo fa, e solo perché un operatore lo ha associato.
Eseguila in CI quando:
- la regola esiste già, in uno strumento che il tuo team esegue e revisiona, su un formato che quello strumento analizza già. Riesprimerla come contenuto di policy del socket è lavoro che alla fine non porta alcuna nuova copertura.
- la regola riguarda gli artefatti così come il target li riceverà — l’insieme finale di file, dopo ogni trasformazione, nella forma che viene applicata. È anche l’oggetto del ruolo
render-verdict, quindi su questo punto, preso da solo, le due strade vedono la stessa cosa e la scelta dipende dagli altri. - il risultato è destinato a un revisore anziché alla build. Una pipeline che pubblica gli artefatti e i risultati fianco a fianco offre a un revisore entrambi; una build arrestata gli offre un messaggio.
- il controllo va oltre una singola build — confrontando l’output di questa build con quello dell’ultima, con lo stato effettivo di un cluster o con un inventario che nessun payload di build porta. Una policy in uno dei due ruoli di verdetto vede la build a cui è associata, ed è tutto ciò che vede.
Le strade si compongono anziché competere: un’invariante di topologia arresta la build da ir-verdict, e la stessa pipeline esegue poi le regole sugli artefatti già esistenti del parco IT su ciò che quella build ha scritto.
Riferimenti incrociati
plugin-contract.md— la collocazione del socket nella pipeline, le forme tipizzate dei dati trasmessi che porta e la sandbox in cui viene eseguito ogni plugin.plugin-developer-guide.md— la scrittura di un plugin, l’autodescrizionedescribe()e il ciclo di vita publish → pull → build.../entities/plugin.md— l’entitàPluginche porta un plugin nel catalogo.../cli/aggrega-build.md— il comando di build che invoca il socket.../schema/other/aggrega-config.md— lo schema della configurazione del workspace, inclusa la superficie di associazioneplugins.governance.../examples/policy-in-ci/— due script di regole eseguibili sull’output di una build, con il passo della pipeline per ciascuno.../examples/policy-data-class-route/— una regolair-verdictsui percorsi, scritta per il motore Rego, il motore CEL e OPA dietro il guest adattatore di riferimento, associata per build da un file--configper motore, con uno script che verifica che tutti e tre raggiungano lo stesso esito su ogni Release.