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

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 dalla Release (CI/CD) inline sotto parameters: oppure tramite parameters: { $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: 2 in workers: 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 inline parameters:. La stratificazione su più file si esprime tramite catene extends: della Release.
  • values (l’intento cognitivo - di proprietà dello sviluppatore)
    • Ambito: usato in modo uniforme all’interno di components e dei relativi collegamenti features nell’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).
  • uses (la topologia strutturale - stato dichiarativo)
    • Ambito: usato in modo uniforme all’interno di components e dei relativi collegamenti features nell’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 usesSchema del catalogo per imporre la sicurezza dei tipi tra nodi.
  • infra (la realtà fisica - di proprietà di Ops)
    • Ambito: usato in modo uniforme all’interno dei components di un confine e dei relativi collegamenti features nella Release.
    • 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 collegamenti features non includono un campo infra e, insieme a additionalProperties: false, rifiutano infra durante la validazione dello schema. Validato dalla dichiarazione unificata schema: del catalogo.
  • inject (il contratto di consegna - comando imperativo)
    • Ambito: usato su un’istanza di componente, all’interno di definizioni esplicite di destinazione in uses e sulle features collegate, 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, arg o 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 con in: e porta esattamente uno tra from: e value:.
  • .context (la pipe generica dei metadati)
    • Ambito: iniettato silenziosamente dal compilatore nei template della Recipe di 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.

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 tipizzato parameters:, quindi interpola le variabili di template Go risolte prima di eseguire la validazione dello schema values: a valle.
    • Uso consigliato: i parameters sono 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 blocco infra della Release e gli overlay dei confini, mantenendo l’Aggregate dello 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 parameters possono 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.
  • Flusso 2: intento cognitivo dell’applicazione (values nei Components): definisce la logica intrinseca dell’applicazione. La dichiarazione schema: 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 (values nelle 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 porta values dello sviluppatore: le operazioni la collegano nella Release, con il suo infra (Flusso 4).
  • Flusso 4: dimensionamento dell’infrastruttura fisica (infra): scavalcando completamente lo sviluppatore, il dimensionamento fisico infra viene proiettato esplicitamente dalla Release specifica 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 dimensionamento infra è 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 campi infra locali 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 payload values del 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 port nella dichiarazione schema:. 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 dichiarazione schema: 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 versa

Comportamento 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, | quote e | 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 usando subsystems. I sottosistemi agiscono come cartelle ricorsive sul piano logico/dell’intento, propagando a cascata le annotations verso il basso nel contenitore .context.annotations.aggregate e 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 (supportando type, 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.
aggregate.yaml
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 contratto exportedComponents:, che stabilisce un nome di interfaccia pubblica stabile. Il padre raggiunge i componenti del modulo solo attraverso questa interfaccia: una destinazione uses: 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.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type indica 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 pattern spec.aggregates + exportedComponents mostrato 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, senza subsystems. Il compilatore li raccoglie in un sottosistema default sintetizzato 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, senza boundaries. Il compilatore li raccoglie in un confine default sintetizzato il cui output è piatto — gli artefatti finiscono direttamente sotto dist/ (per provider: dist/compose/, dist/helm/, …), senza alcun segmento con il nome del confine. È il caso più semplice: aggrega build su un target Compose piatto o a cluster singolo, senza dare nomi ai confini. (Un confine che uno sviluppatore dichiara e chiama default è un normale confine con nome e, senza un proprio directory:, emette in dist/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 subsystems espliciti, oppure Ops introduce boundaries espliciti. 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.

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 blocco values, senza virgolette, così il valore arriva come l’intero che è stato dichiarato.
    • Perché: se l’Aggregate dichiara env_workers come 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 schema values: circostante. Questo preserva la riusabilità dell’Aggregate: Ops fornisce l’intero tramite i parameters: della Release, il compilatore lo valida rispetto alla dichiarazione tipizzata parameters:, sostituisce il valore risolto nel documento e la dichiarazione schema: del Component valida con successo l’intero risultante.
  • 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 un type di Feature per credenziali (uno etichettato feature.aggrega.ai/kind: secret) e usando i values propri 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 di values e trasporta alla lettera un letterale inline. È la superficie degli allegati a rendere disponibile e tipizzata la forma scritta correttamente.
  • Vincolo 2: Components agnostici rispetto alle capacità

    • Pattern non supportato: l’architetto scrive aws_instance_type: string nella dichiarazione schema: del Component.
    • Perché: per convenzione i Components sono agnostici rispetto alle capacità. I target hardware fisici risiedono nelle Recipes di Ops o in annotazioni .context generiche, non nella logica applicativa cognitiva di base.
  • Vincolo 3: logica condizionale sui metadati

    • Pattern non supportato: Ops scrive {{ if eq .context.labels.gpu "true" }} in una Recipe per cambiare radicalmente la strategia di deployment.
    • Perché: il canale .context aggira la validazione schema: di ciascun pilastro. Affidarsi a etichette non validate per la logica di base dell’infrastruttura rende fragile la piattaforma. L’oggetto .context trasporta tag di metadati (ad es. fatturazione, SOC2); l’instradamento strutturale appartiene ai pilastri validati dallo schema.
  • 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: 4 in workers: 10) dalla Release.
    • 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 della Release lo impone vietando i blocchi values, limitando Ops a soddisfare il contratto parameters e a definire l’infra fisica.
  • 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 annidare infra e override delle feature per ogni componente senza mescolare la paternità delle etichette nell’Aggregate dello sviluppatore.

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’array parameters.approved_egress dell’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 su helm una NetworkPolicy Kubernetes per ciascun workload che quel componente renderizza, ammettendo l’egress solo verso i propri pod, verso i pod delle destinazioni dei suoi archi uses sulle 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, con infra.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; su compose, 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-external nel 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Esecuzione del compilatore al rendering (il passaggio di consegne)

  1. Il compilatore valuta la Recipe di legacy-oracle. Per una Release che fornisce legacy_oracle_ip: "10.0.4.55", il suo primary_endpoint è oracle://10.0.4.55:1521/PROD_DB.
  2. Su helm, il Workload di riferimento renderizza un Service ExternalName, legacy-oracle, con externalName: 10.0.4.55 e porta 1521; su compose non renderizza nulla.
  3. Il compilatore renderizza poi la Recipe di my-agent. Il suo canale .context.uses porta i provides del nodo Oracle, e il contratto di iniezione ha già risolto ORACLE_DSN rispetto 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.

  1. L’Aggregate di piattaforma: il team Infrastruttura scrive un Aggregate.yaml standard i cui componenti sono core/aws-vpc, core/eks-cluster e core/istio-base.
  2. 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.
  3. 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 Release dell’applicazione stessa.