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

La tassonomia delle entità

L’architettura di Aggrega è organizzata in quattro domini, ciascuno di proprietà di una persona diversa e contenente tipi di entità specifici, più un livello di librerie di Tier 3 — il terzo livello del modello a livelli delle entità del riferimento del linguaggio — che contiene contenuti riutilizzabili di schema, mapping, workload e artefatti. La panoramica seguente mostra come i quattro domini e le librerie di Tier 3 si relazionano tra loro; ogni sezione successiva si apre con un diagramma delle proprie entità, in cui un’entità di un altro dominio è disegnata con un contorno tratteggiato. Le superfici di authoring dettagliate (campi, schemi, esempi) di ciascuna entità si trovano nel catalogo delle entità del riferimento del linguaggio.

graph TD
    Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
    Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
    Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
    Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
    Libs["<b>Tier 3: Libraries</b>"]

    Intent -->|"requests, attaches"| Catalog
    Intent -->|"binds via"| Routing
    Routing -->|"attaches"| Catalog
    Catalog -->|"resolved to"| Infra
    Routing -->|"resolves, renders via"| Infra
    Catalog -.->|"$ref"| Libs
    Infra -.->|"$import"| Libs

Il corpus si estende su quattro domini più il livello di librerie di Tier 3:

#EntitàDominioRuolo
1AggregateDominio 1 — Intento dello sviluppatoreProgetto della topologia applicativa
2ComponentDominio 2 — Platform CatalogInterfaccia astratta di nodo di calcolo
3FeatureDominio 2 — Platform CatalogTratto operativo (incluse le Features di credenziali)
4RecipeDominio 3 — Base dell’infrastrutturaImplementazione di un Component, per provider
5FeatureRecipeDominio 3 — Base dell’infrastrutturaImplementazione di una Feature, per provider
6PluginDominio 3 — Base dell’infrastrutturaPlugin WebAssembly indirizzato per contenuto (rendering dei provider, passi di pipeline, linting)
7ManifestDominio 4 — Instradamento e policyLockfile delle dipendenze che mappa le interfacce sulle Recipes
8ReleaseDominio 4 — Instradamento e policyRouter di deployment che lega l’Aggregate al Manifest
9SchemaLibraryTier 3 — LibrerieDefinizioni JSON Schema 2020-12 riutilizzabili
10MappingLibraryTier 3 — LibrerieFrammenti di template Go riutilizzabili
11WorkloadLibraryTier 3 — LibrerieFrammenti di template di Workload riutilizzabili
12ArtifactLibraryTier 3 — LibrerieBundle di artefatti con nome riutilizzabili

Quella tabella è l’insieme completo dei tipi di entità di authoring, i tipi che un autore dichiara in un campo kind:. Il tipo Workload è un contenuto di proprietà della piattaforma incorporato nell’input sintetizzato di una Recipe anziché un’entità di catalogo autonoma (vedi il capitolo 16), per cui è deliberatamente assente dalla tabella precedente.

Il Plugin è un’entità di authoring di prima classe — con un proprio kind, un proprio JSON Schema e una propria directory di catalogo — di proprietà di Platform Ops nel Dominio 3. Un Plugin è un riferimento indirizzato per contenuto a un artefatto WebAssembly, che dichiara l’unico tipo di socket che implementa. La tassonomia ha sette membri: provider (rende i nodi IR in artefatti nativi del provider), linter (solleva diagnostiche sul contenuto scritto), pipeline-step (un passo di una feature-recipe-pipeline), governance (svolge un ruolo di governance — trasforma label o annotazioni, oppure restituisce un verdetto di accettazione/rifiuto sul grafo IR o sugli artefatti renderizzati), cli (aggiunge un sottocomando aggrega che un operatore invoca dalla riga di comando), parser (trasforma un testo sorgente esterno in un albero strutturato canonico) e importer (trasforma una sorgente esterna di infrastruttura o di definizione di agenti in bozze di file di authoring di Aggrega). Un Plugin di rendering del provider (pluginType: provider) è l’unità che serve il rendering del provider: dichiara il nome o i nomi di provider che renderizza in spec.provider.capabilities e porta il resto dei propri metadati di socket del provider nello stesso blocco spec.provider. Il compilatore fissa e instrada il riferimento; il runtime WebAssembly esegue i byte; il compilatore non interpreta ciò che il plugin fa — il plugin è il veicolo dell’intelligenza specifica di dominio che vive in WebAssembly. La sua superficie di authoring e di metadati è documentata in language-reference/entities/plugin.md.

Dominio 1: intento dello sviluppatore (il «cosa»)

graph LR
    classDef ext stroke-dasharray:5 4;

    A["Aggregate<br/>The 'What'"]
    CC["Component"]:::ext
    CapC["Feature"]:::ext
    EB["Release"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    A -->|"Binds via"| EB
  • Ruolo: lo sviluppatore. Si concentra esclusivamente sull’architettura AI, sui cicli cognitivi e sui requisiti di sopravvivenza dell’applicazione. Non ha bisogno di conoscere CEL, OPA o le porte fisiche.
  • 1. Aggregate: il progetto dichiarativo basato su mappe della topologia applicativa. Che funga da Aggregate radice costruito da una Release o da modulo parametrizzato e riutilizzabile, definisce components logici e collega, sotto features, le Features il cui comportamento è intento applicativo, con i relativi values; una Feature i cui input sono tutti operativi viene invece collegata dall’operatore nella Release (vedi il dominio 4). Una credenziale si richiede su quella stessa superficie di collegamento features, tramite una Feature di credenziali: non esiste un blocco separato per essa. Definisce requisiti di capacità astratti tramite parameters (contratti tipizzati scritti nel vocabolario della forma compatta) e lo stato del payload tramite values. Le istanze di Component supportano un campo description opzionale per la documentazione e il rendering nello Studio. Promuove la convenzione «Zero-Port» (astrarre le porte di rete a meno che non siano esplicitamente richieste da codice preesistente) senza alcuna piattaforma di destinazione o namespace codificati in modo fisso.

Dominio 2: Platform Catalog (le «interfacce e intelligenza»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release"]:::ext
    CC["Component<br/>The Compute Interface"]
    CapC["Feature<br/>The Operational Trait"]
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    EB -.->|"Attaches"| CapC
    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
  • Ruolo: il Platform Architect. Il «programmatore» della piattaforma. Colloca ogni componente nell’ontologia operativa, scrive le policy programmabili (mutatori e validatori Wasm) e stabilisce le etichette semantiche di duck typing.
  • 2. Component: l’interfaccia astratta di un nodo di calcolo. Dichiara la propria forma di base tramite l’ontologia cloud operativa (ad es. component.aggrega.ai/type: server) e stratifica la propria identità cognitiva tramite etichette di duck typing (ad es. model.aggrega.ai/capability: generative). Dichiara gli slot delle credenziali tramite featuresSchema (obbligatori/opzionali, blackbox/trasparenti) e usa schema: (JSON Schema 2020-12, di norma scritto con la notazione abbreviata della forma compatta) per validare rigorosamente il blocco values opaco dello sviluppatore.
  • 3. Feature: un tratto operativo modulare (ad es. mascheramento dei dati, instradamento DNS, gestione dei segreti). Usa selettori di etichette appliesTo per legarsi dinamicamente a specifiche etichette semantiche. Come i Components, dichiara gli slot delle credenziali tramite featuresSchema per imporre il provisioning delle chiavi API. Soprattutto, usa metadata.annotations per etichettare esplicitamente gli elementi nel grafo IR piatto, il che indica ai validatori di policy Wasm e ai plugin di rendering a valle come gestire il payload di configurazione della Feature.
    • Features di credenziali: la piattaforma unifica la gestione delle credenziali nell’entità Feature: una Feature con l’etichetta feature.aggrega.ai/kind: secret è una feature di credenziali, che definisce un’interfaccia di interrogazione verso un archivio di segreti (ad es. AWS Secrets Manager, HashiCorp Vault). Si collega sotto features: come qualsiasi altra Feature, sulla stessa superficie e con la stessa forma; l’etichetta è un metadato che il catalogo riporta per descrivere ciò che il collegamento produce, e nessun ramo del compilatore la legge. Non esiste un kind separato per l’archivio di segreti o per la recipe di segreti: una FeatureRecipe di credenziali ha la stessa forma di qualsiasi altra FeatureRecipe, la pipeline di recupero e consegna è la stessa per entrambe e il contratto di consegna inject (env, file, arg) è condiviso. Un’entità, una parola chiave di collegamento, un percorso di esecuzione dei modificatori attraverso il rendering; e le credenziali si mappano sotto features.type nel Manifest.

L’ontologia come etichetta. L’ontologia cloud operativa è dichiarata in metadata.labels["component.aggrega.ai/type"] anziché come campo spec.type di primo livello. Questa scelta consente al motore dei selettori di etichette del compilatore di puntare direttamente ai valori dell’ontologia: una Feature dichiara appliesTo: "component.aggrega.ai/type in (server, worker)" per collegarsi dinamicamente a ogni componente server o worker senza alcuna nuova logica Go nel compilatore centrale. Lo stesso meccanismo dei selettori si applica a ogni etichetta di Aggrega, per cui una Feature, un selettore di socket o una mappatura dei confini di una Release legge la chiave di etichetta propria di un catalogo esattamente come legge questa.

component.aggrega.ai/type è la chiave di Aggrega, e il suo insieme di valori è chiuso: lo schema pubblicato del Component enumera le primitive, e un documento che riporti qualsiasi altro valore viene rifiutato al caricamento, con E0215 che nomina l’etichetta ed elenca ciò che accetta. Un catalogo che necessita di una classificazione che Aggrega non definisce aggiunge la propria chiave di etichetta accanto a essa (lo schema del Component accetta qualsiasi ulteriore chiave di etichetta con un valore stringa), per cui un nuovo asse costa una chiave tua e nessuna release del compilatore, mentre la chiave riservata mantiene un unico significato ovunque. È questo che fa funzionare una Feature scritta per component.aggrega.ai/type in (stateful-server) con Components di autori che non si sono mai incontrati.

Dominio 3: base dell’infrastruttura (le «implementazioni»)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    ENV["Manifest"]:::ext
    EB["Release"]:::ext
    CD["Recipe<br/>The Implementation"]
    CapD["FeatureRecipe<br/>The Binding"]
    T["Plugin<br/>The Wasm Plugin"]

    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
    EB -->|"Renders via"| T
  • Ruolo: l’ingegnere dell’infrastruttura / Ops. Possiede la realtà fisica, l’assegnazione delle porte di rete e la logica di templating.
  • 4. Recipe: il template di traduzione multi-provider (ad es. Helm o Docker Compose). Stabilisce un contratto API rigoroso 1:1 con il componente del catalogo tramite la parola chiave implements. La Recipe mappa i .values dello sviluppatore nel formato fisico. Codifica in modo fisso le porte di rete fisiche (ad es. 5432) e legge i provides della destinazione attraverso la pipe .context.uses, soddisfacendo il contratto di iniezione senza codificare in modo fisso i nomi dei database.
  • 5. FeatureRecipe: mappa esplicitamente una Feature su un’implementazione di infrastruttura concreta tramite la parola chiave implements. Impone una capability del provider di destinazione in capability (ad es. helm, compose). Poiché la piattaforma unifica la gestione delle credenziali nell’entità Feature, le FeatureRecipes gestiscono sia le feature operative (mascheramento dei dati, instradamento DNS, iniezione di sidecar) sia le feature di credenziali (generazione di CRD per i vault, montaggio di volumi di segreti). Per coprire tutto questo spettro, supporta tre blocchi di esecuzione distinti:
    1. pipeline: un array sequenziale di plugin WebAssembly (Wasm) per la mutazione del Workload dopo il rendering (ad es. iniettare un sidecar Envoy tramite JSONPatch o montare un volume di segreti).
    2. source e valuesMapping, workload, artifacts: gli stessi tre tipi di input che porta una Recipe, usati per la generazione di risorse, consentono agli Ops di eseguire nativamente il rendering di template statici (ad es. generare una nuova CRD HTTPRoute o una CRD ExternalSecret) accanto al componente di base.
    3. injectMapping (intercettazione prima del rendering): un blocco di template Go nativo eseguito prima del rendering della Recipe di base. Produce un dizionario JSON che il compilatore unisce nativamente in profondità sopra la pipe di memoria .context.inject del chiamante, consentendo la mutazione delle variabili d’ambiente e delle stringhe di connessione lato chiamante, senza Wasm.
    • Il pattern FeatureRecipe per le credenziali: quando una FeatureRecipe implementa una Feature di credenziali (etichettata feature.aggrega.ai/kind: secret), si applica il principio standard del Plugin in due parti: la pipeline concatena un plugin Fetcher (che genera la CRD specifica del vault) seguito da un plugin Injector (che monta il segreto nel container di destinazione). La separazione Fetcher/Injector massimizza la riusabilità: passare da AWS Secrets Manager a HashiCorp Vault richiede solo di sostituire il plugin Fetcher; l’Injector resta identico.
  • 6. Plugin: il plugin WebAssembly indirizzato per contenuto. Un Plugin di rendering per provider (pluginType: provider) è l’unità che trasforma i tipi di input di una Recipe nel formato di file finale serializzato come stringa: dichiara in spec.provider.capabilities il nome o i nomi dei provider che serve (ad es. helm), espone un export render_node a cui il compilatore invia le richieste e porta il resto dei metadati del proprio socket provider (workloadSchema, wellKnownAnnotations) in quello stesso blocco spec.provider. Gli altri tipi di socket che un Plugin può dichiarare sono pipeline-step, linter, governance, cli, parser e importer. Il compilatore instrada il riferimento fissato; il runtime WebAssembly esegue i byte.

Dominio 4: instradamento e policy (il «collante»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release<br/>The Deployment Router"]
    ENV["Manifest<br/>The Dependency Lockfile"]
    CapC["Feature"]:::ext
    T["Plugin"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -->|"Binds via"| EB
    EB -.->|"Attaches"| CapC
    EB -->|"Uses"| ENV
    EB -->|"Renders via"| T
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
  • Ruolo: il Platform Operator / DevOps.
  • 7. Manifest: il lockfile delle dipendenze. Usa una mappatura URI piatta: un dizionario components.type mappa i tipi di componenti del catalogo sugli URI delle Recipe, e un dizionario features.type mappa i tipi di Feature sugli URI delle FeatureRecipe. La risoluzione è una ricerca diretta degli URI nel lockfile e nel catalogo; la determinazione della capability deriva dal campo spec.capability di ciascuna Recipe risolta, al momento della build. Dopo la risoluzione, ogni entità deve avere una mappatura, altrimenti il compilatore si arresta. Per mantenere un ecosistema DRY, i Manifests supportano un pattern di composizione in stile Kustomize tramite la parola chiave extends, che consente ai manifest specifici di un ambiente (come locale o staging) di ereditare in modo pulito da un manifest di base globale e di dichiarare solo le proprie sostituzioni specifiche.
  • 8. Release: il router. Lega un aggregate a un manifest e mappa i componenti su confini fisici (ad es. aws-eks-production). Per mantenere un flusso di lavoro DRY, le Releases supportano l’ereditarietà tramite la parola chiave extends, che consente alle release specifiche di un ambiente di ereditare in modo pulito da una release di base globale. Soddisfa il contratto astratto dell’aggregate iniettando le realtà fisiche rigorosamente nel blocco parameters, e inietta il dimensionamento fisico (come CPU o porte) tramite il namespace parallelo infra. Per proteggere l’Aggregate come unica fonte di verità, lo schema della Release vieta meccanicamente un blocco values:: gli Ops non possono dichiarare values su alcun Component o Feature da una Release. La variazione per ambiente dei valori rivolti allo sviluppatore passa attraverso il Parameter Hoisting: lo sviluppatore espone un campo tipizzato parameters.* nell’Aggregate, il template values del Component vi fa riferimento e la Release soddisfa il parametro per il proprio ambiente. I valori prodotti differiscono tra gli ambienti, mentre l’Aggregate, la superficie di authoring che stabilisce quali valori esistono e come fluiscono, resta l’unica fonte di verità. Vedi il vincolo 4, «La Release non può sovrascrivere i valori dello sviluppatore», in Vincoli architetturali e pattern consigliati per il divieto a livello di schema enunciato esplicitamente. Soprattutto, per impedire Releases non tracciabili che «mutano l’aggregate», quando una Release usa extends, la dichiarazione di un aggregate viene rifiutata dallo schema della Release (il vincolo dello schema non consente di dichiarare aggregate quando si usa extends). La release figlia deve corrispondere esattamente allo stesso intento dello sviluppatore della release padre. Il manifest, invece, diventa opzionale, abilitando il «late binding»: gli Ops possono ereditare l’intera topologia fisica ma sostituire chirurgicamente il lockfile delle dipendenze.
    • Collegamento delle Feature: anche la Release collega Features, sotto features su un confine o su un singolo componente. Una Feature i cui input sono tutti operativi la collega direttamente, con il suo type e il suo infra; una Feature collegata dall’Aggregate la dimensiona, scrivendo l’infra di quel collegamento sotto lo stesso nome.

Perché separare il Manifest dalla Release. Separare il lockfile del software (Manifest) dal router di deployment (Release) rende possibile una forma che le due entità non potrebbero produrre da sole: DevOps distribuisce una singola applicazione su più router di deployment regionali (diverse Releases che puntano a diverse regioni cloud, tutte con riferimento allo stesso Manifest) senza duplicare i binding delle Recipe tra gli ambienti. Ogni Release regionale porta la propria disposizione dei confini e i parametri specifici dell’ambiente, consumando lo stesso lockfile del software fornito dal Manifest. Lo scaling multi-regione deriva dalla separazione dei domini, non dalla duplicazione del Manifest.

Tier 3: librerie (riuso del catalogo)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext
    SL["SchemaLibrary<br/>JSON Schema definitions"]
    ML["MappingLibrary<br/>Go template fragments"]
    WL["WorkloadLibrary<br/>Workload template fragments"]
    AL["ArtifactLibrary<br/>Named artifact bundles"]

    CC -.->|"$ref"| SL
    CapC -.->|"$ref"| SL
    CD -.->|"valuesMapping $import"| ML
    CapD -.->|"$import"| ML
    CD -.->|"workload $import"| WL
    CD -.->|"artifacts $import"| AL
    CapD -.->|"$import"| AL
  • Ruolo: il Platform Architect (la stessa persona del dominio 2), ma il ruolo entra in gioco solo quando il contenuto del catalogo cresce abbastanza da trarre vantaggio dal riuso degli schemi tra un Component e l’altro o dal riuso tra una Recipe e l’altra di template, forme di workload o bundle di artefatti. Gli autori singoli e i cataloghi piccoli si distribuiscono senza alcuna entità di Tier 3.
  • 9. SchemaLibrary: definizioni JSON Schema 2020-12 riutilizzabili. Una libreria dichiara schemi con nome in spec.schemas: e helper parametrizzati opzionali in spec.templates: (con dichiarazioni $params: e riferimenti $instantiate: per il riuso parametrico). Le entità del catalogo consumano le voci della libreria tramite la parola chiave JSON Schema standard $ref: che punta alla voce della libreria per identità, nella forma senza host <library>#/schemas/<name> (la versione proviene dal lockfile, non dal riferimento). Nomi in PascalCase, distribuzione tramite OCI, versione fissata nel lockfile. Facoltativa, per i cataloghi che necessitano del riuso degli schemi tra un Component e l’altro: forme comuni come PodResources, PersistenceSpec, NodePool, MetricsServiceMonitor ricorrono in ogni Component di datastore e in ogni Component di workload, e le voci della SchemaLibrary eliminano questa ripetizione dalla definizione di ciascun Component.
  • 10. MappingLibrary: frammenti di template Go riutilizzabili. Una libreria dichiara template con nome in spec.mappings:. Le Recipes e le FeatureRecipes consumano le voci della libreria per identità tramite valuesMapping: { $import: <library>#/mappings/<name> }. Un’unica modalità di authoring (solo template Go); nessun percorso di authoring parallelo in Jsonnet. Facoltativa, per i cataloghi che necessitano del riuso dei mapping tra una Recipe e l’altra: pattern comuni come la logica degli helper dei chart Bitnami o i pattern condivisi dei template dei pod ricorrono in ogni Recipe di datastore che punta allo stesso provider, e le voci della MappingLibrary eliminano questa ripetizione dalla definizione di ciascuna Recipe.
  • 11. WorkloadLibrary: frammenti di template di Workload riutilizzabili. Una libreria dichiara voci di workload con nome in spec.workloads:. Una Recipe consuma una voce per identità tramite workload: { $import: <library>#/workloads/<entry> }, e il corpo importato viene validato rispetto allo schema del Workload di proprietà della piattaforma esattamente come un blocco workload: inline, per cui un workload importato da una libreria produce lo stesso rendering dell’equivalente inline. Un’unica modalità di authoring (solo template Go). Facoltativa, per i cataloghi che necessitano del riuso dei workload tra una Recipe e l’altra, quando diverse Recipes condividono un’unica forma di deployment e differiscono solo per i valori.
  • 12. ArtifactLibrary: bundle di artefatti con nome riutilizzabili. Una libreria dichiara bundle con nome in spec.artifacts:, ciascuno dei quali raggruppa i file di output che vanno insieme (ad esempio una CRD, il suo RBAC e una ConfigMap) e viene importato come un’unica unità. Le Recipes e le FeatureRecipes consumano un bundle per identità tramite artifacts.<name>: { $import: <library>#/artifacts/<name> }. Un’unica modalità di authoring (solo template Go). Facoltativa, per i cataloghi che necessitano del riuso degli artefatti tra una Recipe e l’altra, quando lo stesso insieme di risorse ausiliarie accompagna molte Recipes.

Ogni libreria viene pubblicata tramite OCI, è fissata nel lockfile (le sezioni schema_libraries:, mapping_libraries:, workload_libraries: e artifact_libraries:) e compare nella UI dell’Hub con la consapevolezza dei consumatori (quali Components fanno riferimento a quali voci di libreria; quali Recipes consumano quali voci di libreria).