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

Schema della Release di Aggrega

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

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

Consulta il riferimento per l’authoring della Release per una guida in prosa sulla scrittura delle entità Release; questa pagina documenta lo schema strutturale descritto da quel riferimento.

Tipo di primo livello: object

Proprietà

ProprietàTipoObbligatoriaDescrizione
apiVersionconst “aggrega.ai/v1beta1”sìCostante: "aggrega.ai/v1beta1"
kindconst “Release”sìCostante: "Release"
metadataobjectsì
specobjectsìCiò che la Release lega e instrada: l’Aggregate e il Manifest che distribuisce (oppure una base extends), l’adempimento dei parametri specifico dell’ambiente e i confini verso cui vengono instradati i suoi componenti.

Non sono consentite proprietà aggiuntive.

release.metadata

ProprietàTipoObbligatoriaDescrizione
namestringsìLungo almeno 1 carattere.
environmentstringsì
versionstringsìVersionamento semantico rigoroso della release (ad es. 1.0.0). Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringnoChe cos’è questa entità e a che cosa serve, scritto per chi sta decidendo se usarla. Apri con una frase che nomina la cosa, poi aggiungi ciò di cui un lettore ha bisogno per sceglierla e usarla correttamente — che cosa si aspetta dalla piattaforma su cui distribuisce, e qualsiasi aspetto sorprendente del suo comportamento. Un breve paragrafo è la lunghezza abituale.
maintainersobject[]noElenco dei manutentori responsabili di questa entità.
licensestringnoIdentificatore SPDX della licenza del software descritto da questa entità, come MIT o AGPL-3.0. Registra le condizioni di quel software, non le condizioni di questo file.
repositorystringnoL’URL del repository Git in cui risiedono i file sorgente.
homestringnoL’URL della home page, del wiki o della documentazione di questa entità.
keywordsstring[]noUn elenco di parole chiave descrittive per la reperibilità nell’interfaccia utente.

Non sono consentite proprietà aggiuntive.

release.metadata.maintainers[]
ProprietàTipoObbligatoriaDescrizione
namestringsì
emailstringno
urlstringno

Non sono consentite proprietà aggiuntive.

release.spec

Ciò che la Release lega e instrada: l’Aggregate e il Manifest che distribuisce (oppure una base extends), l’adempimento dei parametri specifico dell’ambiente e i confini verso cui vengono instradati i suoi componenti.

ProprietàTipoObbligatoriaDescrizione
aggregatestringnoRiferimento all’Aggregate (intento dello sviluppatore) che questa release distribuisce. Un token semplice si risolve per identità — il metadata.name dell’Aggregate referenziato, cercato nella directory propria della Release e poi nel catalogo. Un valore che inizia con ’./’ o ’../’ è un file locale esplicito risolto in modo relativo alla Release (ad es. ’../shared/app.yaml’ per condividere un solo Aggregate tra varianti della release in una sottodirectory).
manifeststringnoRiferimento al Manifest che risolve le interfacce astratte rispetto a cui questa release distribuisce. Un token semplice si risolve per identità — il metadata.name del Manifest referenziato, cercato nella directory propria della Release. Un valore che inizia con ’./’ o ’../’ è un file locale esplicito risolto in modo relativo alla Release. Un Manifest appartiene al lato distribuzione e non è indicizzato nel catalogo, quindi si risolve solo dalla directory della Release o da un percorso esplicito.
extendsstringnoRiferimento a una Release di base la cui superficie di authoring questa Release eredita — il suo albero dei confini con l’infra per componente e le associazioni di Feature al di sotto, i suoi parametri, le sue annotazioni e il suo puntatore al Manifest. Il valore è un percorso a un file accanto a questa Release, che inizia con ’./’ o ’../’; un nome semplice e una coordinata di registry vengono entrambi rifiutati, perché una Release appartiene al lato distribuzione e non è indicizzata nel catalogo. Ciò che viene ereditato può essere sostituito chiave per chiave, fino al primo valore indivisibile — uno scalare, una lista, un template — che viene sostituito per intero; una chiave scritta come null rimuove ciò che era stato ereditato. Nessun campo dei metadati viene trasmesso, quindi un figlio porta il proprio nome, la propria versione e il proprio ambiente. Dichiarare ‘aggregate’ accanto a ‘extends’ viene rifiutato da questo schema, quindi un figlio distribuisce lo stesso intento dello sviluppatore della sua base; ‘manifest’ resta opzionale e può essere sostituito per cambiare il file di lock delle dipendenze.
parametersobjectnoContratto di adempimento delle variabili specifico dell’ambiente con due modalità di authoring tramite smistamento in base alla forma del contenuto. Modalità 1 (inline): una mappa YAML che porta direttamente valori di parametri annidati strutturati. Modalità 2 (importazione da file): una mappa YAML con esattamente una chiave, $import: ./relative/path.yaml, che punta a un unico file locale che fornisce i valori dei parametri. Una sola sorgente in questo punto — la stratificazione su più file è competenza delle catene extends: della Release (la Release genitore fornisce i parametri di base; il figlio estende + sovrascrive).
boundariesmappa di boundarynoI contenitori logici radice in cui vengono instradati i componenti dell’Aggregate. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
componentsmappa di boundary_componentnoIstanze di componente di primo livello che portano l’infra per componente dell’operatore, per una Release con un unico ambito e senza confini con nome. Mutuamente esclusivo con boundaries: dichiara components per una Release piatta oppure boundaries per un instradamento verso più destinazioni, mai entrambi. Quando si usa components, il compilatore sintetizza un confine default che li contiene ed emette i loro artefatti in modo piatto in dist/. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.

Non sono consentite proprietà aggiuntive.

Definizioni

boundary_component

Un’istanza di componente instradata in un confine, con dimensionamento fisico e associazioni di funzionalità opzionali.

ProprietàTipoObbligatoriaDescrizione
descriptionstringnoDocumentazione opzionale che descrive il ruolo di questo componente in questo confine della Release.
subDirectorystringnoSostituzione del sotto-percorso a livello di Component, aggiunta in coda alla directory del confine genitore. Se omesso o vuoto sia sul confine sia sul componente, vale ’{{ .capability }}’ per impostazione predefinita; una stringa vuota scritta qui viene letta come omessa. Imposta ’.’, oppure un template che si valuta in una stringa vuota, per disattivare la generazione delle sottodirectory.
annotationsmappa di string o object o nullnoAnnotazioni dell’Operatore specifiche del Component che sovrascrivono, per questo componente, le annotazioni a livello di confine. Unite in profondità sopra le annotazioni del confine (il componente prevale in caso di collisione di chiavi; i valori strutturati si uniscono per sottochiave con genitori strutturati). I valori sono stringhe, oggetti strutturati oppure null. Usate per le sostituzioni per componente delle annotazioni ben note del provider (ad es. aggrega.ai/namespace sul provider helm). Un null esplicito su una chiave ereditata dal confine genitore rimuove il legame ereditato da questo componente (rinuncia a una Feature guidata da annotazioni); i componenti fratelli mantengono il legame ereditato.
infraobjectnoDimensionamento fisico strettamente locale a questo componente (ad es. repliche, IOPS del disco).
featuresmappa di objectnoLe Features associate a questo componente tramite la Release. Per le funzionalità dichiarate anche nell’Aggregate viene fornito solo infra (i values provengono dall’Aggregate). Per le funzionalità solo della Release (iniettate dall’Operatore), type è obbligatorio. Le chiavi sono nomi di istanza di funzionalità e possono portare l’URI completo del tipo di funzionalità (punti e barre consentiti). La Release NON DEVE fornire values per le funzionalità — questo è il dominio dello Sviluppatore. Chiavi: una o più lettere, cifre, trattini bassi, punti, barre o trattini. Pattern: ^[a-zA-Z0-9_./-]+$.
usesrelease_uses_blocknoSuperficie degli archi dell’Operatore. All’interno dei socket dichiarati dall’Architetto la Release può collegare un socket dichiarato ma non legato a un componente esistente (target) e/o fornire infra per arco. Nessun values (vale il divieto di values: della Release) e nessuna creazione di risorse di calcolo; reindirizzare un arco dichiarato dallo sviluppatore provoca un arresto in fase di build.

Non sono consentite proprietà aggiuntive.

release_uses_block

Superficie uses per arco scritta nella Release, indicizzata per socket e poi per alias (rispecchia la forma della topologia uses dell’Aggregate). Ogni connessione può impostare target (per creare un arco verso un socket dichiarato ma non legato, che punta a un componente esistente), infra (configurazione per arco dell’operatore, convalidata rispetto all’infraSchema del socket quando la Release viene risolta) e features (associazioni che riempiono gli slot dichiarati dal socket), in qualsiasi combinazione. values è vietato (il divieto di values: della Release); reindirizzare un arco dichiarato dallo sviluppatore è una protezione ben visibile in fase di build.

Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.

I valori sono map of object.

Nessun’altra chiave è consentita.

release_connection_attachment

Un’associazione portata da una voce di connessione della Release: la Feature che riempie uno slot dichiarato dal socket della connessione, con il dimensionamento dell’operatore per essa.

ProprietàTipoObbligatoriaDescrizione
typestringnoL’URI della Feature. Obbligatorio per un’associazione che solo la Release effettua. Deve corrispondere al type dell’Aggregate se entrambi lo dichiarano.
descriptionstringnoDocumentazione opzionale che spiega perché l’Operatore ha associato questa funzionalità alla connessione.
infraobjectnoDimensionamento operativo per questa associazione, convalidato dalla dichiarazione dello schema della Feature.

Non sono consentite proprietà aggiuntive.

aggregate_routing

Instrada in questo confine i componenti interni di un sotto-modulo Aggregate annidato. Rispecchia la struttura component/aggregate del confine per la composizione ricorsiva.

ProprietàTipoObbligatoriaDescrizione
componentsmappa di boundary_componentnoIstanze di Component all’interno dell’aggregato annidato da instradare in questo confine. Le chiavi sono il nome locale che ciascun componente porta all’interno di quel sotto-modulo — ‘main-db’ per il componente che la mappa components propria di un confine indirizza come ‘data.main-db’ — perché è l’unico nome che ha lì. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
aggregatesmappa di aggregate_routingnoUlteriori aggregati annidati all’interno di questo sotto-aggregato (per la composizione di moduli profondamente annidati). Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.

Non sono consentite proprietà aggiuntive.

boundary

ProprietàTipoObbligatoriaDescrizione
descriptionstringnoDocumentazione opzionale che descrive lo scopo e la destinazione fisica di questo confine (ad es. ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’).
directorystringnoPercorso di output fisico per la generazione degli artefatti GitOps. Supporta variabili di template Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Combinato con subDirectory tramite un’unione di percorsi per produrre il percorso finale dell’artefatto.
subDirectorystringnoSotto-percorso a livello di confine aggiunto in coda a directory. Se omesso o vuoto sia sul confine sia sul componente, vale ’{{ .capability }}’ per impostazione predefinita, per il partizionamento automatico CI/CD; una stringa vuota scritta qui viene letta come omessa. Imposta ’.’, oppure un template che si valuta in una stringa vuota, per disattivarlo.
syncWaveintegernoOndata di distribuzione opzionale per confine (intero con segno, predefinito 0). Ogni componente in questo confine eredita nel proprio nodo l’ondata del confine. Sono consentiti valori negativi (eseguiti prima di tutto il resto); i valori più alti vengono eseguiti dopo quelli più bassi. Su K8s e Helm l’ondata è ciò che ordina la distribuzione: diventa un’annotazione argocd.argoproj.io/sync-wave, e su una risorsa che il chart contrassegna già come hook di Helm diventa anche l’helm.sh/hook-weight di quell’hook. Su compose l’ondata viene sia registrata come etichetta del servizio sia usata per ordinare i servizi del file in cui viene renderizzata, tramite depends_on tra di essi — quindi raggiunge ogni servizio di quell’unico file e nulla al di fuori di esso. Su cloudformation l’ondata ordina il provisioning dello stack in cui il confine viene assemblato: ogni risorsa di un’ondata viene dichiarata dipendente dalle risorse dell’ondata precedente, il che fissa l’ordine in cui vengono create e, al contrario, l’ordine in cui vengono eliminate. Si tratta solo dell’ordine di creazione e di eliminazione — un template di stack non esprime alcuna nozione di risorsa pronta, quindi nulla attende che una risorsa diventi utilizzabile. Su terraform l’ondata ordina i blocchi module della configurazione radice in cui il confine viene assemblato: ogni modulo di un’ondata viene dichiarato dipendente dai moduli dell’ondata precedente, il che fissa l’ordine in cui il motore esegue le sue azioni. Si tratta solo dell’ordine delle azioni — una configurazione non esprime alcuna nozione di risorsa pronta, quindi nulla attende che una risorsa diventi utilizzabile — e il valore viene anche registrato con la provenienza di build del nodo. Il compilatore porta lo stesso valore su ogni nodo del confine come sync_wave di quel nodo, dove il comportamento per destinazione è descritto di nuovo dal lato del nodo. I confini annidati non ereditano implicitamente — ciascuno dichiara la propria ondata.
annotationsmappa di string o object o nullnoAnnotazioni dell’Operatore valide per l’intero confine, che scendono in cascata fino al contenitore .context.annotations.release. I valori sono stringhe, oggetti strutturati oppure null. Un valore strutturato porta una configurazione per sottochiave che si unisce in profondità con i genitori strutturati (per sottochiave, prevale il figlio) e fluisce attraverso l’espansione delle Feature guidata da annotazioni; nel contesto di rendering emergono solo i valori scalari. Un null esplicito su una chiave ereditata da un confine genitore rimuove il legame ereditato dall’insieme effettivo di annotazioni di questo confine (rinuncia a una Feature guidata da annotazioni), propagandosi a ogni componente instradato in questo confine, a meno che una sostituzione più profonda non reintroduca il legame.
featuresmappa di objectnoFunzionalità valide per l’intero confine applicate a tutti i componenti annidati (ad es. una mesh di sicurezza predefinita). Il blocco uses di una funzionalità si proietta su ogni componente del confine, dichiarando una dipendenza condivisa una sola volta sul confine anziché ripeterla su ciascun componente. Le chiavi sono nomi di istanza di funzionalità e possono portare l’URI completo del tipo di funzionalità (punti e barre consentiti). Chiavi: una o più lettere, cifre, trattini bassi, punti, barre o trattini. Pattern: ^[a-zA-Z0-9_./-]+$.
boundariesmappa di boundarynoConfini logici annidati (ad es. namespace all’interno di un cluster). Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
componentsmappa di boundary_componentnoQuali componenti dell’Aggregate vengono collocati in questo confine. Le chiavi sono nomi di istanza di componente; il componente di un sotto-aggregato si indirizza tramite il suo percorso qualificato con punti (ad es. ‘data.main-db’ — il nome dell’istanza di aggregato, un punto, il nome del componente). Chiavi: una o più lettere, cifre, trattini bassi, punti o trattini. Pattern: ^[a-zA-Z0-9_.-]+$.
aggregatesmappa di aggregate_routingnoInstrada in questo confine i componenti dei sotto-moduli Aggregate annidati. Le chiavi sono nomi di istanza di aggregato che corrispondono alla mappa spec.aggregates dell’Aggregate. Tutte le istanze di aggregato devono essere collocate in esattamente un confine, se sono definiti dei confini. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.

Non sono consentite proprietà aggiuntive.

uses_block

La topologia strutturale - di proprietà dello Sviluppatore. Dichiara gli archi di rete logici e le dipendenze.

Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.

I valori sono string[] or map of object.

Nessun’altra chiave è consentita.

inject_block

Instradamento agnostico dell’iniezione su una connessione. Associa variabili locali alle chiavi provides della destinazione. Ogni meccanismo di consegna (env, file, arg o personalizzato) è scritto come array di voci {in, from} — ‘from’ esplicito per i riferimenti a provides. Un meccanismo personalizzato può avere qualsiasi nome tranne all: un template legge tutti i meccanismi uniti in un’unica vista in .context.inject.all, quindi un meccanismo con quel nome ne verrebbe nascosto, e nominarne uno arresta la build.

ProprietàTipoObbligatoriaDescrizione
envinject_deliverynoUn singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’. Su una Release ogni voce si trova su una connessione, quindi ‘from’ si risolve rispetto ai provides della destinazione e una voce che porta ‘value’ viene rifiutata.
fileinject_deliverynoUn singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’. Su una Release ogni voce si trova su una connessione, quindi ‘from’ si risolve rispetto ai provides della destinazione e una voce che porta ‘value’ viene rifiutata.
arginject_deliverynoUn singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’. Su una Release ogni voce si trova su una connessione, quindi ‘from’ si risolve rispetto ai provides della destinazione e una voce che porta ‘value’ viene rifiutata.

inject_delivery

Un singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’. Su una Release ogni voce si trova su una connessione, quindi ‘from’ si risolve rispetto ai provides della destinazione e una voce che porta ‘value’ viene rifiutata.

Tipo: object[]