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

Schema del file di lock per Release di Aggrega

Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.

Id dello schema: https://aggrega.ai/schemas/lockfile-v1beta1.schema.json

File di lock generato automaticamente che fissa ogni URI risolto da una Release per build future deterministiche. Si trova in <release-stem>.lock accanto a <release-stem>.yaml; è prodotto da aggrega pull --release <release>; è consumato da aggrega build --release <release>. Due forme di provenienza registrano due relazioni distinte nel grafo delle dipendenze: referenced_from (elenco di stringhe) compare su entities, come percorsi puntati dei siti di authoring che registrano da dove, nella Release / Aggregate / Manifest / .aggrega-config.yaml, è stato incluso ciascun URI, e su plugins, come il riferimento di ciascuna entità Plugin attraverso cui è stato raggiunto un artefatto; consumers (elenco di record {consumer_uri, fragments}) compare su schema_libraries, mapping_libraries, workload_libraries e artifact_libraries per registrare quale entità di catalogo fa riferimento a quali frammenti <entry-name> di una libreria — la forma strutturata rende tracciabili i diff dei consumatori interessati dall’aggiornamento di versione di una libreria senza risolvere di nuovo la Release. Disciplina di evoluzione dello schema: aggiungere una nuova sezione di primo livello è SemVer-MINOR (additivo); aggiungere un nuovo campo all’interno di una sezione esistente è SemVer-MINOR; rimuovere una chiave o restringere un vincolo è SemVer-MAJOR.

Tipo di primo livello: object

Proprietà

ProprietàTipoObbligatoriaDescrizione
entitiesobject[]noEntità di catalogo raggiungibili da questa Release: Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, l’Aggregate e il Manifest propri della Release, e il Manifest che quel Manifest estende. Ogni voce è identificata dal suo kind insieme al suo URI canonico, così due entità di tipi diversi che condividono un nome — ad esempio un Aggregate e un Manifest entrambi di nome imported/flow — sono due voci, ciascuna verificata rispetto al proprio digest. Ognuna registra la versione risolta, il digest di ciò che l’entità porta e le origini nei siti di authoring (referenced_from) che hanno incluso l’URI nella chiusura delle dipendenze della Release. Un lockfile le cui voci non portano alcun kind non è aggiornato: aggrega pull --release <release> lo riscrive. Predefinito: []
external_inputsExternalInput[]noInput remoti fissati nell’archivio di input indirizzato per contenuto al momento dell’acquisizione — contenuto che il rendering di un plugin del provider consuma dall’esterno del workspace, come documenti di schema remoti o dipendenze di chart non vendorizzate. Ogni voce fissa un URL al digest che ne nomina i byte nell’archivio. La build serve gli input fissati dall’archivio e legge questa sezione senza accesso alla rete. Predefinito: []
generated_atstringsìTimestamp RFC 3339 del pull che ha prodotto questo file di lock; il pattern vincola il valore a quella forma quando il file di lock viene caricato. Provenienza diagnostica — registra l’istante, secondo l’orologio di sistema, della risoluzione. Cambia intenzionalmente tra un pull e l’altro; non fa parte della garanzia di identità byte per byte del file di lock. Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$.
mapping_librariesLibraryEntry[]noVoci di MappingLibrary che la chiusura delle dipendenze della Release raggiunge tramite i siti valuesMapping: { $import: ... } di Recipe / FeatureRecipe. L’elenco consumers di ciascuna voce registra quale entità di catalogo fa riferimento a quali frammenti <entry-name> della libreria — un record strutturato che rende tracciabili i diff dell’impatto di un aggiornamento di versione della libreria senza risolvere di nuovo la Release. Predefinito: []
mutatorsobject[]noAssociazioni di governance con ruolo di trasformazione risolte, nell’ordine in cui sono state scritte. Un plugin con ruolo di trasformazione (label-transform, che riscrive le etichette dei nodi; oppure annotation-transform, che inietta annotazioni prima dell’espansione) modella i byte dell’output renderizzato, quindi l’insieme delle associazioni — l’elenco ordinato, più per ciascuna associazione il ruolo, la coordinata del plugin e la funzione esportata — è un input che determina i byte, fissato qui. La build legge questa sezione — mai .aggrega-config.yaml — per ricostruire l’insieme, l’ordine, il ruolo e la funzione esportata, quindi l’output della build è invariante rispetto a una modifica di plugins.governance fatta dopo il pull (adottata solo al pull successivo). L’ordine è SEMANTICO: ciascun esecutore di trasformazione applica le associazioni del proprio ruolo nell’ordine dell’elenco, quindi, a differenza delle sezioni plugins / providers ordinate per URI, questo elenco non viene mai riordinato. Il digest del contenuto del plugin NON è duplicato qui: ha un’unica fonte nelle sezioni plugins ed entities, verso cui questo record punta per identità. Predefinito: []
pluginsobject[]noI plugin Wasm i cui byte modellano l’output renderizzato, ciascuno fissato dal digest del contenuto del suo .wasm: un plugin di governance associato con un ruolo di trasformazione (label-transform, annotation-transform) sotto .aggrega-config.yaml plugins.governance, più qualsiasi URI di plugin incorporato proveniente da Recipes / FeatureRecipes / Providers referenziati. Un plugin di governance associato con un ruolo di verdetto (ir-verdict, render-verdict) e un’associazione plugins.linter restituiscono un verdetto e non modellano alcun byte di output, quindi nessuno dei due viene fissato: nessuno dei due compare qui o sotto entities, e i file di regole che un’associazione di verdetto legge sono registrati sotto verdict_inputs. Predefinito: []
providersobject[]noSelezioni del provider per capacità risolte. Ogni voce fissa una capacità (ad es. helm) all’identità OCI senza digest del plugin di rendering del provider che la renderizza, risolta al pull dall’elenco plugins.providers di .aggrega-config.yaml (quando la capacità è servita in modo ambiguo) oppure dall’unico plugin che la serve (quando non c’è ambiguità). La build legge questa sezione — mai .aggrega-config.yaml — per selezionare il provider, quindi l’output della build è invariante rispetto a modifiche della configurazione del workspace fatte dopo il pull. Il digest del contenuto del plugin NON è duplicato qui: ha un’unica fonte nelle sezioni plugins ed entities, verso cui questo record punta per identità. La coesistenza delle versioni è preservata: questo record seleziona il repository del plugin per capacità; le versioni concrete si trovano in entities (una voce per ogni versione del plugin risolta), e il fissaggio di versione spec.capability di ciascuna Recipe seleziona tra di esse al momento del rendering. Predefinito: []
releasestringsìPercorso della Release a cui corrisponde questo file di lock, risolto in modo relativo alla directory propria del file di lock (ad es. ./release-prod.yaml). La convenzione di denominazione per Release colloca <release-stem>.lock accanto a <release-stem>.yaml; il percorso relativo rende il file di lock autodescrittivo senza percorsi assoluti specifici della macchina. Questo nomina la Release; ciò che la Release conteneva quando è stata risolta è registrato sotto release_documents.
release_documentsobject[]noI file della Release letti dalla risoluzione, ciascuno registrato tramite il digest del contenuto dei suoi byte: prima la Release a cui appartiene questo file di lock, poi ogni Release che essa estende, nell’ordine in cui viene percorsa la catena extends. Tutto ciò che una Release richiede viene risolto a partire da ciò che contiene, quindi una Release modificata dopo il pull non corrisponde più al digest registrato, e una build — o aggrega pull --verify — si arresta nominando il file, con aggrega pull --release <release> come rimedio, prima che qualcosa venga renderizzato. Il digest copre i byte così come sono, senza nulla di normalizzato, la stessa regola che seguono i fissaggi dell’Aggregate e del Manifest: una modifica a un commento o agli spazi conta come una modifica. Un file di lock senza questa sezione non registra alcun file della Release, e una build che dispone di un tale file di lock riporta la Release come non registrata. Un file che la Release importa tramite parameters non è registrato qui.
schema_librariesLibraryEntry[]noVoci di SchemaLibrary che la chiusura delle dipendenze della Release raggiunge tramite i siti $ref e $import: nel contenuto schema: / usesSchema: / featuresSchema: delle entità. L’elenco consumers di ciascuna voce registra quale entità di catalogo fa riferimento a quali frammenti <entry-name> della libreria — un record strutturato che rende tracciabili i diff dell’impatto di un aggiornamento di versione della libreria senza risolvere di nuovo la Release. Predefinito: []
source_artifactsSourceArtifactEntry[]noArtefatti sorgente scaricati dai campi spec.source di Recipe / FeatureRecipe al momento del pull. Ogni voce identifica un’identità {kind, url, chart, pinned_version} univoca con il digest del contenuto, il mediatype e i puntatori all’indietro strutturati referenced_by: che nominano ogni entità di catalogo risolta in questo artefatto. url è l’URL di identità scritto dall’autore; la posizione risolta dell’artefatto per una sorgente helm con radice del repository è registrata separatamente sotto resolved_url: come provenienza. Più Recipes che fissano lo stesso chart alla stessa versione vengono deduplicate in un’unica voce con più record referenced_by:. L’enum dei tipi copre i quattro tipi di sorgente che si risolvono, e terraform-module-oci, che nessun adattatore di sorgente serve: una Recipe o una FeatureRecipe che lo nomina viene rifiutata quando viene letta, quindi nessun pull registra una voce di quel tipo. Predefinito: []
toolchainobjectnoVersioni della toolchain che ha prodotto questo file di lock: la versione propria del compilatore e la versione di ciascun plugin core che il compilatore porta con sé. Registrate affinché un file di lock risponda a posteriori su quale compilatore e quali plugin core hanno risolto e renderizzato una build — una domanda a cui le sezioni fissate non sempre possono rispondere, perché un plugin di provider core servito dall’interno del binario del compilatore viene lasciato senza fissaggio e quindi non porta alcuna versione registrata propria. Solo versioni: il timbro non registra mai da dove provengono i byte di un plugin, quindi due macchine che hanno fissato la stessa chiusura delle dipendenze con lo stesso compilatore scrivono lo stesso timbro. Nulla confronta questa sezione, avvisa a suo riguardo o rifiuta una build a causa sua, e la sua assenza da un file di lock è silenziosa: la toolchain non fa parte della chiusura delle dipendenze che il file di lock fissa. Per lo stesso motivo la sezione è esclusa dal confronto di identità byte per byte tra due pull degli stessi input, alla pari di generated_at.
verdict_inputsobject[]noInput esterni delle regole che un’associazione di governance con ruolo di verdetto (ir-verdict / render-verdict) legge in fase di compilazione — un file di regole Kyverno / Rego fornito tramite il with.sources dell’associazione. Registrati come digest del contenuto per sorgente, per l’audit e per la visibilità della deriva tra un pull e l’altro: il digest che ha determinato un verdetto è confrontabile tra i pull, così un file di regole modificato emerge come diff del file di lock. Questa sezione è PROVENIENZA, non un input della build: a differenza di mutators.sources non porta alcun content, e la build NON la legge — un plugin di verdetto viene messo in cache anziché fissato e legge i propri input delle regole dal vivo (il verdetto non determina alcun byte dell’output, quindi nulla di ciò che il file di lock fissa per un output deterministico lo include). Poiché un plugin di verdetto non è fissato, è assente dalle sezioni entities / plugins; questo record identifica quindi l’associazione tramite il suo URI scritto dall’autore, a sé stante anziché puntare in quelle sezioni. Registrare il digest rende verificabili e riproducibili gli input che hanno determinato una decisione di accettazione o rifiuto senza fissarli nella build. Predefinito: []
versionconst 1sìVersione dello schema del file di lock: 1. Una modifica SemVer-MAJOR allo schema la incrementa. Costante: 1
workload_librariesLibraryEntry[]noVoci di WorkloadLibrary che la chiusura delle dipendenze della Release raggiunge tramite i siti workload: { $import: ... } di Recipe. L’elenco consumers di ciascuna voce registra quale entità di catalogo fa riferimento a quali frammenti <entry-name> della libreria — un record strutturato che rende tracciabili i diff dell’impatto di un aggiornamento di versione della libreria senza risolvere di nuovo la Release. Predefinito: []
artifact_librariesLibraryEntry[]noVoci di ArtifactLibrary che la chiusura delle dipendenze della Release raggiunge tramite i siti artifacts.<name>: { $import: ... } di Recipe / FeatureRecipe. L’elenco consumers di ciascuna voce registra quale entità di catalogo fa riferimento a quali bundle <entry-name> della libreria — un record strutturato che rende tracciabili i diff dell’impatto di un aggiornamento di versione della libreria senza risolvere di nuovo la Release. Predefinito: []

Non sono consentite proprietà aggiuntive.

lockfile.entities[]

ProprietàTipoObbligatoriaDescrizione
kindstring (enum)sìTipo dell’entità di catalogo, letto da dove la Release, il suo Aggregate o il suo Manifest la nomina: component e feature per un tipo di Component o di Feature che l’Aggregate, la Release o una mappatura del Manifest nomina, recipe e feature_recipe per una realizzazione che una mappatura del Manifest vincola, plugin per un’entità Plugin, aggregate per l’Aggregate proprio della Release e per ogni Aggregate che esso include, e manifest per il Manifest proprio della Release e per il Manifest che esso estende. Insieme a uri identifica la voce: una build confronta ogni voce con l’entità dello stesso tipo e URI, così una modifica a una qualsiasi di due entità omonime di tipi diversi viene rilevata. Valori ammessi: "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe"
uristringsìURI canonico dell’entità di catalogo (ad es. hub.aggrega.ai/component/core/compute/api-server).
resolved_versionstringsìVersione concreta che il resolver ha selezionato al momento del pull — la versione propria di un’entità di catalogo (ad es. 1.2.3), oppure vuota per un’entità di primo livello risolta tramite percorso anziché tramite versione. Registrata come un singolo segmento di percorso, perché ne nomina uno, quindi non contiene /, \ né ..: il valore costruisce lo slot della cache da cui la build rilegge questa entità, e un valore che uscisse dalla directory della cache nominerebbe una posizione al di fuori di essa. Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringsìDigest di ciò che porta una pubblicazione dell’entità, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli: lo SHA-256 calcolato sul documento dell’entità e su ogni file che dichiara accanto a esso, ordinati per percorso, ciascuno dei quali contribuisce con il proprio percorso e lo SHA-256 dei propri byte. Un’entità che non dichiara alcun file conta come il suo unico documento. Nient’altro vi entra — né il modo in cui un archivio è stato compresso, né un timestamp, né alcun bit di permesso, compreso il bit di esecuzione — così l’entità registra lo stesso digest sia che venga letta da una directory di catalogo sia che venga recuperata da un registry, e su qualsiasi checkout degli stessi file, su qualsiasi sistema. Pattern: ^sha256:[a-f0-9]{64}$.
manifest_digeststringnoDigest del manifest OCI dell’artefatto risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. La firma copre questo digest, e il manifest nomina il digest dei byte pubblicati, rispetto al quale vengono controllati un recupero e una lettura dalla cache prima che l’entità venga confrontata con il proprio digest qui sopra. Presente solo per un’entità risolta da un registry. Pattern: ^sha256:[a-f0-9]{64}$.
referenced_fromstring[]noOrigini nei siti di authoring — percorsi puntati nello YAML di Release / Aggregate / Manifest (ad es. aggregate.spec.components.api.type) che registrano perché questo URI si trova nella chiusura delle dipendenze della Release. Predefinito: []
signatureVerifiedSignaturenoFatto di firma verificata registrato quando la firma di questa entità è stata verificata al momento del pull, rispetto alla policy di fiducia del registry che l’ha risolta.
deprecationDeprecationRecordnoMarcatore di deprecazione retroattivo verificato, registrato quando al momento del pull è stato scoperto su questo artefatto un marcatore di deprecazione firmato e attendibile. Un marcatore è un referrer OCI firmato dell’artefatto che depreca, allegato dopo la pubblicazione senza ripubblicare l’artefatto. Registra la severità e il messaggio del marcatore più il firmatario verificato che lo ha creato. La build legge questo fatto e applica la politica di deprecazione basandosi solo sul file di lock; non riscopre né riverifica mai il marcatore.

Non sono consentite proprietà aggiuntive.

lockfile.mutators[]

ProprietàTipoObbligatoriaDescrizione
pluginstringsìCoordinata risolta del plugin con ruolo di trasformazione — l’identità <pluginType>/<name> di un’entità Plugin (ad es. governance/tag-injector). Si collega per identità alle sezioni plugins e entities per il digest fissato e l’insieme delle versioni.
rolestring (enum)sìIl ruolo di trasformazione a cui è legata questa associazione, registrato testualmente dalla voce plugins.governance scritta dall’autore, così una build esegue l’associazione esattamente in quel ruolo anziché dedurne uno: label-transform riscrive le etichette dei nodi durante la costruzione della topologia; annotation-transform inietta annotazioni prima dell’espansione, durante la risoluzione. Valori consentiti: "label-transform", "annotation-transform"
functionstringnoOverride dell’esportazione che l’associazione nomina. Se assente, viene selezionata l’esportazione predefinita del ruolo (mutate per label-transform, transform_annotations per annotation-transform).
settingsobjectnoOggetto di impostazioni in forma libera dichiarato dall’associazione, fissato così come è stato scritto e passato al plugin testualmente. La build legge le impostazioni da qui — mai dalla configurazione attiva — così una modifica delle impostazioni successiva al pull non sposta l’output della build. Assente quando l’associazione non ne dichiara.
sourcesobject[]noFissaggi indirizzati per contenuto dei file sorgente dichiarati dall’associazione, in ordine di nome base. La build ricostruisce la sorgente che il plugin legge dal contenuto registrato di ciascun fissaggio anziché da una lettura dal vivo sull’host, così l’output della build resta invariante rispetto a una modifica del file sorgente successiva al pull. Assente quando l’associazione non ne dichiara.

Non sono consentite proprietà aggiuntive.

lockfile.mutators[].sources[]
ProprietàTipoObbligatoriaDescrizione
contentstringsìIl contenuto del file sorgente, portato testualmente così che la build ricostruisca dal file di lock l’input sorgente del plugin.
digeststringsìL’indirizzo di contenuto del contenuto registrato, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Un nuovo pull confronta il file sottostante con questo digest per rilevare la deriva. Pattern: ^sha256:[a-f0-9]{64}$.
pathstringsìIl nome base del file sorgente — mai un percorso assoluto dell’host, così il fissaggio è portabile e deterministico.

Non sono consentite proprietà aggiuntive.

lockfile.plugins[]

ProprietàTipoObbligatoriaDescrizione
uristringsìIdentità semplice dell’artefatto .wasm del plugin Wasm — il percorso <pluginType>/<name> (ad es. governance/aggrega-security-baseline). Il primo segmento è il tipo del plugin (provider, linter, pipeline-step, governance, cli, parser, importer); il segmento successivo è il nome del plugin. Tipo e nome insieme formano l’identità del plugin — lo stesso nome sotto due tipi corrisponde a due plugin. La posizione fisica di recupero è derivata da questa identità più il registry configurato, e non è mai portata nel file di lock.
resolved_versionstringsìIl digest del contenuto in cui si è risolto l’artefatto Wasm, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Un artefatto di plugin è indirizzato per contenuto anziché nominato per versione — un .wasm viaggia inline nel manifest del suo plugin ed è fissato dal digest dei suoi byte — quindi questo campo registra quel digest, che è anche il digest qui sotto. Costruisce lo slot della cache da cui la build rilegge l’artefatto, quindi non contiene /, \ né .., che la forma sha256: esclude già. Pattern: ^sha256:[a-f0-9]{64}$.
digeststringsìDigest del contenuto dell’artefatto Wasm risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli — la forma in cui l’indirizzo di contenuto è scritto ovunque venga confrontato. Pattern: ^sha256:[a-f0-9]{64}$.
manifest_digeststringnoDigest del manifest OCI dell’artefatto Wasm risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. La firma copre questo digest; il digest del contenuto qui sopra è l’identità portabile usata per il fissaggio nella cache e per il controllo di integrità. Presente solo per un artefatto risolto da un registry. Pattern: ^sha256:[a-f0-9]{64}$.
referenced_fromstring[]noPerché questo artefatto si trova nella chiusura delle dipendenze della Release: il riferimento di ciascuna entità Plugin attraverso cui è stato raggiunto, così come la sezione entities registra quell’entità (ad es. governance/label-injector:1.0.0). Predefinito: []
signatureVerifiedSignaturenoFatto di firma verificata registrato quando la firma di questo plugin è stata verificata al momento del pull, rispetto alla stessa policy di fiducia per registry usata per le entità di catalogo.
deprecationDeprecationRecordnoMarcatore di deprecazione retroattivo verificato, registrato quando al momento del pull è stato scoperto su questo artefatto un marcatore di deprecazione firmato e attendibile. Un marcatore è un referrer OCI firmato dell’artefatto che depreca, allegato dopo la pubblicazione senza ripubblicare l’artefatto. Registra la severità e il messaggio del marcatore più il firmatario verificato che lo ha creato. La build legge questo fatto e applica la politica di deprecazione basandosi solo sul file di lock; non riscopre né riverifica mai il marcatore.

Non sono consentite proprietà aggiuntive.

lockfile.providers[]

ProprietàTipoObbligatoriaDescrizione
capabilitystringsìLa capacità per cui questo legame seleziona un provider — il nome semplice della capacità che una Recipe lega tramite spec.capability (ad es. helm, compose).
pluginstringsìIdentità semplice del plugin di rendering del provider risolto (l’identità dell’entità Plugin, cioè i suoi metadata.pluginType e metadata.name uniti da una barra, ad es. provider/helm). Si collega per identità alle sezioni plugins e entities per il digest fissato e l’insieme delle versioni.

Non sono consentite proprietà aggiuntive.

lockfile.release_documents[]

ProprietàTipoObbligatoriaDescrizione
digeststringsìIl digest del contenuto dei byte del file di Release nel momento in cui la risoluzione li ha letti, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Pattern: ^sha256:[a-f0-9]{64}$.
pathstringsìIl percorso del file di Release relativo alla directory che contiene la Release a cui appartiene questo file di lock, con barre normali (ad es. release-prod.yaml, ../shared/base-release.yaml) — mai un percorso assoluto dell’host, così la voce è portabile e deterministica.

Non sono consentite proprietà aggiuntive.

lockfile.toolchain

Versioni della toolchain che ha prodotto questo file di lock: la versione propria del compilatore e la versione di ciascun plugin core che il compilatore porta con sé. Registrate affinché un file di lock risponda a posteriori su quale compilatore e quali plugin core hanno risolto e renderizzato una build — una domanda a cui le sezioni fissate non sempre possono rispondere, perché un plugin di provider core servito dall’interno del binario del compilatore viene lasciato senza fissaggio e quindi non porta alcuna versione registrata propria. Solo versioni: il timbro non registra mai da dove provengono i byte di un plugin, quindi due macchine che hanno fissato la stessa chiusura delle dipendenze con lo stesso compilatore scrivono lo stesso timbro. Nulla confronta questa sezione, avvisa a suo riguardo o rifiuta una build a causa sua, e la sua assenza da un file di lock è silenziosa: la toolchain non fa parte della chiusura delle dipendenze che il file di lock fissa. Per lo stesso motivo la sezione è esclusa dal confronto di identità byte per byte tra due pull degli stessi input, alla pari di generated_at.

ProprietàTipoObbligatoriaDescrizione
compiler_versionstringsìVersione del compilatore che ha scritto questo file di lock, nella forma senza v che riporta ogni superficie di Aggrega (1.2.0, non v1.2.0). Una build con il timbro di una versione registra quella versione — una build di release taggata il proprio tag — e una build priva di timbro di versione registra il marcatore (devel), così un file di lock prodotto da un compilatore senza timbro non viene scambiato per output di release. Registrata come un singolo segmento di percorso, quindi non contiene /, \ né ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
core_pluginsobject[]sìVersione di ciascun plugin core che il compilatore porta con sé, una voce per plugin, ordinate per coordinata del plugin. Un plugin core è pubblicato sul tag proprio del compilatore alla stessa versione, quindi queste versioni risultano uguali sia che il compilatore abbia servito un plugin dal proprio interno sia che lo abbia recuperato da un registry — ed è questo che mantiene il timbro privo di dettagli specifici della macchina. Vuoto per una build che non porta alcun plugin core. Predefinito: []

Non sono consentite proprietà aggiuntive.

lockfile.toolchain.core_plugins[]
ProprietàTipoObbligatoriaDescrizione
pluginstringsìCoordinata del plugin core — l’identità <pluginType>/<name> di un’entità Plugin (ad es. provider/helm), la stessa identità con cui le sezioni providers e mutators nominano un plugin.
versionstringsìVersione di questo plugin core, nella forma senza v che riporta ogni superficie di Aggrega. Registrata come un singolo segmento di percorso, quindi non contiene /, \ né ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.

Non sono consentite proprietà aggiuntive.

lockfile.verdict_inputs[]

ProprietàTipoObbligatoriaDescrizione
pluginstringsìL’URI del plugin scritto dall’autore per l’associazione di verdetto, così come è scritto in .aggrega-config.yaml plugins.governance (ad es. governance/aggrega-security-baseline:1.0.0). Identifica a quale associazione appartengono gli input delle regole registrati; un plugin di verdetto viene messo in cache anziché fissato, quindi non ha alcuna voce nelle sezioni plugins / entities a cui collegarsi.
rolestring (enum)sìIl ruolo di verdetto a cui è legata questa associazione — ir-verdict (durante l’analisi statica, sul grafo IR) o render-verdict (durante il rendering, sugli artefatti renderizzati). Distingue lo stesso plugin associato in entrambe le fasi di verdetto, ciascuna potenzialmente con i propri input delle regole. Valori consentiti: "ir-verdict", "render-verdict"
sourcesobject[]noDigest del contenuto dei file di input delle regole dichiarati dall’associazione, in ordine di nome base. Assente quando l’associazione non dichiara sorgenti.

Non sono consentite proprietà aggiuntive.

lockfile.verdict_inputs[].sources[]
ProprietàTipoObbligatoriaDescrizione
digeststringsìL’indirizzo di contenuto dei byte del file di input delle regole al momento del pull, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Un nuovo pull lo ricalcola, così un file di regole modificato emerge come diff del file di lock. Pattern: ^sha256:[a-f0-9]{64}$.
pathstringsìIl nome base del file di input delle regole — mai un percorso assoluto dell’host, così la voce è portabile e deterministica.

Non sono consentite proprietà aggiuntive.

Definizioni

DeprecationRecord

Marcatore di deprecazione retroattivo verificato, registrato quando al momento del pull è stato scoperto su questo artefatto un marcatore di deprecazione firmato e attendibile. Un marcatore è un referrer OCI firmato dell’artefatto che depreca, allegato dopo la pubblicazione senza ripubblicare l’artefatto. Registra la severità e il messaggio del marcatore più il firmatario verificato che lo ha creato. La build legge questo fatto e applica la politica di deprecazione basandosi solo sul file di lock; non riscopre né riverifica mai il marcatore.

ProprietàTipoObbligatoriaDescrizione
messagestringsìMessaggio di deprecazione leggibile dall’uomo portato dal marcatore — tipicamente un rimando per la migrazione.
severitystring (enum)sìSeverità del marcatore, ordinata warning < error < retracted. La build si arresta quando questa severità raggiunge o supera la soglia di arresto configurata, ed emette un avviso in caso contrario. Valori consentiti: "warning", "error", "retracted"
signerVerifiedSignaturenoFirmatario verificato del marcatore, registrato nello stesso modo del firmatario della firma di un artefatto: il soggetto/emittente del certificato per la firma keyless, oppure l’impronta della chiave fissata per la firma con chiave. Un marcatore è un artefatto firmato a pieno titolo, quindi il suo firmatario ha la stessa forma della firma di un artefatto — e il bundle_digest qui nomina il bundle della firma proprio del marcatore anziché quello dell’artefatto deprecato.

Non sono consentite proprietà aggiuntive.

ExternalInput

Un singolo input esterno fissato: l’URL richiesto da un rendering, il fissaggio SHA-256 che nomina i suoi byte nell’archivio di input indirizzato per contenuto (sha256/<digest>), la dimensione del payload e la provenienza dei consumatori che lo hanno richiesto. Il fissaggio è autorevole — un URL fissato viene sempre servito dall’archivio, e un nuovo riempimento dell’archivio viene verificato rispetto a questo digest prima che i byte raggiungano un rendering.

ProprietàTipoObbligatoriaDescrizione
required_bystring[]sìProvenienza — i siti di rendering che hanno richiesto questo input. Ordinati e deduplicati dallo scrittore del file di lock.
sha256stringsìFissaggio SHA-256 in esadecimale minuscolo. Per un input https, il digest dei byte del payload; per un input oci, il digest del manifest in cui si è risolto il riferimento. Nomina il blob dell’archivio in sha256/<digest>. Pattern: ^[0-9a-f]{64}$.
sizeintegersìDimensione in byte del payload fissato. Un conteggio di byte non è mai negativo. Minimo: 0.
urlstringsìL’URL dell’input così come è scritto nel sito di rendering — la chiave di ricerca che abbina una richiesta in fase di rendering al suo fissaggio.

Non sono consentite proprietà aggiuntive.

LibraryEntry

Forma comune condivisa dalle voci di schema_libraries, mapping_libraries, workload_libraries e artifact_libraries. L’elenco consumers cattura la relazione nel grafo del catalogo — quale entità di catalogo fa riferimento a quali frammenti <entry-name> di questa libreria — a supporto di diff strutturati dell’impatto quando il digest della libreria cambia. Una libreria è un artefatto OCI come qualsiasi altro, quindi registra gli stessi fatti verificati di un’entità di catalogo: il digest del manifest coperto dalla sua firma, la firma verificata stessa e qualsiasi marcatore di deprecazione retroattivo verificato scoperto al momento del pull.

ProprietàTipoObbligatoriaDescrizione
uristringsìURI canonico dell’entità libreria.
resolved_versionstringsìVersione concreta risolta al momento del pull (selezione della versione minima sul grafo delle dipendenze tra librerie) — la versione propria della libreria. Registrata come un singolo segmento di percorso, perché costruisce lo slot della cache da cui la build rilegge la libreria, quindi non contiene /, \ né ..: un valore che uscisse dalla directory della cache nominerebbe una posizione al di fuori di essa. Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringsìDigest del contenuto dell’artefatto della libreria risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli — la forma in cui l’indirizzo di contenuto è scritto ovunque venga confrontato. Pattern: ^sha256:[a-f0-9]{64}$.
manifest_digeststringnoDigest del manifest OCI dell’artefatto della libreria risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. La firma copre questo digest; il digest del contenuto qui sopra è l’identità portabile usata per il fissaggio nella cache e per il controllo di integrità. Presente solo per una libreria risolta da un registry. Pattern: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignaturenoFatto di firma verificata registrato quando la firma di questa libreria è stata verificata al momento del pull, rispetto alla stessa policy di fiducia per registry usata per le entità di catalogo.
deprecationDeprecationRecordnoMarcatore di deprecazione retroattivo verificato scoperto su questa libreria al momento del pull. La build lo segnala e, dove il workspace ha configurato una soglia di arresto che la severità registrata raggiunge, si arresta — così una libreria ritirata dopo che la versione è stata fissata viene annunciata a ogni build anziché solo alla selezione della versione, che una versione fissata esplicitamente scavalca.
consumersobject[]noRecord di quale entità di catalogo fa riferimento a questa libreria e a quali frammenti <entry-name>. Cattura il fan-in: molti consumatori per libreria, ciascuno dei quali può fare riferimento a molti frammenti. Ogni record porta l’URI del consumatore più l’insieme dei frammenti che quel consumatore include. Predefinito: []

Non sono consentite proprietà aggiuntive.

LibraryEntry.consumers[]

ProprietàTipoObbligatoriaDescrizione
consumer_uristringsìURI canonico dell’entità di catalogo che fa riferimento a questa libreria: un Component o una Feature per una libreria di schemi, una Recipe o una FeatureRecipe per una libreria di mapping, di workload o di artefatti, oppure un’altra libreria dello stesso tipo le cui voci fanno riferimento a questa.
fragmentsstring[]sìInsieme dei frammenti <entry-name> a cui questo consumatore fa riferimento all’interno della libreria (ad es. ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). L’ordine è reso canonico in ordine lessicografico dallo scrittore.

Non sono consentite proprietà aggiuntive.

SourceArtifactEntry

Un singolo fissaggio di artefatto sorgente: l’identità {kind, url, chart, module_subdir, pinned_version}, il digest del contenuto che verifica il pull, il mediatype canonico e i puntatori all’indietro strutturati verso ogni entità di catalogo risolta in questo artefatto. chart e module_subdir sono i due termini selettori — ciascuno nomina ciò che l’URL da solo non nomina, per i tipi che ne hanno bisogno.

ProprietàTipoObbligatoriaDescrizione
kindenumsìIl tipo di sorgente. Determina quale adattatore ha risolto l’artefatto e quale mediatype è atteso. terraform-module-oci appartiene all’insieme, e nessun adattatore di sorgente lo serve: una Recipe o una FeatureRecipe che lo nomina viene rifiutata quando viene letta. Valori consentiti: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci"
urlstringsìL’URL scritto dall’autore — l’URL di identità così come è scritto in spec.source.url della Recipe. Per helm-https-chart è la radice del repository (forma con radice del repository) oppure il .tgz diretto (forma diretta), esattamente come scritto dall’autore; la build ricostruisce questo stesso URL offline, quindi è l’identità stabile su cui è indicizzato il fissaggio. Per git-repository, l’URL del repository clonabile. Per helm-oci-chart, il riferimento al registry. Per compose-https-fragment, l’URL HTTPS del frammento. La posizione risolta dell’artefatto per una sorgente helm con radice del repository è registrata separatamente sotto resolved_url: come provenienza.
chartstringnoIl nome del chart per una sorgente helm con radice del repository (spec.source.chart della Recipe), parte dell’identità {kind, url, chart, module_subdir, pinned_version}, così due chart serviti da un’unica radice del repository alla stessa versione vengono fissati in voci distinte. Assente per una sorgente .tgz diretta, OCI, compose o git, nessuna delle quali seleziona un chart all’interno dell’URL.
module_subdirstringnoLa directory, all’interno di un repository di origine git, che costituisce l’artefatto (spec.source.module_subdir della Recipe), parte dell’identità {kind, url, chart, module_subdir, pinned_version}, così due directory di uno stesso repository allo stesso commit vengono fissate in voci distinte. Assente quando l’intero repository è l’artefatto, e per ogni tipo che raggiunge il proprio artefatto tramite URL anziché scendendo in un clone.
pinned_versionstringsìLa versione concreta fissata al momento del pull. Per i tipi helm-*, la versione del chart. Per git-repository, il commit in cui si è risolto il riferimento scritto dall’autore (NON il riferimento originale di tag/branch — questo è registrato sotto requested_ref: su ciascuna voce referenced_by:, ogni volta che la Recipe ha scritto uno spec.source.ref:). Una build trova questa voce in base a ciò che la Recipe ha scritto: il ref: scritto dall’autore, dove ce n’è uno, confrontato con il requested_ref: registrato, e altrimenti questo valore fissato — così una Recipe che nomina un tag si risolve nel commit a cui quel tag è stato fissato, senza che il commit compaia mai nella Recipe. Registrata come un singolo segmento di percorso, perché costruisce lo slot della cache da cui la build rilegge l’artefatto, quindi non contiene /, \ né ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
resolved_urlstringnoSolo provenienza: la posizione concreta dell’artefatto in cui l’URL scritto dall’autore si è risolto al momento del pull. Per una sorgente helm con radice del repository è l’URL del .tgz diretto in cui l’indice del repository ha risolto chart+versione; è registrato a fini diagnostici e NON fa parte dell’identità dell’artefatto. Assente quando la posizione risolta coincide con l’URL scritto dall’autore (una sorgente .tgz diretta, OCI, compose o git).
digeststringsìDigest del contenuto dell’archivio .tar.gz risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. La verifica in fase di build legge i byte dello slot della cache, ricalcola il digest e lo confronta con questo campo; una mancata corrispondenza arresta la build, segnalando una mancata corrispondenza del digest del contenuto. Pattern: ^sha256:[a-f0-9]{64}$.
manifest_digeststringnoDigest del manifest OCI dell’artefatto risolto, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Il manifest è la radice di fiducia indipendente rispetto alla quale viene verificato l’archivio in cache; il digest del contenuto qui sopra è l’identità portabile usata per il fissaggio nella cache e per il controllo di integrità. Presente solo per una sorgente distribuita tramite OCI (un helm-oci-chart). Pattern: ^sha256:[a-f0-9]{64}$.
mediatypestringsìTipo di media canonico annunciato dal registry (o il valore predefinito del tipo per i tipi senza metadati di registry). Registrato come provenienza diagnostica.
referenced_bySourceArtifactReference[]sìEntità di catalogo risolte in questo artefatto, ordinate per (uri, field) per un output deterministico. Una voce esiste solo perché una Recipe o una FeatureRecipe l’ha acquisita con un pull, quindi l’elenco non è mai vuoto. Almeno 1 voce.

Non sono consentite proprietà aggiuntive.

SourceArtifactReference

Un singolo puntatore all’indietro entità di catalogo → artefatto sorgente. entity + uri insieme identificano l’entità di catalogo; field nomina il percorso lato sorgente all’interno della spec dell’entità in cui l’artefatto è stato dichiarato. Il requested_ref: facoltativo conserva lo spec.source.ref: scritto dall’autore della Recipe, ed è scritto ogni volta che la Recipe ne ha scritto uno (tag/branch di git-repository → SHA del commit).

ProprietàTipoObbligatoriaDescrizione
entityenumsìIl tipo di entità di catalogo che contiene questo puntatore all’indietro. Valori consentiti: "recipe", "feature_recipe"
uristringsìURI canonico della Recipe o della FeatureRecipe (ad es. hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0).
fieldstringsìPercorso lato sorgente all’interno della spec dell’entità in cui l’artefatto è stato dichiarato. Il valore è spec.source.
requested_refstringnoFacoltativo — lo spec.source.ref: scritto dall’autore della Recipe, scritto ogni volta che la Recipe ne ha scritto uno. Per una Recipe git-repository che scrive ref: v1.0.0, questo conserva "v1.0.0" mentre pinned_version: contiene il commit in cui quel riferimento si è risolto. Assente quando la Recipe non scrive alcun ref:, il che vale per ogni tipo il cui resolver fissa testualmente la versione scritta dall’autore (helm-, compose-). Svolge due compiti contemporaneamente, e registrarlo incondizionatamente è ciò che impedisce che si escludano a vicenda. Una build lo usa come chiave di unione per trovare questa voce a partire da una Recipe che nomina il riferimento anziché il commit. E un pull che non è un aggiornamento vincola ogni riferimento registrato alla sua versione fissata: un riferimento che si è spostato sul suo remoto arresta l’esecuzione anziché essere adottato.

Non sono consentite proprietà aggiuntive.

VerifiedSignature

Fatto di firma verificata registrato quando la firma di un artefatto è stata verificata al momento del pull, rispetto alla policy di fiducia del registry che lo ha risolto. Ogni artefatto firmabile lo registra nello stesso modo — un’entità di catalogo, una libreria, un plugin Wasm — perché tutti vengono verificati attraverso un unico percorso anziché uno per tipo. Registra la modalità di verifica, l’identità/emittente keyless che ha trovato corrispondenza (se keyless) e il digest indirizzato per contenuto del bundle della firma nella cache dei contenuti. La build non riesegue la verifica. Prima che qualcosa venga renderizzato, legge questo fatto su ogni voce a partire dalla quale costruisce, in ogni sezione: ricalcola l’hash del bundle in cache e confronta il risultato con bundle_digest, arrestandosi dove il blob manca o differisce; e per una voce servita dalla cache dei contenuti, legge da quel bundle per quale artefatto è stata creata la firma, e si arresta dove è stata creata per un artefatto diverso da quello che la build ha letto per la voce — così una signature copiata da una voce su un’altra viene rifiutata, qualunque cosa dica il requisito di firma. Una build non verifica alcuna firma, quindi un bundle scritto a mano nella cache, intestato all’artefatto proprio della voce, non viene distinto da uno verificato da un pull. E dove la configurazione di fiducia del workspace richiede una firma per una voce servita dalla cache dei contenuti — il requisito che pull applica quando recupera l’artefatto, così le esenzioni e un registry advisory che consentono a un pull di ammettere un artefatto privo di firma consentono anche alla build di ammetterne la voce — una voce che non porta alcun fatto arresta la build. Una voce letta da una directory di catalogo, dalla copia all’interno del binario del compilatore o da accanto alla Release non è mai vincolata a quel requisito.

ProprietàTipoObbligatoriaDescrizione
bundle_digeststringsìDigest SHA-256 del blob del bundle della firma in cache, nella forma sha256: seguito da 64 caratteri esadecimali minuscoli. Nomina il blob della cache, quindi costruisce un percorso e non contiene /, \ né .. — cosa che la forma sha256: esclude già — e su una voce di qualsiasi sezione è ciò rispetto a cui una build confronta l’hash ricalcolato di quel blob. Pattern: ^sha256:[a-f0-9]{64}$.
identitystringnoFirmatario verificato della firma: il soggetto del certificato di firma per una firma keyless, oppure keyed:sha256: seguito dallo SHA-256 del testo PEM della chiave pubblica fissata per una firma con chiave.
issuerstringnoEmittente OIDC verificato per una firma keyless. Vuoto per una firma con chiave.
modestring (enum)sìModalità di verifica che ha ammesso la firma. Valori consentiti: "keyless", "keyed"

Non sono consentite proprietà aggiuntive.