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

Aggregate

Il ruolo concettuale dell’entità Aggregate (Dominio 1 — il progetto dichiarativo della topologia dello sviluppatore) è descritto in architecture/04-entity-taxonomy.md. I pattern di composizione (sottosistemi, aggregati annidati, convenzione Zero-Port, Parameter Hoisting) sono descritti in architecture/06-data-taxonomy-and-composition.md. Questa pagina tratta la superficie di authoring del catalogo per l’Aggregate — nello specifico, l’authoring di moduli Aggregate riutilizzabili da distribuire tramite il catalogo.

Ambito Component: il sottosistema predefinito

Un Aggregate organizza i componenti in sottosistemi — raggruppamenti con nome per aspetti trasversali (un livello dati, un livello edge) che hanno una propria cascata di annotazioni. La maggior parte degli Aggregates ha un solo raggruppamento, che quindi non richiede formalità.

Ambito singolo (il predefinito). Scrivi i componenti direttamente sotto spec.components: e ometti il blocco subsystems::

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Il compilatore li raccoglie in un sottosistema default sintetizzato. L’identità dei nodi non cambia — api resta api, mai default.api — quindi un Aggregate scritto in questo modo è intercambiabile con la forma esplicita a sottosistema singolo, e per indirizzarlo (nelle destinazioni uses:, nella diagnostica) si usa il percorso semplice spec.components.<name>. L’ambito sintetizzato è registrato fedelmente nell’IR esportata (con un marcatore di sottosistema sintetizzato), ma non compare mai nei percorsi che un autore scrive o legge.

Ambiti multipli. Quando i componenti si dividono in gruppi trasversali distinti, dichiara sottosistemi con nome sotto subsystems:. Ogni sottosistema ha i propri componenti e la propria cascata di annotazioni, e può annidare altri sottosistemi.

Mutua esclusività. spec.components: e spec.subsystems: si escludono a vicenda alla radice dell’Aggregate — scrivi l’uno o l’altro, mai entrambi. Un documento che li dichiara entrambi si arresta al caricamento con un errore di envelope. (Un sottosistema che uno sviluppatore chiama esplicitamente default è un normale sottosistema dichiarato, indirizzato al suo percorso qualificato spec.subsystems.default.components.<name> — l’omissione dell’ambito sintetizzato dipende dalla provenienza, non dal nome.)

Moduli Aggregate riutilizzabili

Gli Aggregates fungono sia da Aggregate radice compilato 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: è il nome del modulo, un punto e uno dei suoi alias esportati, e il compilatore collega l’arco al componente interno che l’alias nomina. Una destinazione che entra in un modulo con qualsiasi altro nome — il nome del componente all’interno del modulo, o un percorso verso un modulo annidato al suo interno — arresta la build, indicando il modulo e gli alias che esporta; vedi A uses target names a module’s component the module does not export (Una destinazione nomina un componente di un modulo che il modulo non esporta).

Perché un elenco exportedComponents: esplicito. Gli autori di un modulo decidono quali dei suoi componenti formano l’interfaccia pubblica e quali restano dettagli implementativi. Poiché un padre può nominare solo ciò che l’elenco pubblica, la struttura interna del modulo può essere rifattorizzata — un componente rinominato, un componente diviso in due, un worker sostituito da un servizio gestito — senza rompere alcun padre, purché ogni nome pubblicato punti ancora a un componente. L’elenco costa una voce per ogni componente pubblicato, e un componente può essere pubblicato con il proprio nome (store: store) dove quello è il nome che gli importatori devono usare. La stessa regola vale all’interno di una composizione: un modulo raggiunge un modulo che importa attraverso gli alias esportati di quel modulo. Una Release può collegare tra loro due componenti di uno stesso modulo, poiché quella connessione non attraversa l’interfaccia di alcun modulo.

Riesportare l’interfaccia di un modulo annidato. Una voce di exportedComponents: può puntare all’alias esportato di un sotto-aggregato annidato anziché a un componente dichiarato direttamente — un modulo che ripubblica parte di un modulo che importa, sotto il proprio nome di interfaccia ed eventualmente con un nuovo nome. Un arco uses: che ha come destinazione un tale alias riesportato si risolve in modo transitivo lungo la catena fino al nodo interno concreto, così un modulo compone moduli più profondi nella propria interfaccia pubblica senza esporne la struttura interna, e un consumatore non ha mai bisogno di sapere quanto in profondità sia annidata la destinazione. La disciplina dell’interfaccia stabile vale a ogni passaggio: ogni modulo riesporta solo ciò che sceglie di pubblicare. Una destinazione riesportata che non si risolve in alcun nodo interno arresta la build in modo esplicito come una destinazione diretta pendente, e una catena di riesportazione che si richiude su sé stessa viene rifiutata anziché seguita all’infinito.

Le dichiarazioni di un modulo vengono verificate come quelle dell’Aggregate. Il documento di un modulo viene letto solo quando si compila la composizione che lo importa, e le sue dichiarazioni vengono verificate da quel momento, a qualsiasi profondità di annidamento. Il blocco inject: proprio di un componente del modulo è vincolato alla allowlist spec.inject del suo tipo, e alle regole che vietano di rivendicare due volte una stessa chiave di consegna e di leggere una chiave che il tipo non pubblica. Un’associazione scritta su uno dei sottosistemi propri del modulo può nominare solo un socket che la sua Feature dichiara, e lo stesso vale per un’associazione che la Release scrive su un componente fornito da un modulo.

Le associazioni ai sottosistemi di un modulo raggiungono i suoi componenti. Una Feature che un modulo associa a uno dei propri sottosistemi si propaga a cascata su ogni componente che il modulo dichiara sotto quel sottosistema, sottosistemi annidati inclusi, esattamente come fa un’associazione a un sottosistema nell’Aggregate — e solo su quei componenti, mai sul componente di un Aggregate importatore che si trovi sotto un sottosistema con lo stesso nome. Viene valutata subito dopo le associazioni proprie del componente, i sottosistemi esterni prima di quelli interni. Su un campo che entrambe scrivono prevale l’associazione propria del componente con lo stesso nome, e i campi che essa omette mantengono i valori del sottosistema. Ogni componente che raggiunge la vincola all’appliesTo della Feature. Un rilievo sulle dichiarazioni proprie di un modulo nomina il modulo e la chiave all’interno del suo documento — .spec.subsystems.<subsystem>.features.<attachment>, ad esempio — così la modifica si fa nel modulo, dove si trova la dichiarazione, anziché nell’Aggregate che lo importa.

Posizione nel catalogo

Un modulo Aggregate riutilizzabile si trova sotto la directory di tipo aggregate/, al percorso che il suo metadata.name compone, segmento per segmento, con una directory di versione come foglia:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Il nome di un modulo può avere un segmento iniziale {publisher} che indica il fornitore o l’autore — core per la libreria standard, acme per un’azienda — e i moduli pubblicati della libreria standard sono nominati così: core/agenta si trova in aggregate/core/agenta/1.0.0/aggregate.yaml. Un nome formato da un solo token si trova un livello meno in profondità, in aggregate/{module-name}/{version}/aggregate.yaml. Entrambe le forme sono ben formate; il nome è ciò che l’autore scrive, e la directory lo rispecchia. Questo rispecchiamento è una convenzione del catalogo e non qualcosa che il compilatore verifica — un modulo viene trovato in base al nome che dichiara, non in base a dove si trova il suo file.

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, in minuscolo — così un modulo chiamato core/agenta viene pubblicato in hub.aggrega.ai/aggregate/core/agenta:1.0.0, e uno chiamato db-module in hub.aggrega.ai/aggregate/db-module:1.0.0.

Il pattern dei moduli

Modulo figlio (aggregate/child-database-module/1.0.0/aggregate.yaml, pubblicato come hub.aggrega.ai/aggregate/child-database-module:1.0.0):

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"

Aggregate padre:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Etichette dei moduli

Quando un Aggregate viene pubblicato nel catalogo come modulo riutilizzabile, può avere metadata.labels nel suo envelope YAML — ad esempio aggregate.aggrega.ai/tier: infrastructure o aggregate.aggrega.ai/compliance: pci-dss. Queste etichette descrivono l’identità del modulo e sono riportate sul documento del modulo così come pubblicato; nessun comando le legge ancora. La ricerca nel catalogo non indicizza gli Aggregates, e il grafo di build non riporta né le etichette di un modulo né il suo nome di catalogo, quindi una policy di governance non può selezionare i componenti di un modulo in base al modulo da cui provengono.

La distinzione critica. Le etichette dell’Aggregate descrivono l’identità del modulo riutilizzabile nel catalogo. Non si propagano a cascata ai nodi componente figli. Le etichette dei componenti provengono esclusivamente dall’entità di catalogo Component nel Dominio 2. Se uno sviluppatore importa un modulo etichettato aggregate.aggrega.ai/tier: infrastructure, i singoli componenti all’interno di quel modulo mantengono solo le proprie etichette definite nel catalogo (ad es. component.aggrega.ai/type: stateful-server). L’etichetta dell’Aggregate non viene mai iniettata nel dizionario labels del nodo IR.

Vedi architecture/06-data-taxonomy-and-composition.md §6 per la trattazione completa degli Aggregates compositi / del pattern dei moduli (inclusa la regola che esclude i sotto-componenti per i Components), e per il meccanismo di raggruppamento trasversale subsystems. Vedi vocabulary/data-pillars per la superficie di authoring del contratto tipizzato parameters.

Contratti di parametri tipizzati

Il blocco spec.parameters: dell’Aggregate dichiara il contratto tipizzato per i parametri che la Release soddisfa. Ogni slot di parametro ha un type dichiarato, una description facoltativa, un default facoltativo, vincoli facoltativi sullo spazio dei valori e (per gli slot di tipo oggetto) una struttura annidata. Il compilatore convalida ogni valore fornito dalla Release rispetto al contratto durante la risoluzione, prima che venga eseguita l’interpolazione dei parametri.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Le virgolette su ciascun riferimento sono intenzionali: sono ciò che decide il tipo con cui arriva il valore sollevato. Vedi templates/parameters-context.md.

Vocabolario degli slot di parametro

Il blocco tipizzato parameters: accetta il vocabolario della forma compatta: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate e validateMessage (un controllo personalizzato e il messaggio che riporta), items (per gli array), properties (per gli oggetti), valuesType (per le mappe di valori tipizzati) e required: true (marcatore per slot). Tre di queste parole chiave accettano come valore un contratto anziché una semplice impostazione — items, valuesType e ogni voce sotto properties — e su uno slot di parametro quel contratto annidato si scrive nella stessa forma tipizzata dello slot che lo contiene: valuesType: { type: boolean }, non valuesType: boolean. Prima dell’interpolazione, il compilatore verifica direttamente la mappa dei parametri unita rispetto a queste dichiarazioni: un parametro che nessuno slot dichiara viene rifiutato, uno slot marcato required: true che né la Release riempie né un default fornisce arresta la build, e ogni valore fornito viene verificato rispetto al type dichiarato del suo slot, all’appartenenza al suo enum, ai limiti minLength e maxLength, all’espressione regolare pattern e al format su uno slot stringa, e ai limiti min e max — il valore di uno slot numerico, la lunghezza di uno slot stringa e il numero di elementi di uno slot array. Gli slot oggetto e array sono ricorsivi: ogni voce sotto properties e ogni elemento rispetto a items viene verificato allo stesso modo, un contratto valuesType governa le chiavi che properties non nomina, e una chiave annidata che nessuna dichiarazione nomina viene rifiutata. Vedi vocabulary/compact-form-authoring.md per il vocabolario completo delle parole chiave, incluso dove un pilastro schema: scrive queste parole chiave in modo diverso.

Le parole chiave seguenti vengono verificate anche sulla dichiarazione stessa, prima che venga letto qualsiasi valore della Release, quindi uno slot che non potrebbe vincolare nulla arresta la build anche quando nessuna Release lo fornisce:

  • I limiti di lunghezza sono zero o più. Un minLength o maxLength negativo sulla dichiarazione propria di un parametro viene rifiutato dallo schema dell’Aggregate quando l’Aggregate viene caricato, indicando il parametro e la chiave. All’interno di un contratto annidato — sotto items, properties o valuesType — un limite di lunghezza viene letto così come è scritto e non è vincolato a quel minimo quando l’Aggregate viene caricato, quindi scrivilo come zero o più anche lì: un minLength negativo non impone nulla, e un maxLength negativo rifiuta ogni valore.
  • min e max devono delimitare qualcosa. Su uno slot booleano o oggetto la coppia non delimita nulla, quindi un min o un max scritto lì viene rifiutato quando l’Aggregate viene caricato, indicando il parametro e la chiave.
  • Un pattern deve compilare. Ogni pattern viene compilato come espressione regolare quando il contratto dei parametri viene letto — sullo slot stesso e all’interno di qualsiasi contratto annidato, a qualsiasi profondità — e uno che non compila viene rifiutato indicando il parametro, il pattern e il motivo. Il contratto viene letto per ogni build, pull e convalida della Release che raggiunge l’Aggregate, che si tratti dell’Aggregate della Release stessa o di un modulo che quell’Aggregate importa. Il controllo dei valori confronta poi ogni valore fornito con quella stessa espressione compilata.
  • Un formato deve essere uno di quelli che il compilatore verifica. format indica uno tra email, uri, hostname, ipv4, ipv6, uuid, date-time e date, scritti come li scrive JSON Schema. Qualsiasi altro nome — un errore di battitura come emial, o un nome che JSON Schema non definisce, come password — viene rifiutato quando l’Aggregate viene caricato, indicando il parametro ed elencando i nomi supportati: sullo slot stesso dallo schema dell’Aggregate, e all’interno di un contratto annidato, a qualsiasi profondità, quando il contratto dei parametri viene letto. Una stringa fornita che non ha il formato indicato viene poi rifiutata indicando il parametro, il valore e il formato. Ciò che verifica ciascun nome è descritto in vocabulary/compact-form-authoring.md.

Parametri di tipo oggetto e di tipo array

Gli slot di parametro accettano qualsiasi tipo supportato dalla forma compatta, inclusi oggetti annidati e array di elementi tipizzati:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

La Release soddisfa i parametri di tipo oggetto con YAML strutturato; il compilatore convalida la struttura rispetto allo schema dichiarato prima dell’interpolazione. I template che fanno riferimento ai campi dell’oggetto usano la sintassi standard dei template Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }}, ecc.

Convalida del contratto dei parametri

Il contratto stesso viene verificato per primo, quando viene letto: sono i controlli sui limiti di lunghezza e sui pattern descritti sopra in «Vocabolario degli slot di parametro». Il compilatore esegue poi tre sotto-passaggi durante l’elaborazione dei parametri:

  1. Riempimento dei default — gli slot con default: definito e nessun valore fornito dalla Release ricevono il loro default. I parametri a oggetto annidato hanno una semantica di authoring a tre casi per gli slot genitore omessi, esplicitamente vuoti e parzialmente scritti: omettere il genitore riempie i default dei figli, scrivere il genitore come {} preserva il vuoto esplicito (sopprime i default dei figli), e scrivere il genitore come mappa non vuota riempie solo i figli che la Release non ha fornito. Vedi templates/parameters-context.md per gli esempi YAML e la guida alla scelta «quando usare ciascuna forma».
  2. Convalida del contratto — ogni valore nella mappa unita, che sia stato fornito dalla Release o riempito da un default:, viene convalidato rispetto ai vincoli dichiarati di type / enum / min / max / pattern / struttura annidata. Gli errori di convalida arrestano la build con un errore chiaro che indica lo slot in questione, il valore fornito e il vincolo violato. I parametri obbligatori mancanti senza default: producono un arresto analogo con il nome dello slot.
  3. Interpolazione — il compilatore valuta l’intero testo dell’Aggregate come template, prima di leggerlo come YAML, e sostituisce ogni riferimento {{ .parameters.<slot> }} — tipicamente all’interno delle stringhe values: di componenti / funzionalità / sotto-aggregati — con il valore risolto; anche qualsiasi altro {{ nel testo viene letto come sintassi di template, quindi un valore che contiene doppie graffe proprie — la definizione esportata di una piattaforma di flussi, per esempio — scrive ogni {{ come {{"{{"}}, come descrive Testo che contiene le proprie doppie graffe. Dopo questo passaggio, le superfici dei template di valori consumano letterali già interpolati e non ricevono .parameters nel loro contesto di template.

La mappa dei parametri unita resta attiva durante il rendering per supportare la valutazione dei template di percorso. I template directory: e subDirectory: scritti dall’operatore sui confini della Release leggono .parameters.<slot> direttamente al momento del rendering, rispetto a un elenco chiuso di valori consentiti; l’emissione dei percorsi ha bisogno di un vocabolario di regione / ambiente per la disposizione degli artefatti per ambiente, e la concessione asimmetrica mantiene quella responsabilità dell’operatore all’interno della superficie dell’operatore senza passare attraverso i values dell’Aggregate. La mappa resta leggibile finché tutte le fasi di rendering non sono completate ed è raggiungibile solo dalla compilazione per cui è stata risolta; le ricette che consumano values: scritti dallo sviluppatore vedono le stringhe post-interpolazione, mentre i template di percorso vedono dati .parameters attivi durante il rendering. Vedi templates/expansion-matrix.md riga 3 per la matrice di disponibilità dei template di percorso e path-template-variables.md per l’elenco delle variabili consentite nei template di percorso.

Per la checklist più ampia del parameter hoisting (dichiarazione nell’Aggregate → riferimento nei values → soddisfacimento nella Release → consumo nella Recipe) e per i meccanismi trasversali ai pilastri, vedi vocabulary/data-pillars.md §«Parametri» e §«La checklist del parameter hoisting». Per i campi del contesto di template esposti durante l’interpolazione e l’eccezione per i template di percorso, vedi templates/parameters-context.md.

Un arco uses è una chiamata dichiarata dall’Aggregate

Un arco uses è la dichiarazione dell’Aggregate che un componente ne chiama un altro. Il compilatore convoglia nel chiamante i valori che il target pubblica e non restringe nulla: da solo, un arco non ammette il chiamante né rifiuta nessun altro, e un carico di lavoro che raggiunge l’indirizzo del target senza un arco lo raggiunge comunque.

Limitare chi può chiamare un componente, e cosa esso può chiamare, è una decisione dell’operatore, presa per ambiente nella Release. Dove una Release associa a un componente la Feature core/caller-allowlist del catalogo della libreria standard, la build scrive una network policy che ammette esattamente i componenti i cui archi uses puntano a esso, i pod di quel componente stesso e le sorgenti che l’associazione indica. La sua controparte in uscita, core/egress-allowlist, consente al componente a cui è associata di raggiungere solo i componenti a cui puntano i suoi archi uses, i suoi pod, il DNS del cluster e gli intervalli di indirizzi che la Release elenca. Una chiamata che l’Aggregate non dichiara come arco può allora essere rifiutata dal cluster a entrambe le estremità, ovunque il suo plugin di rete applichi le network policy. Quindi scrivi un arco per ogni chiamata che i tuoi componenti effettuano, anche per una che non inietta alcun valore: un arco mancante è una chiamata che un componente recintato può rifiutare. model-server-caller-allowlist mostra un model server raggiungibile solo attraverso il gateway che lo precede.

Le associazioni proprie di una connessione: features su una voce uses

Una connessione che un componente traccia nella forma estesa di uses: è una voce a sé stante, e accanto a target, inject e values può portare associazioni, sotto features:. Ciascuna è indicizzata da uno slot che il socket dichiara: il Component consumatore elenca, nel featuresSchema del socket, gli slot che ogni connessione cablata attraverso quel socket può riempire (vedi Socket di topologia). È così che un componente mantiene una credenziale diversa per ciascun componente che raggiunge: un gateway che chiama due modelli con due chiavi, o un agente che presenta a un modello una chiave propria.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Un’associazione su una connessione porta type (obbligatorio), una description facoltativa e values per la Feature. Non porta né uses né inject: un’associazione su una connessione non si annida, e il modo in cui il suo materiale raggiunge il consumatore lo decide la Recipe del componente consumatore, non un blocco inject. Un documento che scrive l’una o l’altra chiave viene rifiutato al caricamento, indicando la chiave.

Solo gli slot che il socket dichiara. Un’associazione sotto un nome che il featuresSchema del socket non elenca arresta la build al caricamento, indicando la connessione, il socket, il componente e gli slot che il socket dichiara — e, dove il nome dista una sola modifica da uno di essi, quello slot, come probabile grafia voluta. Uno slot riempito è poi vincolato alla dichiarazione propria dello slot su ogni connessione: un selector che le label della Feature non soddisfano arresta la build a questa voce, e uno slot required lasciato vuoto su una qualsiasi connessione arresta la build indicando quella connessione. Un socket che non dichiara slot non ammette associazioni sulle sue connessioni, e nemmeno un socket ad hoc — uno che l’Aggregate cabla senza che il Component lo dichiari — poiché non dichiara alcuno slot. Un componente fornito da un sotto-modulo è soggetto alla stessa regola, e il rilievo punta al documento del sotto-modulo stesso. Vedi A connection carries an attachment under a name its socket declares no slot for (Una connessione porta un’associazione sotto un nome per cui il suo socket non dichiara alcuno slot).

Una connessione tracciata da una Feature non ne porta nessuna. Il blocco uses: proprio di una Feature associata — su un componente o su un sottosistema — si scrive nella stessa forma ma rifiuta features: al caricamento del documento. Una credenziale di cui una tale connessione ha bisogno riempie uno slot che la Feature dichiara nel proprio featuresSchema, associato accanto alla Feature; vedi La credenziale propria di una Feature.

Il nome che assume l’associazione. Ogni associazione di connessione diventa un’associazione del componente consumatore, chiamata <alias>.<slot>: l’alias sotto cui è scritta la connessione, un punto e lo slot, cioè gpt.credential nell’esempio sopra. Il punto è il separatore riservato ai nomi che il compilatore compone, e nessun alias, slot o nome di associazione in un Aggregate può contenerlo, quindi il nome composto non coincide mai con uno scritto nel blocco features: del componente stesso; una Release che lo scrive su un componente o su un confine viene rifiutata (vedi Configurazione delle connessioni per arco). È il nome con cui il livello per istanza del Manifest indicizza l’associazione (vedi Mappatura URI piatta), il nome con cui la riportano la diagnostica e il grafo IR, e il valore che la FeatureRecipe dell’associazione legge come .attachment_name (vedi Nomi derivati dall’associazione di una connessione).

Da lì si risolve come qualsiasi associazione: il Manifest lega il suo tipo di Feature a una FeatureRecipe, i suoi values vengono convalidati rispetto allo schema della Feature — un errore viene segnalato alla voce di connessione che li ha scritti — e la sua FeatureRecipe esegue il rendering rispetto ai values e all’infra propri dell’associazione. Due cose la distinguono dalle associazioni proprie del componente:

  • Non compare in .features della Recipe consumatrice. Quel pilastro porta solo le associazioni scritte nel blocco proprio del componente, quindi a una Recipe che cerca in .features le proprie associazioni per tipo non viene mai passata la credenziale di una connessione. Una Recipe legge l’associazione di una connessione dalla connessione stessa, in .context.uses.<alias>.features.<slot>, nella forma che porta .features, inclusi i suoi provides risolti (vedi Le associazioni di una connessione).
  • Arriva solo al consumatore. L’output renderizzato di un target è lo stesso qualunque cosa portino le connessioni che lo raggiungono.

La copia del blocco scritto nel grafo. Il grafo IR mantiene il blocco uses: di ogni componente così come è stato scritto, e lì un’associazione di connessione conserva il suo type e la sua description e nessuno dei suoi values. I valori compaiono una sola volta, sull’associazione che porta il consumatore, dove un valore che la Feature dichiara sensibile viene omesso.

Una Release può dimensionare con infra un’associazione dichiarata qui, o associarne una propria su una connessione che raggiunge: vedi Configurazione delle connessioni per arco.

Disattivare un componente o un modulo: active:

Un’istanza di componente e un modulo sotto-aggregato accettano ciascuno un interruttore active: che decide se quell’entità fa parte o meno della topologia compilata. Se lo ometti, l’entità è presente; è il default e il caso ordinario.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Scrivi direttamente un booleano, o un template su .parameters che si risolve in un booleano. La forma a template è il motivo per cui l’interruttore esiste: permette a una Release di decidere la presenza di un’entità soddisfacendo un parametro, così un solo Aggregate copre ambienti che differiscono per i pezzi che distribuiscono, senza che la Release dichiari nulla che l’Aggregate non abbia dichiarato.

Cosa rimuove un interruttore falso. L’entità viene potata prima che il grafo venga costruito, e la potatura si propaga a cascata: un componente porta con sé i propri archi uses: e le Features associate, e un modulo porta con sé tutto ciò che ha fornito — i suoi componenti, i loro archi, le loro associazioni. Nulla di ciò che l’entità potata ha portato viene renderizzato. Ciò che la potatura non raggiunge è un riferimento a essa da un punto sopravvissuto, ed è l’oggetto del paragrafo successivo.

Un componente sopravvissuto che punta ancora a uno potato arresta la build. Se api dichiara un arco uses: verso redis e redis è disattivato, la build si ferma anziché lasciar sparire l’arco, il che lascerebbe i valori iniettati di api silenziosamente vuoti al momento del deploy. Decidi quale dei due appartiene a questo ambiente: riattiva il target, subordina il consumatore allo stesso parametro in modo che la coppia esca insieme, oppure rimuovi l’arco dal blocco uses: del consumatore.

Un interruttore scritto deve risolversi in un booleano, e un valore vuoto non lo è. L’interruttore viene letto in modo rigoroso dopo che il suo template è stato risolto, e un letterale che non si interpreta come booleano ferma la build invece di assumere un valore predefinito. Il caso a cui fare attenzione è un interruttore che legge un parametro privo di valore: si risolve nel nulla, e leggere il nulla come «presente» distribuirebbe proprio l’entità che hai subordinato a quel parametro. Quindi scrivere active: senza nulla dopo non equivale a omettere la chiave: solo un interruttore che nessuno ha scritto vale «presente» per default. Dai al parametro un default: in spec.parameters in modo che ogni ambiente abbia una risposta, oppure soddisfalo nella Release. Per rendere un’entità presente incondizionatamente, rimuovi la chiave active: anziché svuotarla. L’arresto è descritto sotto «An active: toggle does not resolve to true or false (Un interruttore non si risolve in true o false)» nel riferimento delle condizioni di arresto.

Un componente disattivato resta nominabile da una Release. Una Release può ancora nominarlo in un confine, ed è intenzionale: disattivare un componente è un atto di authoring, e non ci si aspetta che la Release che lo configura venga riscritta nella stessa modifica.

Annotazioni su sottosistemi e componenti

I sottosistemi e le istanze di componente hanno entrambi un campo annotations:. Le annotazioni scritte dallo sviluppatore sulla superficie dell’Aggregate guidano la cascata di annotazioni lato Aggregate — un’annotazione di sottosistema si propaga a ogni sottosistema annidato e a ogni componente contenuto, con override ai livelli più vicini a granularità di singola chiave. La mappa mappings.features.annotations del Manifest dichiara i binding che traducono le chiavi di annotazione in collegamenti sintetici di Feature in fase di build. L’invariante dell’Aggregate come superficie di authoring limita queste annotazioni all’instradamento attraverso i percorsi maps.values del binding; un binding che dichiara solo percorsi maps.infra si attiva dal lato della Release, non dal lato dell’Aggregate.

Forme dei valori

Ogni chiave di annotazione assume una di quattro forme, distinguendo «taccio» da «dichiaro un valore» — uno scalare o un oggetto strutturato — e da «mi escludo»:

  • Chiave assente — l’ambito non dichiara alcun valore per questa annotazione. I sottosistemi annidati e i componenti contenuti ereditano qualsiasi binding da un ambito antenato.
  • Una stringa scalare — un singolo valore. Il binding del Manifest deve dichiarare esattamente un percorso in totale; lo scalare viene instradato verso quel percorso.
  • Un oggetto strutturato — una mappa da sottochiave a sottovalore. Ogni sottochiave dell’oggetto viene instradata, attraverso le maps del binding del Manifest, verso il campo corrispondente dello schema della Feature nel pilastro dichiarato.
  • null YAML esplicito — l’ambito rimuove dal proprio sottoalbero qualsiasi binding ereditato per questa chiave. I componenti e i sottosistemi fratelli mantengono la propria ereditarietà; solo l’ambito che si esclude perde il binding.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Valori strutturati per Features con più campi

Una Feature con più campi configurabili si presta a un valore di annotazione strutturato: una sola chiave di annotazione che porta valori per diversi campi dello schema della Feature in un’unica dichiarazione. Il lato Aggregate attiva solo le sottochiavi il cui pilastro nella mappa del binding è values; le sottochiavi instradate verso infra appartengono alle annotazioni lato Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

I valori strutturati si propagano a cascata con un merge profondo per sottochiave: le sottochiavi dei livelli più vicini sovrascrivono quelle del genitore; un null esplicito su una sottochiave sopprime la sottochiave ereditata per quell’ambito, mentre le sottochiavi sorelle restano. Per la trattazione completa dei valori strutturati — composizione tra i due lati con le sottochiavi infra lato Release, validazione del tipo per sottochiave, la disciplina del default rilassato per i campi di schema senza un type dichiarato — vedi providers/well-known-annotations.md §«Valori di annotazione strutturati».

Indipendenza per chiave

Ogni chiave di annotazione eredita, sovrascrive e si esclude in modo indipendente. Un componente che dichiara annotations.feature.myco/db-pool: null si esclude solo da quella chiave; le altre chiavi ereditate dal sottosistema che lo contiene continuano a propagarsi a quel componente. I componenti fratelli nello stesso sottosistema mantengono in modo indipendente le proprie mappe di annotazioni — l’esclusione di un componente non influisce sui fratelli.

Annotazioni dei componenti di primo livello

I componenti di primo livello (dichiarati direttamente sotto spec.components anziché dentro un sottosistema) non hanno alcuna cascata ereditata. Il loro campo annotations: dichiara i valori direttamente sull’ambito del componente; l’espansione sintetizza collegamenti di Feature a partire da ogni annotazione dichiarata per cui il Manifest ha un binding corrispondente.

Per la regola della cascata lato Aggregate applicata ai binding, la ripartizione tra lato e pilastro e un esempio completo che mostra i binding che traducono le annotazioni in collegamenti sintetici di Feature, vedi providers/well-known-annotations.md §«Cascata di annotazioni lato Aggregate».

Pattern di anchor YAML (blocco defs:)

Lo schema dell’Aggregate accetta un blocco defs: opzionale a livello radice — un elenco di stringhe YAML usato esclusivamente come contenitore per gli anchor YAML standard (&anchor) e i riferimenti (*anchor). Il compilatore non legge mai il contenuto del blocco; esiste perché gli autori possano dichiarare le definizioni degli anchor in un unico punto e farvi riferimento nel resto dell’Aggregate, mantenendo DRY i valori ripetuti senza perdere il dizionario piatto O(1) su cui il compilatore itera. Il meccanismo rispecchia l’equivalente blocco defs: dell’entità Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Gli anchor vengono risolti durante il parsing YAML, quindi *default_log_level è la stringa "info" nel momento in cui il compilatore legge il blocco dei valori. Il blocco defs: è la sede convenzionale delle definizioni degli anchor; YAML consente di dichiarare gli anchor ovunque, ma raccoglierli in un punto mantiene leggibile il resto dell’Aggregate. Il blocco è opzionale — gli Aggregates che non hanno bisogno di anchor lo omettono del tutto.