Tassonomia dei dati e composizione
La tassonomia unificata dei dati e le regole di composizione
Per stabilire uno schema prevedibile ed eliminare l’attrito cognitivo, la piattaforma utilizza esattamente cinque parole chiave universalmente comprese e una struttura YAML rigorosamente basata su mappe (dizionari), con mappe anziché array annidati alla radice della struttura.
1. Lo standard delle mappe a 5 parole chiave e la simmetria totale degli schemi
Il vocabolario strutturale diretto: una regola fondamentale della progettazione degli schemi è che le strutture dati radice devono essere parole chiave singole e strutturali. Sebbene l’uso di espressioni colloquiali in inglese (come depends_on o runs_within) possa rendere un DSL YAML più naturale da leggere per uno sviluppatore, introduce complessità strutturale quando si mappano quelle chiavi in template Go programmatici. Per mantenere una mappatura diretta 1:1 delle variabili e prevenire la frammentazione del linguaggio specifico di dominio (DSL), gli schemi JSON delle entità principali del catalogo (Component, Feature) esprimono una simmetria strutturale quasi totale, guidata dallo stesso insieme centrale di parole chiave strutturali usato in tutti gli slot di istanza scritti. Le Features di credenziale (etichettate feature.aggrega.ai/kind: secret) condividono questo identico paradigma — non esiste uno schema separato per i secret.
parameters(il contratto dell’ambiente globale)- Ambito: definito alla radice dell’
Aggregate; soddisfatto dallaRelease(CI/CD) inline sottoparameters:oppure tramiteparameters: { $import: <path> }che punta a un file di parametri esterno. - Significato: argomenti esterni che modificano dinamicamente lo stato cognitivo o logico dell’applicazione tra gli ambienti (ad es. cambiare
workers: 2inworkers: 10). Supporta un contratto tipizzato (vedi data-pillars per la sintassi completa del contratto tipizzato) validato prima dell’interpolazione. Per i flussi di lavoro GitOps che mantengono i valori dei parametri in un file separato, la Release usa la forma$import:; il compilatore carica il contenuto del file e sostituisce la mappa inlineparameters:. La stratificazione su più file si esprime tramite cateneextends:della Release.
- Ambito: definito alla radice dell’
values(l’intento cognitivo - di proprietà dello sviluppatore)- Ambito: usato in modo uniforme all’interno di
componentse dei relativi collegamentifeaturesnell’Aggregate, Features di credenziale incluse. - Significato: lo stato cognitivo centrale, la logica di business e la configurazione operativa. Opaco per il compilatore Go ma validato rigorosamente dalla dichiarazione unificata
schema:del catalogo (forma compatta o JSON Schema 2020-12).
- Ambito: usato in modo uniforme all’interno di
uses(la topologia strutturale - stato dichiarativo)- Ambito: usato in modo uniforme all’interno di
componentse dei relativi collegamentifeaturesnell’Aggregate, Features di credenziale incluse. - Significato: un’affermazione dichiarativa di fatto che definisce archi di rete e dipendenze (ad es. «Questo agente usa questo database»). Analizzata nativamente dal compilatore Go per disegnare il grafo della rappresentazione intermedia (IR). Validata dalla dichiarazione unificata
usesSchemadel catalogo per imporre la sicurezza dei tipi tra nodi.
- Ambito: usato in modo uniforme all’interno di
infra(la realtà fisica - di proprietà di Ops)- Ambito: usato in modo uniforme all’interno dei
componentsdi un confine e dei relativi collegamentifeaturesnellaRelease. - Significato: l’impronta fisica e il dimensionamento meccanico iniettati durante il Late Binding (ad es.
cpu_limit: "4",port: 5432). Le istanze di componente dell’Aggregate e i relativi collegamentifeaturesnon includono un campoinfrae, insieme aadditionalProperties: false, rifiutanoinfradurante la validazione dello schema. Validato dalla dichiarazione unificataschema:del catalogo.
- Ambito: usato in modo uniforme all’interno dei
inject(il contratto di consegna - comando imperativo)- Ambito: usato su un’istanza di componente, all’interno di definizioni esplicite di destinazione in
usese sullefeaturescollegate, Features di credenziale incluse. - Significato: un comando esplicito e imperativo che detta l’intento della consegna (ad es. «Compilatore, inietta questo valore mappato come variabile d’ambiente»). Stabilisce il contratto astratto (
env,file,argo meccanismi personalizzati) per un output fisico, un endpoint risolto o una credenziale recuperata, mentre la meccanica fisica di come esattamente quel montaggio viene eseguito è delegata interamente alla Recipe di Ops sottostante. Ogni meccanismo è un elenco di voci ([{ in: API_HOST, from: "host" }]), ciascuna delle quali nomina il proprio identificatore locale conin:e porta esattamente uno trafrom:evalue:.
- Ambito: usato su un’istanza di componente, all’interno di definizioni esplicite di destinazione in
.context(la pipe generica dei metadati)- Ambito: iniettato silenziosamente dal compilatore nei template della
Recipedi Ops. - Significato: porta ciò che il compilatore ha assemblato per il nodo a partire dal resto del grafo (come
.context.uses), passato direttamente al motore di template di Ops.
- Ambito: iniettato silenziosamente dal compilatore nei template della
La realtà della mappatura 1:1
Sostituendo le preposizioni colloquiali con parole chiave infrastrutturali rigorose, si ottiene una mappatura 1:1 diretta. L’ingegnere Ops non deve tradurre la grammatica; si limita a fare riferimento alle chiavi esatte scritte dallo sviluppatore.
Forme strutturali: mappe alla radice, array nei payload. I blocchi di topologia radice — components, features, aggregates, subsystems, boundaries — sono mappe YAML le cui chiavi, scritte dall’utente, fungono da ID di istanza stabili. Gli array non sono validi in queste posizioni; la chiave della mappa è l’identità che il compilatore usa per i riferimenti incrociati (target: my-db), la costruzione dei nodi del grafo e la risoluzione del Manifest. All’interno dei blocchi di payload opachi (values, infra, parameters), gli array sono pienamente consentiti — gli sviluppatori possono scrivere tools_allowed: ["sql", "web"] o hostnames: ["stripe.com", "twilio.com"] nei values di un Component. Lo schema dell’Aggregate dichiara questi blocchi di payload come additionalProperties: true, quindi sono opachi per il compilatore Go e validati interamente dalla dichiarazione schema: incorporata nel catalogo. Questo colloca la volatilità dei framework (nuove forme di API di IA, nuovi formati di payload cloud-native) nel dominio del catalogo, dove può evolvere in modo indipendente, mentre il compilatore Go resta limitato a chiavi indirizzabili alla radice strutturale.
2. I flussi di informazioni: chi, quando e per cosa?
Per prevenire collisioni nello spazio dei nomi dei template e la fuoriuscita involontaria di configurazioni dell’infrastruttura fisica nella logica cognitiva dell’applicazione, l’architettura separa esplicitamente i dati in sei flussi distinti:
- Flusso 1: l’iniezione ambientale (
parameters): la pipeline CI/CD inietta le realtà del deployment. Il compilatore valida ogni valore fornito dalla Release rispetto al contratto tipizzatoparameters:, quindi interpola le variabili di template Go risolte prima di eseguire la validazione dello schemavalues:a valle.- Uso consigliato: i
parameterssono riservati alla logica cognitiva dell’applicazione che varia tra gli ambienti (ad es.LOG_LEVEL=debug,ENABLE_BETA=true). Il dimensionamento operativo e gli aspetti dell’infrastruttura fisica — repliche, limiti di CPU, ARN di AWS, hostname di ingress — passano attraverso il bloccoinfradellaReleasee gli overlay dei confini, mantenendo l’Aggregatedello sviluppatore concentrato sull’intento applicativo. - Via d’uscita pragmatica: per team più piccoli, prototipazione rapida o integrazioni CI/CD legacy in cui una separazione rigorosa non è praticabile, i
parameterspossono trasportare configurazioni globali dell’ambiente attraverso lo stack. Il compilatore accetta tutto ciò che supera la validazione dello schema; la raccomandazione precedente è un contratto sociale, non una regola del compilatore.
- Uso consigliato: i
- Flusso 2: intento cognitivo dell’applicazione (
valuesnei Components): definisce la logica intrinseca dell’applicazione. La dichiarazioneschema:del Component (forma compatta o JSON Schema 2020-12) fornisce un controllo dei tipi e una validazione rigorosi per questo payload, offrendo agli sviluppatori un feedback «Shift-Left» immediato e garantendo che le configurazioni richieste corrispondano all’API dell’infrastruttura sottostante. - Flusso 3: intento operativo della Feature (
valuesnelle Features): nell’Aggregate, lo sviluppatore richiede le capacità infrastrutturali il cui comportamento è intento applicativo e interroga credenziali rigorosamente tipizzate, senza modificare il codice interno. Una Feature i cui input sono tutti operativi non portavaluesdello sviluppatore: le operazioni la collegano nella Release, con il suoinfra(Flusso 4). - Flusso 4: dimensionamento dell’infrastruttura fisica (
infra): scavalcando completamente lo sviluppatore, il dimensionamento fisicoinfraviene proiettato esplicitamente dallaReleasespecifica dell’ambiente direttamente sui Components con ambito locale e sulle relative Features collegate, Features di credenziale incluse. Per evitare collisioni nella validazione degli schemi chiusi dovute alla diffusione letterale di dizionari, il dimensionamentoinfraè rigorosamente localizzato al componente esplicito che lo indirizza. Questo mantiene limiti di calcolo, repliche e requisiti meccanici di risorse nel dominio Ops. - Flusso 5: annotazioni a cascata (metadati contestuali): i dati contestuali ampi (come domini operativi, namespace o codici di fatturazione) sono gestiti tramite annotazioni a cascata, evitando l’inquinamento dovuto alla diffusione di
infra. Sono segregati in contenitori in base alla loro origine, e l’uso previsto di ciascun contenitore descritto di seguito è un contratto sociale: un template di Recipe può leggerli tutti e tre, e il compilatore non impone la separazione (vedi labels-and-annotations):.context.annotations.release(confini del Dominio 4): usate esclusivamente per governare le realtà fisiche. Ops instrada esplicitamente queste annotazioni in campiinfralocali rigorosi tramite template Go (ad es. mappando un namespace regionale su un componente di calcolo)..context.annotations.aggregate(sottosistemi del Dominio 1): usate esclusivamente per governare la logica cognitiva e operativa. Queste annotazioni sono instradate esplicitamente nei payloadvaluesdel componente (ad es. propagando a cascata un codice di fatturazione del team fino a una configurazione dell’applicazione)..context.annotations.catalog(catalogo del Dominio 2): tratti intrinseci immutabili scritti dall’architetto, usati principalmente per la valutazione programmatica delle policy Wasm.
- Flusso 6: la pipe dei metadati (
.context): applica i requisiti aziendali globali (tag SOC2) direttamente ai template dell’infrastruttura fisica.
3. Astrazione di rete: la convenzione «Zero-Port»
- La best practice: gli sviluppatori dovrebbero omettere le porte dall’
Aggregate. La Recipe di Ops gestisce dinamicamente l’instradamento interno. - La via d’uscita: se il codice interno di un’applicazione non può essere modificato, l’architetto di piattaforma espone esplicitamente un campo
portnella dichiarazioneschema:. Nota architetturale: la convenzione «Zero-Port» è l’esempio più evidente della più ampia separazione delle responsabilità della piattaforma. Questa stessa identica filosofia — tenere la meccanica fisica lontana dallo sviluppatore — si applica alle richieste di CPU, ai limiti di memoria, ai domini operativi e al dimensionamento dei dischi. Ogni volta che un vincolo dell’infrastruttura fisica deve filtrare nel payload applicativo dello sviluppatore (a causa di codice legacy o di requisiti hardware rigorosi), deve sempre essere governato da una «via d’uscita» esplicita nella dichiarazioneschema:dell’architetto, la dichiarazione rispetto alla quale viene validato il payload dello sviluppatore.
Il nome «Zero-Port» designa questa convenzione; il principio si generalizza a qualsiasi vincolo dell’infrastruttura fisica che un’applicazione legacy codifica in modo fisso. Lo schema seguente usa tcp_keepalive_seconds come esempio svolto — una temporizzazione di kernel/rete che l’applicazione si aspetta al livello dei socket — perché si colloca chiaramente sull’asse della fuoriuscita di infra.
Lo schema (Dominio 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }Lo YAML dello sviluppatore (Dominio 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaComportamento del compilatore: il compilatore Go passa tcp_keepalive_seconds: 120 nel grafo IR. La Recipe di Ops legge poi {{ .values.tcp_keepalive_seconds }} per configurare la spec del pod Kubernetes o l’idle timeout del load balancer del cloud provider, colmando così il divario legacy senza violare lo schema.
4. Il contratto di iniezione e la mappa pre-risolta
Tra le cinque parole chiave strutturali, inject ha una forma diversa dalle altre. parameters, values, uses e infra sono stato dichiarativo — lo sviluppatore scrive fatti su che cosa è l’applicazione e da che cosa dipende. inject è un comando imperativo — lo sviluppatore detta come un valore deve essere consegnato al container in esecuzione, mappando sorgenti di dati astratte (le chiavi provides di una destinazione, i valori propri del componente, la risposta del vault di una Feature di credenziale) su meccanismi di consegna concreti (env, file, arg o un meccanismo personalizzato dichiarato dal Component).
Questo disaccoppiamento è strutturale. L’Aggregate dello sviluppatore dice «inietta l’host del database come variabile d’ambiente DB_HOST» senza nominare l’indirizzo fisico del database, il percorso del vault nell’archivio dei secret o il formato degli hostname del cloud provider. La Recipe di Ops riceve la stringa risolta tramite .context.inject e la consuma senza dover scrivere la catena di lookup.
La mappa pre-risolta. Durante il rendering, il compilatore risolve ogni sorgente di inject — i letterali di self-inject e i riferimenti from: rispetto ai provides del componente stesso, i riferimenti tra componenti tramite uses[].inject, le intercettazioni injectMapping della FeatureRecipe — in un unico dizionario appiattito in .context.inject. Quando viene eseguito il template valuesMapping della Recipe di base, ogni chiave di inject ha già il suo valore stringa finale. Le Recipes iterano direttamente sulla mappa ({{ range $k, $v := .context.inject.env }}) senza percorrere la catena di risoluzione.
I nomi che lo sviluppatore dà ai valori propri del componente. Dove il Component dichiara spec.inject, il blocco inject: dello sviluppatore sceglie i nomi con cui i valori propri e i provides del componente raggiungono il canale di consegna. Il compilatore comunica alla Recipe, in .context.self_inject, l’unico valore proprio che il template di ciascuna voce legge — per meccanismo, ogni nome associato a provides.<key>, a values.<key> per un template che legge esattamente un valore proprio e nient’altro, oppure a una stringa vuota — nella forma che i nomi di una connessione assumono in .context.uses.<alias>.inject. La convenzione del catalogo della libreria standard per una Recipe che esegue l’immagine dello sviluppatore è trattare come valori predefiniti i nomi che altrimenti sceglierebbe per i valori propri del componente, fornendo un valore proprio con il suo nome predefinito solo quando nessuna voce lo associa già. Si tratta di una convenzione del catalogo, non di una regola del compilatore: un catalogo aziendale può fornire i valori propri dei suoi componenti come preferisce. Il compilatore legge la mappa dal testo scritto dallo sviluppatore e non attribuisce alcun significato ai nomi.
La specifica completa del contratto di iniezione — semantica del contesto a doppio stato, regole di collisione delle chiavi, modello di intercettazione della FeatureRecipe ed esempi svolti — si trova in topology-triad.
5. Il motore di template (DX di Ops)
Gli ingegneri di Platform Ops scrivono i template di traduzione e hanno bisogno di tutta la potenza dei template infrastrutturali standard, senza un linguaggio di template proprietario. I template di Aggrega sono Go text/template:
- Nessuna stringa «magica»: il compilatore preserva le chiavi esatte della mappa dello sviluppatore. Ops accede alle feature in sicurezza tramite l’indicizzazione standard delle mappe Go:
{{ (index .features "public-route").infra.hostname }}. - La libreria Sprig: il compilatore registra nativamente la libreria Sprig, standard di Helm, offrendo accesso immediato a pipeline come
| default,| quotee| toYaml. - Frammenti di MappingLibrary: un frammento di mapping riutilizzato da più Recipes risiede in una MappingLibrary e viene incluso in ciascuna Recipe con
$import:. Gli helper dei template dei chart di Helm (include,tpl,required,warn) non sono registrati; sprig-functions elenca quelli che lo sono.
6. Regole di composizione: Aggregates, sottosistemi e Components
- Raggruppamento logico (l’array
subsystems): gli sviluppatori possono applicare metadati logici (proprietà del team, label di conformità) e feature trasversali a decine di componenti contemporaneamente usandosubsystems. I sottosistemi agiscono come cartelle ricorsive sul piano logico/dell’intento, propagando a cascata leannotationsverso il basso nel contenitore.context.annotations.aggregatee collegando feature a tutti i componenti contenuti senza imporre confini fisici. Le feature a livello di sottosistema seguono lo stesso schema delle feature a livello di componente (supportandotype,values,uses,inject) perché si trovano nel Dominio 1 (intento dello sviluppatore). Durante la finalizzazione del grafo il compilatore appiattisce le feature del sottosistema nell’elenco delle feature di ciascun componente contenuto, posizionandole dopo le feature proprie del componente e prima di qualsiasi feature collegata dalla Release nell’ordine di esecuzione.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Gli Aggregates compositi sono SUPPORTATI (il pattern dei moduli): gli Aggregates fungono sia da Aggregate radice costruito da una Release sia da moduli riutilizzabili. Un Aggregate padre può dichiarare un Aggregate figlio esattamente come un componente, passandogli i
parameters. Per evitare un accoppiamento stretto, gli Aggregates figli espongono un contrattoexportedComponents:, che stabilisce un nome di interfaccia pubblica stabile. Il padre raggiunge i componenti del modulo solo attraverso questa interfaccia: una destinazioneuses:nomina il modulo e uno dei suoi alias esportati, e il compilatore collega l’arco al componente interno nominato dall’alias, mentre una destinazione che entra in un modulo con qualsiasi altro nome arresta la build, indicando il modulo e gli alias che esporta. Un modulo può a sua volta riesportare il componente esportato di un modulo annidato sotto il proprio nome di interfaccia — eventualmente rinominandolo — e il compilatore risolve tale catena di riesportazione in modo transitivo fino al nodo interno sottostante, così i moduli si compongono a qualsiasi profondità senza che un padre debba sapere quanto in profondità sia annidata la destinazione. Una destinazione che non si risolve in alcun nodo interno arresta comunque la build in modo esplicito, e una catena di riesportazione che si richiude su sé stessa viene rifiutata anziché seguita all’infinito.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
I Components non possono contenere sotto-componenti: i Components sono elementi costitutivi atomici. La composizione avviene a livello di Aggregate tramite sottosistemi e sotto-aggregati. Se un’applicazione richiede più container fisici (come un’API + un sidecar), quell’annidamento fisico vive all’interno del template della Recipe di Ops, non nella definizione del Component.
-
Un servizio coerente per Component — il confine del singolo workload: un Component modella un servizio coerente — un singolo servizio esposto, oppure il workload o i workload di un servizio insieme ai suoi workload ausiliari solo interni. La sua label
component.aggrega.ai/typeindica la forma operativa di quell’unico servizio. Più workload fisici all’interno di un singolo Component vanno bene quando formano un unico prodotto coerente senza parti utilizzabili in modo indipendente: un servizio il cui chart esegue un controller più un webhook più un injector resta un solo Component. Il criterio non è la presenza di più workload; è l’utilizzabilità indipendente.Il confine si traccia dove un bundle contiene qualcosa che un altro componente potrebbe sensatamente usare (
use) da solo — in particolare infrastruttura esterna come un database, una cache o un message broker che Aggrega modella già come Component a sé. Un bundle del genere non è un solo Component; è un modulo sotto-aggregato — il patternspec.aggregates+exportedComponentsmostrato sopra — che compone un Component per servizio, in modo che ogni servizio sia un nodo indirizzabile con il proprio tipo, i propri archi e la propria superficie di policy e di scalabilità.L’euristica, formulata come regola netta: il chart contiene qualcosa che un altro componente potrebbe sensatamente usare da solo, o per cui Aggrega ha già un Component? Se sì, modellalo come stack — un modulo sotto-aggregato che compone Components per servizio. Se serve sempre e solo questo unico servizio, modellalo come un solo Component.
Racchiudere un intero prodotto multi-servizio in un singolo Component opaco è un antipattern documentato. Il compilatore è privo di opinioni e lo accetterà — renderizza tutto ciò che supera la validazione dello schema — ma la libreria standard compone invece Components per servizio in un modulo, perché un involucro monolitico nasconde i servizi modellabili in modo indipendente alla topologia, al selettore e alle policy e alla scalabilità per servizio. Questa disciplina di granularità è un contratto sociale — vedi
../language-reference/vocabulary/social-contracts.md(granularità del Component).
7. L’ambito predefinito — rivelazione progressiva del raggruppamento
subsystems (nell’Aggregate) e boundaries (nella Release) sono i costrutti di raggruppamento, ma uno sviluppatore non deve dichiararli fin dall’inizio. Ogni entità offre due forme di scrittura, e sono mutuamente esclusive: scrivere i componenti raggruppati sotto ambiti con nome, oppure scrivere i componenti direttamente al primo livello — mai entrambe le cose insieme. Un documento che dichiara sia components di primo livello sia ambiti con nome si arresta al caricamento con un errore di envelope.
Per la forma piatta (components di primo livello), il compilatore sintetizza un vero ambito default al caricamento e vi raccoglie i componenti di primo livello, così ogni passaggio successivo vede una struttura uniforme dotata di ambiti. L’ambito sintetizzato non è un contenitore nascosto: è un nodo autentico dell’IR, marcato con la sua provenienza, distinguibile da un ambito che uno sviluppatore chiama esplicitamente default. È nascosto solo dove l’autore legge i percorsi: la diagnostica e l’indirizzamento mostrano il percorso con la forma della radice .spec.components[…] che lo sviluppatore ha effettivamente scritto.
- Aggregate piatto (componenti di primo livello): i componenti si scrivono sotto
spec.components, senzasubsystems. Il compilatore li raccoglie in un sottosistemadefaultsintetizzato al caricamento. Le annotazioni di ambito del sottosistema e le feature a livello di sottosistema si applicano solo ai sottosistemi dichiarati; la forma piatta non ne porta nessuna. - Release piatta (componenti di primo livello): i componenti si scrivono sotto
spec.components, senzaboundaries. Il compilatore li raccoglie in un confinedefaultsintetizzato il cui output è piatto — gli artefatti finiscono direttamente sottodist/(per provider:dist/compose/,dist/helm/, …), senza alcun segmento con il nome del confine. È il caso più semplice:aggrega buildsu un target Compose piatto o a cluster singolo, senza dare nomi ai confini. (Un confine che uno sviluppatore dichiara e chiamadefaultè un normale confine con nome e, senza un propriodirectory:, emette indist/boundaries/default/come qualunque altro.) - Il percorso di crescita: quando un’architettura piatta cresce fino a richiedere un raggruppamento (namespace diversi, raggruppamenti logici separati, deployment su più confini), lo sviluppatore sposta i componenti di primo livello in
subsystemsespliciti, oppure Ops introduceboundariesespliciti. Poiché le due forme sono mutuamente esclusive, si tratta di un passaggio dalla forma piatta a quella con ambiti — non di una combinazione delle due — e l’identità dei nodi si conserva attraverso la transizione.
Il motivo è la rivelazione progressiva: imporre un raggruppamento obbligatorio per casi d’uso banali (una demo con un solo servizio, un rapido prototipo locale) crea attrito inutile. Il test di onboarding «da zero a funzionante in 10 minuti» richiede che uno sviluppatore possa scrivere un Aggregate minimo con un componente, un Manifest e una Release e ottenere un output funzionante senza dover prima capire sottosistemi o confini. L’ambito predefinito è la rampa d’accesso; gli ambiti dichiarati sono dove va un’architettura man mano che cresce.
8. Vincoli architetturali e pattern consigliati
Le voci seguenti sono un pattern consigliato e cinque vincoli. Gli schemi impongono i vincoli 4 e 5 — la Release non ha un blocco values, e l’istanza di componente di un Aggregate non ha una chiave labels; gli altri sono convenzioni che il compilatore non verifica.
-
Pattern consigliato: sollevamento dei parametri tramite stringhe template
- Esempio: lo sviluppatore scrive
workers: {{ .parameters.env_workers }}nel proprio bloccovalues, senza virgolette, così il valore arriva come l’intero che è stato dichiarato. - Perché: se l’Aggregate dichiara
env_workerscome parametro tipizzato (type: integer), il compilatore valida prima il valore fornito dalla Release rispetto al contratto. La validazione del contratto dei parametri avviene prima dell’interpolazione; l’interpolazione avviene prima della validazione dello schemavalues:circostante. Questo preserva la riusabilità dell’Aggregate: Ops fornisce l’intero tramite iparameters:dellaRelease, il compilatore lo valida rispetto alla dichiarazione tipizzataparameters:, sostituisce il valore risolto nel documento e la dichiarazioneschema:del Component valida con successo l’intero risultante.
- Esempio: lo sviluppatore scrive
-
Vincolo 1: le credenziali sono allegati, non valori
- Pattern sconsigliato: lo sviluppatore scrive
values: { password: "123" }su un componente. - Perché: la convenzione della libreria standard è che una credenziale venga richiesta come allegato sotto
features:, indicando untypedi Feature per credenziali (uno etichettatofeature.aggrega.ai/kind: secret) e usando ivaluespropri di quell’allegato per descrivere la query verso un archivio di segreti. È una convenzione, non un controllo del compilatore: il compilatore non interpreta il significato di una foglia divaluese trasporta alla lettera un letterale inline. È la superficie degli allegati a rendere disponibile e tipizzata la forma scritta correttamente.
- Pattern sconsigliato: lo sviluppatore scrive
-
Vincolo 2: Components agnostici rispetto alle capacità
- Pattern non supportato: l’architetto scrive
aws_instance_type: stringnella dichiarazioneschema:del Component. - Perché: per convenzione i Components sono agnostici rispetto alle capacità. I target hardware fisici risiedono nelle Recipes di Ops o in annotazioni
.contextgeneriche, non nella logica applicativa cognitiva di base.
- Pattern non supportato: l’architetto scrive
-
Vincolo 3: logica condizionale sui metadati
- Pattern non supportato: Ops scrive
{{ if eq .context.labels.gpu "true" }}in unaRecipeper cambiare radicalmente la strategia di deployment. - Perché: il canale
.contextaggira la validazioneschema:di ciascun pilastro. Affidarsi a etichette non validate per la logica di base dell’infrastruttura rende fragile la piattaforma. L’oggetto.contexttrasporta tag di metadati (ad es. fatturazione, SOC2); l’instradamento strutturale appartiene ai pilastri validati dallo schema.
- Pattern non supportato: Ops scrive
-
Vincolo 4: la Release non può sovrascrivere i valori dello sviluppatore
- Pattern non supportato: Ops tenta di sovrascrivere la logica cognitiva di uno sviluppatore (ad es. cambiando
workers: 4inworkers: 10) dallaRelease. - Perché: l’
Aggregateè l’unica fonte di verità per l’intento dello sviluppatore. Se un valore è scritto in modo fisso nell’Aggregate, è immutabile tra gli ambienti. Se un valore deve cambiare in base all’ambiente, lo sviluppatore usa il sollevamento dei parametri. Lo schema dellaReleaselo impone vietando i blocchivalues, limitando Ops a soddisfare il contrattoparameterse a definire l’infrafisica.
- Pattern non supportato: Ops tenta di sovrascrivere la logica cognitiva di uno sviluppatore (ad es. cambiando
-
Vincolo 5: etichette a livello di istanza nell’Aggregate
- Pattern non supportato: lo sviluppatore scrive
labels: {}su un’istanza di componente dentro l’Aggregate. - Perché: le etichette sono tratti immutabili a livello di catalogo scritti dall’architetto della piattaforma — l’identità semantica che leggono i motori di policy e i selettori. La Release instrada i componenti verso i confini tramite un targeting esplicito per ID basato su mappe (
components: { "my-agent": {} }), che preserva la possibilità di annidareinfrae override delle feature per ogni componente senza mescolare la paternità delle etichette nell’Aggregate dello sviluppatore.
- Pattern non supportato: lo sviluppatore scrive
9. Il perimetro di sicurezza & i guardrail espliciti sull’egress (destinazioni fuori perimetro)
Nessuna applicazione esiste nel vuoto. Un’architettura Aggrega compilata rappresenta un grafo mappato rigorosamente. Tuttavia, i moderni sistemi di IA interagiscono costantemente con entità esterne a questo perimetro compilato — come gli LLM SaaS pubblici (Anthropic, OpenAI), le API pubbliche generiche (Stripe, Twilio) o i database brownfield legacy (Oracle on-premise).
Per integrare in modo sicuro questi sistemi esterni, Aggrega separa rigorosamente il confine di sicurezza dalla meccanica di esecuzione. Il confine di sicurezza è governato dalla regola universale del Component e dal guardrail esplicito sull’egress.
1. La regola universale del Component
Se un’applicazione interagisce con un’entità — che sia un database locale, una risorsa cloud gestita, un LLM SaaS o un endpoint di API pubblica generica — quell’entità DEVE essere dichiarata come Component distinto nell’Aggregate. Questa regola è una convenzione: il compilatore non può vedere una chiamata che l’applicazione effettua, quindi nulla la verifica.
Trattando le API SaaS esterne e i database legacy come nodi di prima classe nel grafo della rappresentazione intermedia (IR), gli sviluppatori ottengono la possibilità di associare configurazioni di proxy Zero-Trust direttamente alla chiamata in uscita. Per esempio, modellando l’API di Stripe come nodo distinto, uno sviluppatore può associarle una feature header-injector, garantendo che la configurazione generata impedisca all’agente chiamante di tenere il token grezzo dell’API nella propria memoria.
2. Il guardrail esplicito sull’egress (conformità dell’infrastruttura)
Invece di affidarsi a una logica fissa nel compilatore per governare l’egress di rete, Aggrega delega interamente la sicurezza del perimetro ai motori di policy agnostici dell’azienda e ai plugin di rendering Wasm. Questo garantisce che le configurazioni generate siano rigorosamente conformi alle approvazioni esplicite dell’egress.
- L’hook del catalogo (Dominio 2): quando un architetto definisce un componente SaaS pubblico (ad es.
core/external-service), vi associa un’etichetta aziendale immutabile (ad es.security.enterprise.com/zone: "untrusted-external"). - Il guardrail di policy (in fase di compilazione): prima che venga generata qualsiasi configurazione, il motore di policy OPA o Kyverno valuta il grafo. L’azienda scrive una regola semplice: «Se un nodo interno si connette a un nodo etichettato
untrusted-external, l’ID di quel nodo di destinazione deve essere elencato esplicitamente nell’arrayparameters.approved_egressdell’ambiente.» Se uno sviluppatore tenta di instradare dati verso una destinazione esterna non approvata, il motore di policy arresta la build. - La generazione della configurazione (al momento del rendering): se la policy viene superata, la regola di egress viene renderizzata a partire da ciò che l’operatore ha collegato. La Feature
core/egress-allowlist, collegata al componente chiamante nella Release, renderizza suhelmunaNetworkPolicyKubernetes per ciascun workload che quel componente renderizza, ammettendo l’egress solo verso i propri pod, verso i pod delle destinazioni dei suoi archiusessulle porte che quei pod dichiarano, verso il DNS del cluster e verso gli intervalli di indirizzi che il collegamento elenca per una destinazione che il cluster non esegue, come un’API SaaS pubblica. La build si interrompe a meno che la Release non affermi, coninfra.control_plane_present: true, che il plugin di rete del cluster applica le network policy, e si interrompe indicando qualsiasi connessione esterna di questo tipo per cui non sia elencato alcun intervallo di indirizzi; sucompose, che non ha network policy, il collegamento interrompe la build. Lo sviluppatore non scrive mai una regola di firewall.
Questo garantisce — tramite un ruolo di verdetto di governance che valuta la topologia dichiarata — che l’infrastruttura dichiarata esplicitamente sia conforme alla policy di egress senza che il compilatore Go di base debba capire che cosa significhi «esterno». (Nota: un vero egress zero-trust si basa sul fatto che il cluster di destinazione esegua a runtime una CNI Default Deny; le configurazioni generate si limitano a mappare le eccezioni autorizzate).
Un Component per ogni servizio esterno
Ogni servizio esterno è dichiarato come componente distinto, non raggruppato in un array a più destinazioni. Se un’applicazione chiama cinque diverse API di terze parti, lo sviluppatore dichiara cinque componenti core/external-service distinti. È questa dichiarazione per servizio a permettere ai motori di policy e ai plugin Wasm di indirizzare individualmente ogni destinazione in uscita — associando a ciascuna dipendenza esterna policy di egress diverse, feature di proxy diverse o hook di osservabilità diversi.
Separare la sicurezza dall’esecuzione (lo scenario «brownfield»)
È fondamentale notare che l’etichetta semantica (ad es. untrusted-external) determina la policy di sicurezza di rete, non l’esecuzione. È indipendente dal fatto che Aggrega renderizzi artefatti che forniscono la risorsa.
- Scenario A (API SaaS pubblica): etichettata
untrusted-externalnel catalogo (attiva i guardrail di egress della policy). Realizzata da un workload di riferimento (nessuna risorsa di calcolo fornita; vedi §10). - Scenario B (database legacy interno): etichettato
internal-trusted(aggira i guardrail di egress, resta dentro la VPC). Realizzato da un workload di riferimento (nessuna risorsa di calcolo fornita; vedi §10). - Scenario C (database self-hosted): etichettato
internal-trusted. Eseguito tramite il plugin renderer Helm (fornito fisicamente come StatefulSet di Kubernetes).
10. Servizi che la build non fornisce: Workloads di riferimento
Quando un’applicazione interagisce con un database legacy on-premise o con un’API SaaS pubblica (come Stripe), la regola universale del Component stabilisce che queste entità esterne devono essere dichiarate come componenti distinti nell’Aggregate. Tuttavia, Aggrega non deve tentare di generare per esse un artefatto fisico di Pod Kubernetes o di istanza AWS RDS.
La Recipe che realizza un componente di questo tipo dichiara un Workload con form: reference: un endpoint — un host o un URL — facoltativamente una port, e nessun container. Il compilatore li fa passare entrambi come stringhe di puntatori deterministici e non li risolve mai. Ciò che un provider renderizza per un Workload di riferimento spetta al provider stesso: helm emette un Service ExternalName che porta l’host dell’endpoint, così che i workload nel cluster possano raggiungere un servizio il cui endpoint è un nome DNS tramite un nome stabile interno al cluster; compose non renderizza nulla per esso. Kubernetes tratta un externalName come un nome DNS, quindi un endpoint scritto come indirizzo IP viene raggiunto all’indirizzo che un consumatore riceve, anziché tramite il Service.
Su entrambi i provider, i provides: della Recipe raggiungono ogni consumatore tramite .context.uses e il contratto inject esattamente come quelli di un componente fornito. Il collegamento di un consumatore quindi non cambia quando la sua destinazione passa da fornita a referenziata: cambia solo la Recipe su cui il Manifest mappa la destinazione.
La pipeline di esecuzione passo per passo
1. Dominio 1 (l’Aggregate): l’intento dello sviluppatore Lo sviluppatore richiede un database Oracle legacy. Non gli interessa dove risieda; stabilisce solo che il suo agente chiamante si aspetta di ricevere la stringa di connessione come variabile d’ambiente. Poiché l’IP è statico e noto in anticipo, lo passa tramite i parametri.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Dominio 4 (il Manifest): l’instradamento Ops mappa il tipo di database legacy sulla Recipe che ne formatta la stringa di connessione. Il Manifest nomina una Recipe e nient’altro; la Recipe che nomina dichiara un Workload con form: reference, ed è quella forma a impedire al nodo di fornire risorse di calcolo. L’instradamento resta perfettamente piatto e prevedibile perché la mappa ha esattamente una forma, qualunque sia il target.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Dominio 3 (la Recipe di riferimento): strutturare il passaggio di consegne L’ingegnere Ops scrive la Recipe. Questa costruisce la stringa di connessione primary_endpoint a partire dai values dello sviluppatore nel suo blocco locals, la pubblica sotto provides e dichiara un Workload di riferimento che punta all’host del database.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Esecuzione del compilatore al rendering (il passaggio di consegne)
- Il compilatore valuta la Recipe di
legacy-oracle. Per una Release che forniscelegacy_oracle_ip: "10.0.4.55", il suoprimary_endpointèoracle://10.0.4.55:1521/PROD_DB. - Su
helm, il Workload di riferimento renderizza un Service ExternalName,legacy-oracle, conexternalName: 10.0.4.55e porta1521; sucomposenon renderizza nulla. - Il compilatore renderizza poi la Recipe di
my-agent. Il suo canale.context.usesporta iprovidesdel nodo Oracle, e il contratto di iniezione ha già risoltoORACLE_DSNrispetto a essi.
5. Dominio 3 (la Recipe chiamante): adempiere al contratto La ricetta Helm standard del worker Python legge la mappa di iniezione che ha ricevuto, esattamente come farebbe per un database fornito dalla build.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Piping tra pilastri tramite schema bridge: collegare l’intento all’infrastruttura
Vedi inheritance-and-interface per il pattern schema-bridge che espone in modo sicuro le manopole dell’infrastruttura specializzata tramite componenti figli — un campo values: rivolto allo sviluppatore, dichiarato nello schema: del Component, che il template valuesMapping: della Recipe convoglia nell’output renderizzato con la forma di infra:.
12. Provisioning greenfield («Aggregates di piattaforma»)
Una trappola ricorrente nel platform engineering è costringere il router (il file Release) a gestire il pesante provisioning dei cluster al Day-0 (ad es. avviare un nuovo cluster AWS EKS prima di distribuirvi l’app). Questo crea file di instradamento lunghi e difficili da leggere.
Aggrega gestisce il problema con il principio «tartarughe fino in fondo». Lo schema della Release non ha alcun blocco per installare l’infrastruttura; il provisioning dei cluster si modella con gli Aggregates di piattaforma.
Poiché un cluster AWS EKS, un control plane Istio e una VPC AWS sono in definitiva solo risorse cloud fisiche, vengono modellati esattamente come i componenti applicativi.
- L’Aggregate di piattaforma: il team Infrastruttura scrive un
Aggregate.yamlstandard i cui componenti sonocore/aws-vpc,core/eks-clusterecore/istio-base. - La Release di piattaforma: il team distribuisce questo aggregato. Il renderer associato a questi componenti di piattaforma produce gli artefatti necessari a creare l’infrastruttura di base.
- La Release applicativa: quando lo sviluppatore applicativo è pronto a distribuire il proprio agente IA, il team Ops si limita a indirizzare il cluster appena creato con un confine nel file
Releasedell’applicazione stessa.