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

Riferimento del linguaggio

Il «cosa» e il «come si usa» di Aggrega. Sintassi, invocazione della CLI, catalogo degli errori, esempi svolti.

Leggi i capitoli qui sotto in ordine per una prima comprensione. Le sottodirectory di riferimento sono elencate sotto il rispettivo capitolo — vai direttamente lì quando cerchi una specifica entità, parola chiave, provider, comando della CLI o errore.

Prima di leggere la sequenza di capitoli, consulta Stato del linguaggio per lo stato attuale di maturità — quali superfici del linguaggio sono disponibili oggi, quali sono accettate ma il compilatore non vi agisce ancora e quali sono pianificate per iterazioni future. Compatibilità indica che cosa promette una release per gli schemi, la riga di comando, gli strumenti dell’assistente, i codici di errore e i kit per plugin.

Modello a livelli delle entità

I tipi di entità di authoring di Aggrega sono organizzati in tre livelli che riflettono la progressione dell’adozione (vedi sotto). Accanto a essi si trova il Workload, di proprietà della piattaforma, che non è un tipo di authoring a sé stante: è la forma che assume l’input sintetizzato di una Recipe ed esprime la forma di calcolo tramite il vocabolario form: (stateless, stateful, daemon, scheduled, task, reference). La suddivisione in livelli è un meccanismo di documentazione e di onboarding, non un vincolo di runtime: ogni tipo di entità è un cittadino di prima classe del linguaggio; il compilatore li tratta in modo uniforme; l’Aggrega open source supporta tutti i livelli senza licenze né limitazioni di funzionalità. I contrassegni di livello segnalano «avanzato; salta se non serve» ai fini della navigazione, non delle capacità.

LivelloTipi di entitàQuando adottarli
Livello 1 — la superficie minima indispensabileAggregate, Component, Recipe, Manifest, ReleaseGiorno 1 — fondatori solitari e piccoli team rilasciano software funzionante usando solo il Livello 1. Il modello mentale: «Ho un’app; voglio distribuirla; ecco come.»
Livello 2 — separazione dei ruoliFeature, FeatureRecipe, PluginGiorno 30 — piccoli team in cui i ruoli si separano (sviluppatore + Ops + talvolta Security). Il Livello 2 entra in gioco tramite i Plugins di rendering dei provider (Ops sceglie tra Helm, helm-chart, Compose, Terraform e CloudFormation), le Features (Security gestisce le credenziali separatamente dalla configurazione dell’app) e le FeatureRecipes (personalizzazione al momento del binding per ciascun provider).
Livello 3 — riuso trasversale tra ComponentSchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryGiorno 365 — cataloghi maturi in cui forme comuni ricorrono in molte entità. La soglia è informale: quando una forma (ad es. PodResources) compare in 5+ Components e coordinarne gli aggiornamenti diventa un attrito, una voce di SchemaLibrary si giustifica da sé.

Ogni progressione è facoltativa. Un fondatore solitario non è mai costretto a guardare il Livello 3; un catalogo enterprise ha pieno accesso al Livello 3 quando serve. Il Livello 1 è completo per il caso d’uso del fondatore solitario: uno sviluppatore può rilasciare applicazioni funzionanti usando solo entità di Livello 1. È una proprietà di design forte: il Livello 1 non è un «sottoinsieme che compila»; è un «sottoinsieme che rilascia software».

La superficie di Livello 1 a cinque entità comporta un costo d’ingresso: Aggregate + Component + Recipe + Manifest + Release è più cerimonioso di «metti un file YAML, ottieni un servizio in esecuzione». Il costo è il prezzo della separazione dell’authoring in quattro domini (Intento dello sviluppatore / Catalogo della piattaforma / Operazioni della piattaforma / Routing) che rende Aggrega diverso da Helm o Terraform puri. I tutorial di Livello 1 illustrano esplicitamente la configurazione a cinque entità.

All’interno del Livello 3, il meccanismo spec.templates / $instantiate: (helper parametrici nella SchemaLibrary) è documentato come una sotto-funzionalità ancora più avanzata. La maggior parte di chi adotta il Livello 3 inizialmente non ricorre a spec.templates; la soglia è «quando la tua libreria ha 6+ schemi che condividono una struttura parametrizzata».

Ordine di lettura

  1. Come usare questo riferimento
  2. Convenzioni di denominazione
  3. Panoramica del riferimento alle entità
  4. Panoramica del vocabolario
  5. Panoramica dei template
  6. Panoramica dei Providers
  7. Panoramica della CLI
  8. Panoramica degli errori
  9. Panoramica degli esempi

Riferimento per l’authoring dei Plugin

La superficie dei plugin Wasm si colloca accanto alla sequenza dei capitoli anziché al suo interno: chi scrive un plugin la legge indipendentemente dal percorso di authoring delle entità. La pagina dell’entità plugin copre la superficie di authoring del catalogo; le pagine seguenti coprono i socket, i payload e il flusso di lavoro dell’autore.

  • plugin-contract — i socket a cui si collega un plugin, la loro posizione nella pipeline e le forme di input e di output di ciascun socket.
  • plugin-developer-guide — il flusso di lavoro completo dell’autore: describe(), dichiarazioni di capacità, limiti di runtime, il ciclo di vita publish/pull/build, firma, versionamento.
  • policy-socket — il socket di governance in dettaglio: i suoi quattro ruoli, le severità dei verdetti, il canale di input dell’operatore e come scrivere una policy per l’uno o l’altro dei motori inclusi nel compilatore.
  • governance-attachment-facts — i fatti per singolo collegamento che una policy di governance legge dal grafo di build, incluse le tre unità della marcatura di sensibilità e il motivo per cui una marcatura assente non è un permesso.
  • when-to-use-a-pipeline-step — scegliere tra un passaggio di pipeline e una FeatureRecipe basata su template.
  • embedded-plugins — i plugin inclusi nel binario del compilatore.
  • tagging-plugins — i due plugin di governance integrati che scrivono label senza una policy, governance/label-injector e governance/selector-tagger: le loro impostazioni e ciò che ciascuno scrive.
  • core-importers — i dieci importatori del compilatore, da Langflow, Flowise e n8n a Compose, MCP e ai framework per agenti: cosa legge e cosa abbozza ciascuno, le loro impostazioni e la loro pubblicazione con ogni release del compilatore.
  • authoring-a-provider-walkthrough — una guida passo passo alla scrittura di un guest provider, da una directory vuota a una build che scrive i file di cui il provider ha eseguito il rendering.
  • writing-a-governance-plugin — scrivere un plugin di governance tuo a partire dallo scheletro dell’adattatore del plugin kit: una regola, l’export di ciascun ruolo eseguito a mano, un’entità Plugin nel catalogo del workspace e una build che il plugin rifiuta.
  • compatibility — come vengono versionati i kit per plugin: che cosa possono cambiare una release di patch e una release minore di un kit, e che cosa permette a un plugin già compilato di continuare a caricarsi.