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à.
| Livello | Tipi di entità | Quando adottarli |
|---|---|---|
| Livello 1 — la superficie minima indispensabile | Aggregate, Component, Recipe, Manifest, Release | Giorno 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 ruoli | Feature, FeatureRecipe, Plugin | Giorno 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 Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | Giorno 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
- Come usare questo riferimento
- Convenzioni di denominazione
- Panoramica del riferimento alle entità
- Livello 1: aggregate, component, recipe, manifest, release
- Livello 2: feature, featurerecipe, plugin
- Livello 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Trasversale: workload (tipo del compilatore di proprietà della piattaforma, consumato all’interno di
workload:della Recipe)
- Panoramica del vocabolario
- Riferimento del vocabolario: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Panoramica dei template
- Riferimento dei template: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Panoramica dei Providers
- Riferimento dei Providers: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Panoramica della CLI
- Riferimento della CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import e il file delle risposte dell’importazione, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Panoramica degli errori
- Riferimento degli errori: fatal-halts, warnings, sentinels, error-translation
- Panoramica degli esempi
- Riferimento degli esempi: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; workspace eseguibili: Esempi eseguibili
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-injectoregovernance/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à
Pluginnel 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.