Policy a livello di organizzazione: la regola di un team, quella di un’organizzazione e quella di una pipeline
La policy di un team, quella della sua organizzazione e quella della sua pipeline vengono eseguite insieme su un’unica build, ciascuna associata in un proprio file di configurazione. Il team associa la sua regola nel suo workspace; l’organizzazione ne aggiunge una a ogni build, e la pipeline ne aggiunge un’altra, senza che nessuna delle due modifichi il file del team. Una build legge tutti i file che la riguardano ed esegue ogni associazione che contengono.
Le regole segnalano a tutte e tre le severità di verdetto: info e warn lasciano che la build si completi, e halt la ferma. Una di esse, quella dell’organizzazione, è associata due volte e segnalata ogni volta a una severità diversa, tramite un blocco translation.
Che cosa costruisce
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
db | core/datastore/mariadb | il database del negozio |
web | core/devtool/adminer | un’interfaccia di amministrazione del database, cablata a db |
Entrambi sono compilati per Docker Compose, in dist/compose/docker-compose.yaml. Un Aggregate, un Manifest e una Release, release.yaml; nessuno di essi nomina una policy.
I tre file
| chi | file | come lo legge una build | dove è scritta l’associazione |
|---|---|---|---|
| il team | .aggrega-config.yaml | contrassegna questa directory come workspace, quindi ogni build qui lo legge | plugins.governance |
| l’organizzazione | org/config.yaml | come file di configurazione globale, indicato per una singola build con --config org/config.yaml | plugins.governance_append |
| la pipeline | pipeline/.aggrega-config-append-ci.yaml | una volta copiato in questa directory, come overlay della pipeline | plugins.governance_append |
Tutte e tre le associazioni sono il motore Rego, governance/rego:0.9.0, al ruolo ir-verdict, che giudica il grafo di build prima che qualcosa venga renderizzato. 0.9.0 è la versione della sua entità Plugin nel catalogo della libreria standard. Il motore stesso è compilato nella CLI — aggrega plugin list elenca governance/rego tra i built-in incorporati — quindi nessuna build qui scarica un plugin.
Il file dell’organizzazione è un file di configurazione globale. Una macchina ne ha uno, letto a ogni build: dalla sua posizione predefinita, oppure il file indicato dalla variabile d’ambiente AGGREGA_CONFIG. --config <path> ne indica invece uno per una singola esecuzione, e i file propri del workspace vengono comunque letti sopra di esso. In un’organizzazione il file si troverebbe nella posizione predefinita sulla macchina di ogni sviluppatore e in ogni pipeline; qui si trova in org/, e le build che devono leggerlo lo indicano. Indicare esplicitamente il file globale espone l’ordine in cui vengono tentati i tre modi.
Il file della pipeline è un overlay. Una build legge .aggrega-config-append-ci.yaml nelle directory da cui legge .aggrega-config.yaml, accanto a esso. Qui è tenuto in pipeline/, dove una build eseguita in questa directory non lo legge, perché arresta ogni build che lo legge; il passo della pipeline consiste nel copiarlo dentro:
cp pipeline/.aggrega-config-append-ci.yaml .Ogni file aggiunge, e l’overlay della pipeline aggiunge soltanto
L’organizzazione e la pipeline scrivono entrambe la propria associazione sotto plugins.governance_append, la controparte di accodamento dell’elenco plugins.governance. Le voci sotto una controparte vengono accodate all’elenco risolto dopo che sono stati letti gli elenchi propri di ciascun file, quindi vengono eseguiti sia il plugins.governance del team sia la voce dell’organizzazione, e nessuno dei due file nomina l’altro. L’organizzazione scrive la controparte, e non plugins.governance stesso, perché un elenco plugins.governance nel file del workspace sostituisce quello nel file globale: una regola dell’organizzazione scritta lì viene scartata dall’elenco del team, e la build non stampa nulla al riguardo. Estendere un elenco anziché sostituirlo elenca la controparte di ciascuna impostazione di tipo elenco.
L’overlay della pipeline può solo aggiungere. Ciò che scrive per un’impostazione di tipo elenco viene aggiunto a ciò che gli altri file hanno risolto; non rimuove nulla, e non sovrascrive un’impostazione che contiene un singolo valore, come auto_pull. Questo contiene auto_pull: true, e una build che lo legge ignora la chiave e lo dice in un avviso. Con <workspace> al posto del percorso assoluto della directory in cui è stata eseguita la build, la riga recita:
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)Le regole, e la severità a cui ciascuna viene segnalata
Una policy Rego raccoglie ogni decisione sotto una chiave di decisione, e la chiave sceglie la severità a cui la decisione viene segnalata. Senza translation le chiavi sono deny, warn e audit, segnalate a halt, warn e info:
| severità | che cosa fa la build |
|---|---|
halt | si arresta, esce con 1 e non scrive alcun dist/ |
warn | si completa, stampa il messaggio e scrive dist/ |
info | si completa, stampa il messaggio e scrive dist/ |
La regola del team, policies/team.rego, raccoglie sotto warn, e la sua associazione non dichiara alcuna translation, quindi viene segnalata a warn:
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}La regola dell’organizzazione, org/policies/estate.rego, rifiuta i componenti di una categoria elencata nelle sue impostazioni, e registra che cosa esegue ciascun componente:
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories è un’impostazione di ciascuna associazione, e una policy legge le impostazioni della sua associazione come il proprio documento data.
Traduzione: una regola, due severità
Un blocco translation nelle impostazioni di un’associazione dichiara quali chiavi di decisione vengono lette e la severità a cui ciascuna viene segnalata. Sostituisce la mappatura predefinita anziché estenderla: una chiave che non nomina non viene letta.
Il file dell’organizzazione introduce la propria regola come consiglio. La sua associazione segnala deny a warn, e audit a info:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoLa pipeline associa lo stesso file e fa sì che la stessa regola arresti la build. La sua traduzione nomina solo deny, quindi la sua associazione non segnala una seconda volta le registrazioni audit:
settings: refused_categories: [devtool] translation: - key: deny severity: haltCosì una sola regola, sullo stesso web, è un avviso sulla build di uno sviluppatore e il motivo per cui la build di una pipeline si arresta.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example policy-org-overlayPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd policy-org-overlayBuild
Il catalogo della libreria standard fornisce i Components, le Recipes, la Feature e la sua FeatureRecipe. Vengono risolti da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml nomina. Con un checkout del catalogo (dove ottenerne uno) indicato con --catalog, nulla viene scaricato da un registry, quindi le build vengono eseguite offline. --auto-pull riempie il lockfile durante la build; il lockfile e l’output renderizzato sono generati, non distribuiti.
Con il solo file del team:
aggrega build --release release.yaml --auto-pullla build stampa l’avviso del team e si completa. Con in più il file dell’organizzazione:
aggrega build --release release.yaml --auto-pull --config org/config.yamlstampa le registrazioni dell’organizzazione a info e la sua regola a warn, accanto all’avviso del team, e si completa comunque:
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull 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]Ogni verdetto nomina il plugin che lo ha segnalato, rego, e non il file che lo ha associato, quindi l’avviso del team e quello dell’organizzazione si leggono allo stesso modo; un messaggio che dice di chi è la regola, come fa quello dell’organizzazione, è il modo per distinguerli.
Con l’overlay della pipeline copiato dentro, lo stesso comando si arresta:
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violationLa build esce con 1 e non scrive alcun dist/. La regola dell’organizzazione viene segnalata due volte, una da ciascuna associazione: a warn da quella dell’organizzazione e a halt da quella della pipeline. Le registrazioni audit compaiono una volta, dalla sola associazione dell’organizzazione. Rimuovi .aggrega-config-append-ci.yaml da questa directory per eseguire di nuovo la build senza di esso.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `policy-org-overlay`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-org-overlay` e senza `dir`: scrive l’esempio in una nuova cartella `policy-org-overlay`. Poi chiama lo strumento `build` con `workspace_root` impostato a `policy-org-overlay`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `write` impostato a true, e dimmi che cosa ha riportato la policy. Poi chiama lo strumento `cli-build`, che esegue `aggrega build` e accetta il suo flag `--config`, con `workspace_root` impostato a `policy-org-overlay`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `config` impostato a `org/config.yaml`, e dimmi che cosa ha riportato la policy questa volta. Dimmi quali file ha scritto ogni build; si trovano in `policy-org-overlay/dist/`.Verificare ogni build
Questo controllo automatico viene eseguito in un checkout del repository della documentazione, che contiene lo script di build condiviso che usa; una copia scritta da aggrega scaffold --example non porta con sé quello script.
./check.shcheck.sh esegue la build di release.yaml cinque volte, tramite l’helper build-release, ciascuna in una copia di questo workspace: con il solo file del team, con il file dell’organizzazione indicato da --config, con l’overlay della pipeline copiato dentro, con entrambi, e con una copia del file dell’organizzazione che scrive la propria associazione sotto plugins.governance anziché sotto la controparte — dove l’elenco del team la sostituisce, e viene stampato solo il verdetto del team. Per ciascuna verifica lo stato di uscita, se dist/ è stato scritto, e ogni verdetto che la build ha stampato — la sua severità e il suo messaggio, senza che manchi nulla e senza nient’altro — e, dove l’overlay viene letto, l’avviso che nomina auto_pull. Stampa una riga per build, poi i verdetti che ciascuna ha stampato, ed esce con 1 se un esito differisce, stampando l’output di quella build:
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.Le copie vengono create in una directory temporanea, con il percorso del catalogo nel loro .aggrega-config.yaml reso assoluto così che si risolva ancora da lì; nessun file in questa directory viene modificato o scritto. Usa il binario che ./build-release.sh risolve, quindi AGGREGA_BIN lo sceglie, e gli argomenti dopo -- arrivano a ogni build. Il suo stato di uscita è l’intero verdetto.
Dove il compilatore non interpreta
Il compilatore legge i tre file, accoda le associazioni che contengono, passa a ciascuna policy il grafo di build e le sue impostazioni, e agisce in base alla severità a cui ciascuna decisione viene segnalata. Non sa che cos’è un devtool, perché un’organizzazione non ne distribuirebbe uno, né che l’alta disponibilità conta per un team: quei significati sono le regole e le impostazioni delle policy. Per i ruoli, i payload e le chiavi di decisione, vedi il socket di governance.
File
aggregate.yaml— il database e l’interfaccia di amministrazione cablata a esso.manifest.yaml— lega ogni tipo di componente e la Feature dei secret alla sua Recipe Docker Compose.release.yaml— l’unica Release..aggrega-config.yaml— il file del team: il registry predefinito e l’associazione del team.policies/team.rego— la regola del team.org/config.yaml— il file di configurazione globale dell’organizzazione e la sua associazione.org/policies/estate.rego— la regola dell’organizzazione.pipeline/.aggrega-config-append-ci.yaml— l’overlay della pipeline, letto una volta copiato in questa directory.build-release.sh— esegue la build della Release, mostrando il comandoaggrega buildequivalente.check.sh— esegue i cinque build e verifica ciascun esito.