Schema della base infrastrutturale di Aggrega (FeatureRecipe)
Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.
Id dello schema: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
Definizioni scritte da Ops che mappano una Feature astratta del catalogo su un’implementazione concreta e versionata per una capacità di provider. Rigorosamente 1:1 con un provider fisico e una funzionalità del catalogo.
Consulta il riferimento per l’authoring della FeatureRecipe per una guida in prosa sulla scrittura delle entità FeatureRecipe; questa pagina documenta lo schema strutturale descritto da quel riferimento.
Tipo di primo livello: object
Proprietà
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sì | Costante: "aggrega.ai/v1beta1" |
kind | const “FeatureRecipe” | sì | Costante: "FeatureRecipe" |
metadata | object | sì | |
spec | object | sì | Il legame alla capacità del provider, la mappatura, la pipeline e la mappatura di iniezione di una FeatureRecipe. Porta gli stessi tre tipi di input di una Recipe (con sorgente, sintetizzato, artifacts) più l’injectMapping esclusivo della FeatureRecipe; una FeatureRecipe di solo cablaggio che dichiara soltanto capability e implements è valida e non renderizza nulla. |
Non sono consentite proprietà aggiuntive.
featurerecipe.metadata
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | Lungo almeno 1 carattere. |
version | string | sì | Versionamento semantico rigoroso della FeatureRecipe (ad es. 1.2.5). 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-]+)*))?$. |
description | string | no | Che 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 Release che la distribuisce, e qualsiasi aspetto sorprendente del suo comportamento. Un breve paragrafo è la lunghezza abituale. |
maintainers | object[] | no | Elenco dei manutentori responsabili di questa entità. |
license | string | no | Identificatore 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. |
repository | string | no | L’URL del repository Git in cui risiedono i file sorgente. |
home | string | no | L’URL della home page, del wiki o della documentazione di questa entità. |
keywords | string[] | no | Un elenco di parole chiave descrittive per la reperibilità nell’interfaccia utente. |
Non sono consentite proprietà aggiuntive.
featurerecipe.metadata.maintainers[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | |
email | string | no | |
url | string | no |
Non sono consentite proprietà aggiuntive.
featurerecipe.spec
Il legame alla capacità del provider, la mappatura, la pipeline e la mappatura di iniezione di una FeatureRecipe. Porta gli stessi tre tipi di input di una Recipe (con sorgente, sintetizzato, artifacts) più l’injectMapping esclusivo della FeatureRecipe; una FeatureRecipe di solo cablaggio che dichiara soltanto capability e implements è valida e non renderizza nulla.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
capability | string | sì | La capacità esplicita del provider a cui questa ricetta si lega (ad es. ‘helm’, ‘terraform’, ‘compose’) — il tipo di provider che la renderizza. |
implements | string | sì | Dichiara quale tipo di Feature del catalogo questa ricetta è in grado di implementare (incluse le Features di credenziali etichettate feature.aggrega.ai/kind: secret; versione esatta, intervallo compatibile con la major ’^’ o senza versione). Il compilatore lo usa per verificare le mappature del Manifest e per suggerire candidati nelle diagnostiche e nel completamento dell’editor; non risolve mai una build. La mappatura del Manifest è la scelta esplicita di implementazione dell’utente, fissata nel file di lock della Release. |
locals | mappa di string | no | Lo stato privato di Ops. Risultati di calcolo interni disponibili solo all’interno dei template di questa FeatureRecipe come ‘.locals.*’. Ogni voce è essa stessa un template Go, valutato rispetto a un contesto autonomo: ‘.context.instance_id’ (il COMPONENTE HOST per cui questa associazione viene risolta, che è ciò che quel riferimento denota su ogni superficie di template), ‘.attachment_name’ (l’istanza di associazione in corso di risoluzione, e l’unica via per arrivare a quel nome da un local), i ‘.values’ e ‘.infra’ propri dell’associazione, e le voci di questo stesso blocco risolte fino a quel momento. Le voci si risolvono nell’ordine in cui sono scritte, e una voce PUÒ leggere una voce sorella definita SOPRA di essa, ricevendo il valore risolto di quella voce anziché il testo del suo template. L’ordine dell’autore fa parte del contratto ovunque una voce ne legga un’altra: spostare una definizione sotto la voce che la legge rompe la build, e il blocco non viene mai riordinato per far risolvere un riferimento. Un riferimento ‘.locals. |
provides | mappa di string | no | L’API pubblica dello Sviluppatore. Variabili di output contrattuali disponibili per la risoluzione dell’inject del Chiamante a valle. Quando executionScope è boundary, i provides vengono valutati una volta per l’associazione al confine, rispetto al contesto di template con ambito boundary, e ogni componente raggiunto dall’associazione legge quell’unica valutazione in ‘.features. |
source | string o object | no | Percorso facoltativo del codice di infrastruttura. Accetta una stringa URI o un oggetto strutturato aperto. Se fornito insieme a valuesMapping, il compilatore lo renderizza, e i documenti renderizzati si uniscono all’output della FeatureRecipe prima che vengano eseguiti i passi della sua pipeline. |
valuesMapping | string o object | no | Contenuto della mappatura dei values con tre modalità di authoring tramite smistamento in base alla forma del contenuto. Modalità 1 (inline): uno scalare stringa di template Go che produce il formato dei values atteso dal provider. Modalità 2 (importazione da file): una mappa YAML con esattamente una chiave, $import: ./relative/path.tmpl, che punta a un file di template Go locale. Modalità 3 (importazione da libreria): una mappa YAML con esattamente una chiave, $import: <Library>#/mappings/<entry>, che fa riferimento a una voce di una MappingLibrary per identità di nome semplice (la versione è fornita dal file di lock per Release; nessun host di registry compare nel riferimento). Nella forma a oggetto, $import non deve corrispondere a ^oci://; un valore che vi corrisponde viene rifiutato. |
workload | string o object | no | Produttore di YAML di Workload con tre modalità di authoring tramite smistamento in base alla forma del contenuto. Modalità 1 (inline): uno scalare stringa di template Go il cui output viene analizzato come ‘aggrega.ai/v1beta1 Workload’. Modalità 2 (importazione da file): una mappa YAML con esattamente una chiave, $import: ./relative/path.yaml, che punta a un file di template Go locale. Modalità 3 (importazione da libreria): una mappa YAML con esattamente una chiave, $import: <Library>#/workloads/<entry>, che fa riferimento a una voce di una WorkloadLibrary per identità di nome semplice (la versione è fornita dal file di lock per Release; nessun host di registry compare nel riferimento). Il Provider di destinazione deve supportare la sintesi dei carichi di lavoro; il catalogo della libreria standard dichiara workloadSchema su tali provider come contratto documentato. Una FeatureRecipe con workload: legata a un provider che non può eseguire la sintesi provoca un arresto esplicito in fase di rendering. Un carico di lavoro sintetizzato di una FeatureRecipe emette i propri manifest nativi del provider nella directory di output della funzionalità. Nella forma a oggetto, $import non deve corrispondere a ^oci://; un valore che vi corrisponde viene rifiutato. |
artifacts | mappa di string o object | no | Mappa dal nome della voce all’authoring del contenuto dell’artefatto. Il valore di ogni voce porta una di tre modalità tramite smistamento in base alla forma del contenuto. Modalità 1 (inline): uno scalare stringa di template Go il cui output è il corpo dell’artefatto. Modalità 2 (importazione da file): una mappa YAML con esattamente una chiave, $import: ./relative/path.yaml, che punta a un file di template Go locale. Modalità 3 (importazione da libreria): una mappa YAML con esattamente una chiave, $import: <Library>#/artifacts/<entry>, che fa riferimento a un bundle di una ArtifactLibrary per identità di nome semplice (la versione è fornita dal file di lock per Release; nessun host di registry compare nel riferimento). Un bundle si espande in un output per file, ciascuno annidato sotto la chiave della voce come <key>/<filename>. La chiave nomina l’output della voce: la chiave di una voce in modalità 1 o 2 è il nome del suo file di output, usato così come è scritto, e il file importato da una voce in modalità 2 fornisce il contenuto senza nominare l’output, quindi due voci che importano file diversi con lo stesso nome sono due output distinti. Le risorse ausiliarie che una FeatureRecipe che genera risorse emette (ConfigMap, ServiceMonitor, NetworkPolicy, CRD ExternalSecret, ecc.) hanno la forma di artefatti; artifacts: è il meccanismo principale di generazione delle risorse. Le collisioni tra voci di artefatti, file di bundle, output della sorgente e sintesi del carico di lavoro arrestano la build quando il nodo viene renderizzato. Il blocco artifacts si scrive in modo identico su una Recipe e su una FeatureRecipe — le stesse tre modalità, la stessa regola chiave-output e lo stesso comportamento in caso di collisione — ed è per questo che quella parte di questa descrizione si legge allo stesso modo su entrambi i tipi; un esempio scritto per uno si trasferisce all’altro senza modifiche. Nella forma a oggetto, $import non deve corrispondere a ^oci://; un valore che vi corrisponde viene rifiutato. Chiavi: la chiave nomina l’output della voce, quindi è limitata a un singolo nome di file: inizia con una lettera o una cifra e prosegue con lettere, cifre, punti, trattini o trattini bassi. I punti dopo il primo carattere mantengono le estensioni che le chiavi degli artefatti portano (main.tf, template.yaml, serviceaccount.yaml). Un / farebbe nominare a una chiave un percorso anziché un file, e un . iniziale ammetterebbe .., che nomina una posizione al di fuori della directory di output — la classe del primo carattere li rifiuta entrambi. Per un’importazione da libreria la chiave nomina la directory sotto cui sono annidati i file del bundle, quindi vale lo stesso limite. Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | no | Che cosa escludere da ciò che la sorgente di questa FeatureRecipe renderizza — per una sorgente presa così com’è che renderizza qualcosa che la Release non deve distribuire: un documento che un chart scaricato renderizza, come un Secret che contiene una chiave che il chart genera da capo a ogni rendering, un servizio, un volume o una configurazione che un file compose scaricato include, oppure una risorsa che un template CloudFormation scaricato dichiara. La maggior parte delle FeatureRecipes non ne ha mai bisogno. Ogni voce nomina un’unità che la sorgente renderizza tramite il suo tipo, il suo nome e, dove la voce li fornisce, il suo namespace e il sotto-chart da cui proviene, ciascuno nel vocabolario del provider che renderizza la sorgente — per un chart, un documento tramite il suo kind e il suo metadata.name; per un file compose, un service, un volume o un config tramite la sua chiave sotto services:, volumes: o configs:; per un template CloudFormation, una risorsa tramite il suo Type e il suo ID logico. Quel provider esclude ogni unità a cui una voce corrisponde, e ciò a cui una voce corrisponde, e ciò che il provider rifiuta a causa di una voce, è il contratto documentato di quel provider stesso. Un provider che non può escludere nulla rifiuta una FeatureRecipe che dichiara questa chiave prima che venga renderizzato qualsiasi cosa. Viene filtrato solo ciò che source: renderizza — una voce workload: o artifacts: non lo è mai — quindi la chiave richiede source. Ogni valore è un template, valutato rispetto al contesto rispetto a cui viene valutato valuesMapping. Il when di una voce viene valutato per primo, e una voce il cui when produce un valore falsy viene scartata. Ogni voce rimasta attiva deve escludere qualcosa: una voce attiva che non corrisponde a nulla di ciò che la sorgente ha renderizzato arresta la build, nominando la voce. La sorgente viene comunque renderizzata per intero — ogni template di un chart viene comunque eseguito, quindi un template che fallisce fa comunque fallire la build — e viene escluso solo il suo output. La chiave si scrive in modo identico su una Recipe e su una FeatureRecipe. Almeno 1 voce. |
injectMapping | string | no | Template Go inline facoltativo valutato durante la fase di intercettazione pre-rendering, una volta per ogni componente raggiunto dall’associazione, rispetto al contesto di template di quel componente: legge ‘.context’ e ‘.features’ del componente e ‘.attachment_name’, ‘.values’, ‘.infra’ e ‘.locals’ dell’associazione, qualunque cosa dica executionScope, e un riferimento a ‘.boundary’, che il contesto di nessun componente porta, arresta la build. Produce un dizionario JSON/YAML che il compilatore Go unisce in profondità in modo nativo sopra il pipe di memoria ‘.context.inject’ del Chiamante. Usato per la mutazione lato Chiamante, senza Wasm, delle variabili d’ambiente e dei contratti di consegna. |
pipeline | object[] | no | Elenco sequenziale di passi di pipeline Wasm eseguiti dopo il rendering sull’insieme dei documenti renderizzati, ciascuno dei quali restituisce patch RFC 6902 ed effetti collaterali. |
executionScope | string (enum) | no | Se la Generazione delle risorse di questa FeatureRecipe viene eseguita per componente (il valore predefinito) oppure una volta per ogni associazione a un confine. Le FeatureRecipes con ambito boundary vengono deduplicate per (boundary_path, istanza di FeatureRecipe) e ogni template tranne l’injectMapping legge un contesto di template con ambito boundary: i pilastri .boundary.* invece dei pilastri .context.* per componente, un riferimento ai quali arresta la build. L’injectMapping viene eseguito una volta per ogni componente raggiunto dall’associazione indipendentemente da executionScope, quindi legge il contesto di quel componente e mai .boundary. Valori consentiti: "component", "boundary" Predefinito: "component" |
readsCallerRenderFacts | booleana | no | Dichiara che i template di questa FeatureRecipe leggono ciò che hanno renderizzato i Components che si connettono a quello a cui è associata: i fatti di rendering che il provider di ciascuno di quei chiamanti riporta sul proprio output. Quando è true e la FeatureRecipe esegue il rendering per componente, ogni sua associazione viene renderizzata dopo che ogni Component della build è stato renderizzato, invece che subito dopo il Component a cui è associata, così il rendering di ogni chiamante è completo prima che l’associazione venga valutata. Quando è false o assente, la voce di nessun chiamante su ‘.context.used_by’ porta fatti di rendering, l’associazione viene renderizzata subito dopo il suo Component a meno che readsTargetRenderFacts sia true, e la build si arresta su un template scritto inline in questa FeatureRecipe che legge i fatti di rendering di un chiamante sotto ‘.context.used_by’. Predefinito: false |
readsTargetRenderFacts | booleana | no | Dichiara che i template di questa FeatureRecipe leggono ciò che hanno renderizzato i Components a cui è collegato quello a cui è associata: i fatti di rendering che il provider di ciascuna di quelle destinazioni riporta sul proprio output, su ogni voce di ‘.context.uses’. Quando è true e la FeatureRecipe esegue il rendering per componente, ogni sua associazione viene renderizzata dopo che ogni Component della build è stato renderizzato, invece che subito dopo il Component a cui è associata, così il rendering di ciascuna destinazione è completo prima che l’associazione venga valutata. È lo stesso rendering posticipato che causa readsCallerRenderFacts, quindi impostare l’una o l’altra chiave, o entrambe, fa sì che l’associazione venga renderizzata in quel momento. Quando è false o assente, nessuna voce di ‘.context.uses’ porta fatti di rendering, l’associazione viene renderizzata subito dopo il suo Component a meno che readsCallerRenderFacts sia true, e la build si arresta su un template scritto inline in questa FeatureRecipe che legge i fatti di rendering di una destinazione sotto ‘.context.uses’. Predefinito: false |
assertions | mappa di string | no | Validazione tra campi in fase di build. Ogni voce è un’asserzione con nome: la chiave è un identificatore di regola stabile che compare nei messaggi di errore; il valore è una stringa di template Go con semantica di arresto {{ fail "message" }}. Più asserzioni con nome per entità vengono valutate per istanza nell’ordine dichiarato dall’autore; la prima asserzione che fallisce arresta la build. Le asserzioni della FeatureRecipe vengono valutate dopo il legame con la ricetta e dopo la valutazione dei provides, prima del rendering, ed esprimono invarianti di implementazione dello specifico chart o modulo che la FeatureRecipe usa come sorgente. Contesto del template: .values / .infra / .uses / .features / .metadata più .provides / .locals / .recipe. Il valutatore usa missingkey=error: i riferimenti a chiavi non definite provocano un arresto con una diagnostica no-such-key. Poiché il semplice riferimento provoca l’arresto prima che possa essere eseguito qualsiasi fallback, un semplice default non fornisce un fallback per un campo opzionale su questa superficie — proteggi il riferimento con hasKey, oppure usa l’helper optional, che esegue direttamente il controllo di presenza. Nemmeno la lettura della chiave tramite index ne fornisce uno: index provoca un arresto su una chiave di mappa che la mappa non contiene, nominando la chiave. |
Non sono consentite proprietà aggiuntive.
featurerecipe.spec.omits[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
kind | string | sì | Il tipo dell’unità da escludere, nel vocabolario del provider che esegue il rendering della sorgente: per un chart, il kind proprio di un documento renderizzato, come Secret; per un file compose, service, volume o config; per un template CloudFormation, il Type di una risorsa, come AWS::S3::Bucket. Nomina un tipo che la sorgente renderizza e non ha alcuna relazione con il kind: che porta un source: strutturato. Un template. |
name | string | sì | Il nome dell’unità da escludere, nel vocabolario del provider che esegue il rendering della sorgente: per un chart, il metadata.name proprio di un documento renderizzato; per un file compose, la chiave dell’unità sotto services:, volumes: o configs:; per un template CloudFormation, l’ID logico della risorsa, cioè la sua chiave sotto Resources. Un template. |
namespace | string | no | Il namespace in cui si trova l’unità da escludere, quando la voce deve corrispondere solo a un’unità in quel namespace — per un provider il cui output ha namespace, come accade per i documenti renderizzati di un chart. Se è assente, o se il rendering produce la stringa vuota, la voce corrisponde a un’unità del suo tipo e del suo nome qualunque sia il suo namespace. Un file compose e un template CloudFormation non hanno namespace, e i loro provider rifiutano una voce che ne nomina uno. Un template. |
subchart | string | no | Il sotto-chart da cui proviene l’unità da escludere, quando la voce deve corrispondere solo alla copia che renderizza un sotto-chart — per una sorgente assemblata da sorgenti annidate, come lo è un chart dai suoi sotto-chart. Per un chart, il nome proprio del sotto-chart, oppure l’alias che gli dà la dipendenza del suo genitore, con i nomi di un sotto-chart annidato uniti da / a partire dal più esterno: operator, oppure operator/webhooks. La voce corrisponde allora a un documento renderizzato dai templates/ o dai crds/ propri di quel sotto-chart, e non a uno che il chart renderizza da sé né a uno che renderizza un sotto-chart annidato al suo interno. Se è assente, o se il rendering produce la stringa vuota, la voce corrisponde a un’unità del suo tipo e del suo nome ovunque abbia avuto origine. Un chart che non renderizza alcun sotto-chart con quel nome arresta la build, nominando la voce. Un file compose e un template CloudFormation non hanno sotto-chart, e i loro provider rifiutano una voce che ne nomina uno. Un template. |
when | string | no | Template Go inline valutato prima degli altri campi della voce. Quando produce un valore falsy la voce viene scartata: i suoi altri campi non vengono valutati, nulla viene escluso a causa sua e non è tenuta a corrispondere ad alcunché. Un when vuoto o assente mantiene la voce. La veridicità segue la convenzione standard per l’output di template di tipo booleano: le stringhe true/True/TRUE, qualsiasi numero diverso da zero e qualsiasi altra stringa non vuota sono vere, mentre false/False/FALSE, la stringa vuota e lo zero sono falsi. Un when il cui rendering fallisce arresta la build. |
Non sono consentite proprietà aggiuntive.
featurerecipe.spec.pipeline[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
id | string | sì | Un identificatore programmatico per questo passo, univoco tra i passi di questa pipeline: un documento che dichiara uno stesso id su due dei suoi passi viene rifiutato quando viene letto. Un passo successivo della stessa pipeline legge gli output di questo passo come .steps.<id>.outputs. Pattern: ^[a-zA-Z0-9_]+$. |
plugin | string | sì | Il riferimento all’entità Plugin che questo passo esegue, sempre qualificato con il tipo di socket proprio del plugin: <pluginType>/<name> con una versione opzionale, come in parser/yaml o parser/yaml:1.0.0. La qualificazione è obbligatoria e non una forma tra le tante — un name:version non qualificato viene rifiutato, perché due socket possono contenere un plugin con lo stesso nome ed è la qualificazione a rendere l’entità risolvibile. La build risolve l’entità nel suo artefatto .wasm indirizzato per contenuto — individuato a partire dall’identità del plugin e dal registry configurato, con il suo digest fissato nel file di lock — e ne carica i byte. Un semplice riferimento a un .wasm o a un artefatto non è accettato qui. |
function | string | sì | La funzione Wasm esportata da invocare. |
with | string | no | Template Go inline che produce una mappa JSON/YAML che soddisfa rigorosamente lo schema di input esplicito di questo plugin. |
optional | booleana | no | Quando è true, un fallimento di questo passo (un trap del guest, una patch che punta a un documento non presente nell’insieme, una patch malformata o una diagnostica con gravità di arresto) viene declassato a un avvertimento ben visibile: l’insieme di documenti precedente al passo viene ripristinato, l’output di questo passo viene scartato e la pipeline prosegue. Quando è false o assente, qualsiasi fallimento di un passo arresta la build dopo aver ripristinato l’insieme di documenti precedente al passo. |
when | string | no | Template Go inline valutato durante l’attraversamento della pipeline. Quando produce un valore falsy il passo viene saltato — un passaggio diretto: l’insieme di documenti arriva invariato al passo successivo, senza contribuire patch, effetti collaterali né record del passo. Un when vuoto o assente esegue sempre il passo. La veridicità segue la convenzione standard per l’output di template di tipo booleano: le stringhe true/True/TRUE, qualsiasi numero diverso da zero e qualsiasi altra stringa non vuota sono vere, mentre false/False/FALSE, la stringa vuota e lo zero sono falsi. when e optional sono indipendenti: un passo può dichiararli entrambi. |
Non sono consentite proprietà aggiuntive.