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

Release

Il ruolo concettuale dell’entità Release (Dominio 4 — il router di distribuzione che vincola un Aggregate a un Manifest e mappa i componenti nei confini fisici) si trova in architecture/04-entity-taxonomy.md. Il meccanismo di sequenziamento temporale (syncWave per confine), il Dynamic Addressing Polyfill e il pattern Parameter Hoisting si trovano in architecture/12-day-two-lifecycles.md. Questa pagina tratta la superficie di authoring della Release.

Il ruolo della Release

La Release vincola un aggregate a un manifest e mappa i componenti nei confini fisici di distribuzione (ad es. aws-eks-production). È l’unico punto di ingresso per la compilazione: aggrega build --release release.yaml.

La Release soddisfa il contratto astratto dell’aggregato iniettando le realtà fisiche esclusivamente nel blocco parameters, e inietta il dimensionamento fisico (come CPU o porte) tramite il namespace parallelo infra.

Ogni Release dichiara un campo manifest: che nomina il suo Manifest (a meno che la Release non usi extends:, che eredita il puntatore al manifest del genitore). La CLI aggrega build legge direttamente questo campo; non esiste alcun flag CLI --manifest, quindi la specifica delle dipendenze resta committata in Git accanto alla Release stessa, rendendo verificabile la cronologia delle distribuzioni attraverso la cronologia Git propria della Release.

I campi aggregate: e manifest: vengono risolti per identità o per file con percorso relativo, nello stesso modo in cui il resto del linguaggio risolve i riferimenti — mai come radice di nome file relativa alla Release. Un valore ./ o ../ è un file locale esplicito, letto direttamente in modo relativo alla Release. Un token semplice è un’identità — il metadata.name dell’entità referenziata. Un’identità manifest: viene risolta esaminando la directory propria della Release (un Manifest è configurazione dell’operatore sul lato della distribuzione, quindi non ha un livello di catalogo o di registry). Un’identità aggregate: si risolve attraverso l’intera cascata — la directory della Release, poi il catalogo, poi il registry — quindi una Release può nominare un Aggregate pubblicato per identità e lo stesso modulo pubblicato si risolve sia che sia lo spec.aggregate di primo livello di una Release sia che sia un sotto-aggregato all’interno di un altro Aggregate. Questo modello per identità o per percorso permette a un Aggregate condiviso di sostenere molte varianti di Release senza legare il riferimento a un nome file, e a un Aggregate pubblicato di essere distribuito direttamente per nome.

Un percorso resta all’interno del workspace. Un valore ./ o ../ nomina un file contenuto nel workspace, e così ogni altro percorso che una Release scrive — il suo extends: e un $import: dei parametri, più sotto. Un percorso che esce dal workspace così com’è scritto, o che un collegamento simbolico lungo il cammino porta fuori da esso, viene rifiutato prima che venga letto alcunché dal file che nomina. Per distribuire un Aggregate conservato fuori dal workspace, nominalo per identità ed elenca la directory che lo contiene come directory di catalogo nella configurazione del workspace; un Manifest, una Release nominata da un extends: e un file di parametri vengono letti accanto alla Release e mai cercati per nome, quindi vanno conservati all’interno del workspace. Una Release che nomini sulla riga di comando, o che la configurazione del workspace nomina, fuori dal workspace è una radice a sé: ogni percorso che scrive — e ogni percorso scritto da una Release a cui porta la sua catena extends: — deve portare a un file all’interno della directory che contiene quella Release, e un percorso che esce da quella directory, o che un collegamento porta fuori da essa, viene rifiutato allo stesso modo. Conserva ciò che una tale Release nomina accanto a essa, oppure compilala nel workspace che le contiene entrambe. Vedi errors/fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Un riferimento a un altro file esce dalla directory entro cui deve restare)».

La Release stabilisce la destinazione degli artefatti compilati; lo smistamento verso i provider spetta al Manifest a cui punta la Release (vedi Manifest e Release: separazione delle responsabilità per la ripartizione dei ruoli).

Metadati dell’ambiente

Ogni blocco di metadati di una Release accetta un campo environment: — una stringa libera che identifica l’ambiente in cui la Release viene distribuita (valori tipici: production, staging, dev). Il campo è informativo: non ha alcuna enumerazione, alcun pattern a livello di schema e alcuna validazione tra entità oltre a type: string. Il compilatore emette il suo valore come label aggrega.ai/environment su ogni manifesto Kubernetes che il provider helm renderizza, insieme al resto della suite di label di provenienza di Aggrega — così come è scritto quando è un valore di label Kubernetes valido, e altrimenti riscritto in un valore valido, con il valore esatto riportato nell’annotazione aggrega.ai/environment (così eu/prod riceve la label eu-prod); il provider helm-chart aggiunge le stesse label a ciascun artefatto caricato tramite $import: che colloca in un sub-chart, mentre i template propri del sub-chart portano ciò che il loro autore ha scritto. Il provider compose porta lo stesso valore come label aggrega.ai/environment su ciascun servizio che emette.

Cinque pattern pratici guidano la scrittura di environment::

  1. Attribuzione dei costi OTel/FinOps. Le dashboard dei costi cloud (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtrano i pod Kubernetes per ambiente tramite tag. La label aggrega.ai/environment: production confluisce nelle label dei pod tramite l’iniezione di label del provider Helm; i report dei costi raggruppano la spesa per aggrega.ai/environment senza tagging manuale per risorsa.

  2. Filtraggio di trace e log OTel. Le dashboard di osservabilità (Datadog, New Relic, Honeycomb, Grafana Tempo) filtrano la telemetria per label di ambiente. aggrega.ai/environment: staging permette agli operatori di limitare le query sui log e le ricerche di trace allo staging senza filtrare su convenzioni dei namespace o nomi dei chart — un’unica label canonica su tutta la superficie renderizzata.

  3. Targeting degli operator Kubernetes. I controller GitOps (ArgoCD, Flux) e gli operator di policy (Kyverno, OPA Gatekeeper) a volte filtrano le risorse per label di ambiente per policy specifiche dell’ambiente (per esempio, «le risorse solo di produzione richiedono una label approved-image-source»). La label aggrega.ai/environment fornisce un selettore stabile, distinto dalle convenzioni dei namespace o dai pattern di denominazione.

  4. Differenziazione della produzione multi-regione. Un team che esegue una Release production-us-east accanto a una Release production-eu-west — entrambe con metadata.environment: production — ottiene la stessa label aggrega.ai/environment: production in tutte le regioni. Combinato con una label di regione separata, questo consente il consolidamento dei costi tra regioni («spesa totale di produzione») e il dettaglio per regione.

  5. Delimitazione della conformità. La raccolta di evidenze SOC 2, PCI e HIPAA viene delimitata per ambiente (audit solo di produzione, ecc.). La label aggrega.ai/environment viene usata dagli strumenti di raccolta delle evidenze di conformità (Vanta, Drata) per filtrare le risorse per ambito di audit.

Lo schema richiede environment: su ogni Release; il valore è informativo, e il compilatore lo legge solo per scrivere la label aggrega.ai/environment.

Vincoli a livello di schema

Due garanzie strutturali proteggono l’Aggregate come unica fonte di verità:

  • values: è vietato. Per proteggere l’Aggregate come unica fonte di verità, lo schema della Release vieta meccanicamente un blocco values: — l’operatore non può dichiarare values su alcun Component o Feature da una Release. Il divieto si estende agli archi uses: una voce uses per arco di una Release porta infra e le associazioni che scrive sulla connessione, e anche queste portano infra — mai values (i valori per arco rivolti allo sviluppatore, e i valori di un’associazione su una connessione, restano nell’Aggregate). La variazione per ambiente dei valori rivolti allo sviluppatore passa attraverso il Parameter Hoisting: lo sviluppatore espone un campo tipizzato parameters.* nell’Aggregate, il template values del Component vi fa riferimento e la Release soddisfa il parametro per il proprio ambiente. Vedi architecture/06-data-taxonomy-and-composition.md §8 Vincolo 4 per il divieto a livello di schema enunciato esplicitamente. La superficie degli archi uses della Release — ciò che può configurare e collegare — è documentata in Configurazione della connessione per arco più avanti.
  • extends + aggregate: viene rifiutato. Per impedire Releases non tracciabili che «mutano l’aggregate», quando una Release usa extends, la dichiarazione di un puntatore aggregate viene rifiutata dallo schema della Release. La release figlia deve corrispondere esattamente allo stesso intento dello sviluppatore della release padre. Il manifest, invece, diventa opzionale, abilitando il «late binding» — consente all’operatore di ereditare l’intera topologia fisica ma di sostituire chirurgicamente il Manifest.

Il blocco parameters:

Una Release soddisfa il contratto tipizzato dei parametri che l’Aggregate dichiara. spec.parameters: è la superficie di authoring — una mappa YAML le cui chiavi corrispondono alle dichiarazioni parameters.* dell’Aggregate e i cui valori forniscono il soddisfacimento per ambiente.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Ogni valore è sottoposto al controllo dello schema dichiarato dall’Aggregate al livello del contratto dei parametri, e la build si arresta quando una Release omette un parametro obbligatorio (E0165, parameter-missing) o fornisce un valore che il contratto del suo slot rifiuta (E0164, parameter-contract-violation). I parametri dichiarati con un default: ricevono il valore predefinito quando la Release omette lo slot; il contratto tipizzato è l’unico vocabolario di authoring.

Due modalità di authoring — selezione in base alla forma del contenuto. parameters: accetta una mappa YAML inline (Modalità 1, mostrata sopra) oppure una singola chiave $import: che punta a un file locale (Modalità 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Un percorso $import: relativo viene risolto a partire dalla directory che contiene la Release che lo scrive, da qualunque punto si esegua un comando, così la riga di comando e l’editor leggono lo stesso file; un percorso assoluto indica il proprio luogo, e in entrambi i casi deve portare a un file all’interno del workspace — oppure, per una Release indicata fuori dal workspace, all’interno della directory che la contiene. Le due modalità si escludono a vicenda in questo punto, e si può importare un solo file. La stratificazione dei parametri su più file è compito delle catene extends: della Release: la Release padre fornisce un insieme di base di parametri e la figlia estende e sovrascrive per ambiente. Vedi Release composita / ereditarietà extends: più avanti per il pattern.

Distinzione tra parametri e infra. I parametri portano l’intento cognitivo dello sviluppatore, espresso come slot tipizzati che l’Aggregate dichiara; la Release li soddisfa. infra: sulla Release porta il dimensionamento fisico dell’operatore (numero di repliche, limiti di CPU/memoria, classi di storage) associato a componenti specifici o ad associazioni di Feature. I parametri fluiscono nei template values: dell’Aggregate tramite .parameters.X; infra: fluisce nel template valuesMapping: della Recipe tramite .infra.X. Vedi architecture/06-data-taxonomy-and-composition.md §3 per la tassonomia dei pilastri dei dati e templates/parameters-context.md per il ciclo di vita dei parametri lungo la pipeline.

Confini e ambito predefinito

Una Release raggruppa i componenti in confini — unità fisiche di distribuzione, ciascuna con la propria directory di output e la propria cascata di annotazioni. Il caso a confine singolo è quello comune, quindi non richiede formalità.

Ambito singolo (il predefinito). Scrivi i componenti direttamente sotto spec.components: e ometti il blocco boundaries:. Il compilatore li raccoglie in un confine default sintetizzato il cui output è piatto — gli artefatti finiscono direttamente sotto dist/ (per provider, tramite il valore predefinito sicuro di subDirectory descritto più avanti: dist/compose/, dist/helm/, …), senza alcun segmento con il nome del confine nel percorso. È la distribuzione più semplice: aggrega build su un target Compose piatto o a cluster singolo, senza dare nomi ai confini.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Più ambiti. Quando una Release copre più di un raggruppamento fisico — cluster, regioni o sync wave separati — dichiara confini con nome sotto boundaries:. Ogni confine porta la propria directory:, la propria cascata di annotazioni e il proprio syncWave:, e i componenti vengono indirizzati all’interno del loro confine.

Mutua esclusività. spec.components: e spec.boundaries: si escludono a vicenda alla radice della Release — una Release scrive l’uno o l’altro, mai entrambi. Un documento che li dichiara entrambi si arresta al caricamento con un errore di envelope. La superficie components di primo livello porta la stessa forma per componente, lato operatore, che portano i components di un confine (infra:, annotations:, uses:).

Un confine dichiarato con nome default. L’output piatto è una proprietà del confine predefinito sintetizzato, non del nome. Un confine chiamato default che una Release dichiara esplicitamente sotto boundaries: è un normale confine con nome: il suo output segue la sua directory: (che per impostazione predefinita è dist/boundaries/default/), esattamente come qualsiasi altro confine dichiarato.

Vedi architecture/06-data-taxonomy-and-composition.md §7 per il pattern dell’ambito predefinito.

Segregazione spaziale e percorsi di output

Ogni confine dichiara una directory fisica di output per i propri artefatti compilati; i componenti all’interno di un confine possono sovrascriverla tramite una subDirectory per componente. Il compilatore calcola il percorso finale dell’artefatto unendole, in forma separata da barre su ogni piattaforma: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Una directory, una grafia. Il percorso valutato viene ripulito una sola volta, quindi out/a, out//a, ./out/a e out/a/ sono un’unica directory. I confini i cui percorsi, ripuliti, portano alla stessa directory e che eseguono il rendering tramite lo stesso provider vengono assemblati insieme, esattamente come i confini scritti con percorsi identici.
  • Il percorso resta sotto la radice di output. Un percorso che risale fuori dalla radice di output (.., ../escape, a/../..), uno assoluto, o uno che non indica alcuna directory — vuoto, oppure che, ripulito, si riduce alla radice di output stessa — arresta la build prima che venga scritto qualsiasi cosa. Il messaggio indica la Release, il confine, il campo in errore (directory: o subDirectory:) e il valore a cui è stato valutato, poiché quel valore è spesso il risultato di un template.
  • Default sicuro. Se subDirectory è omesso o vuoto, il compilatore applica automaticamente subDirectory: "{{ .capability }}" — gli artefatti di ciascuna capacità di rendering (Helm, Helm-chart, Compose, Terraform, CloudFormation) finiscono in una propria sottocartella, evitando collisioni tra artefatti misti negli strumenti CI/CD a valle. Un subDirectory: "" scritto esplicitamente viene letto esattamente come uno omesso, quindi riceve anch’esso questo default.
  • Override piatto. Per disabilitare del tutto le sottodirectory (tutti gli artefatti direttamente sotto directory), imposta subDirectory: ".". Anche un template subDirectory che si valuta in una stringa vuota — "{{ .parameters.sub }}" con sub impostato a "", ad esempio — le disabilita.
  • Variabili di template. directory si valuta con {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }} e {{ .parent_boundary.* }} per i dati in cascata da un confine che lo racchiude. subDirectory si valuta con lo stesso insieme più {{ .component_id }} (solo per le sovrascritture per componente). Il compilatore valuta i template di percorso con missingkey=error — fare riferimento a una variabile non dichiarata arresta la build con una diagnostica precisa. Vedi variabili dei template di percorso per la matrice per contesto e le regole della cascata dal confine genitore.

Le annotazioni di confine scendono in cascata verso ogni componente contenuto; infra resta strettamente localizzato sul componente a cui è destinato. La mappa ricorsiva boundaries consente un annidamento arbitrario (confine dentro confine dentro confine), mentre gli invarianti della cascata di annotazioni e dell’infra locale valgono a ogni livello.

Esempio svolto:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Le annotazioni propagate in cascata da questo meccanismo emergono nei template delle Recipe a valle tramite .context.annotations.release; vedi Scrittura di una Recipe e la matrice di espansione dei template per come i renderer le consumano.

Valori di annotazione strutturati. Quando un binding del Manifest dichiara più percorsi di instradamento del pilastro infra per una stessa chiave di annotazione, il valore dell’annotazione lato Release può essere un oggetto strutturato che porta valori per diversi campi dello schema di una Feature in un’unica dichiarazione:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

I valori strutturati scendono in cascata con una fusione profonda per sottochiave; le sottochiavi di livello più vicino sovrascrivono quelle del genitore. Un null per sottochiave esclude una sottochiave mentre le sottochiavi sorelle restano. Il lato Release attiva solo le sottochiavi il cui pilastro nella mappa di binding è infra; le sottochiavi instradate a values appartengono alle annotazioni lato Aggregate. Per la trattazione completa dei valori strutturati — composizione tra i due lati, validazione del tipo per sottochiave, la disciplina dei default rilassati — vedi providers/well-known-annotations.md §«Valori di annotazione strutturati».

Annotazioni ben note. Oltre alle chiavi ad hoc, la libreria standard di Aggrega definisce un insieme di annotazioni ben note sotto i namespace aggrega.ai/ e feature.aggrega.ai/, raggruppate nelle categorie posizionamento, rete, sicurezza e osservabilità. Chi aggiunge annotazioni a un confine di una Release dovrebbe consultare providers/well-known-annotations.md per la matrice completa e le regole di consumo per provider — la pagina documenta quali provider applicano ciascuna chiave ben nota e quale comportamento producono quando la chiave è presente.

Configurazione della connessione per arco

Un componente di un confine può portare un blocco uses: che configura o collega gli archi della topologia all’interno dei socket che lo usesSchema del catalogo del Component dichiara. È la superficie per connessione dell’operatore, delimitata in modo che lo sviluppatore mantenga la titolarità dell’architettura che ha scritto:

  • Configurare un arco esistente. Imposta infra per arco su un arco che lo sviluppatore ha già dichiarato. La voce indica l’alias dello sviluppatore e fornisce infra; indica lo stesso target che lo sviluppatore ha collegato oppure omette il target. L’infra viene validato rispetto allo infraSchema del socket.
  • Collegare un socket non vincolato. Crea un arco verso un socket che lo usesSchema del Component dichiara ma che lo sviluppatore ha lasciato non collegato, puntando a un componente esistente. L’arco creato può anche portare infra per arco.
  • Associare su una connessione. Porta le associazioni sotto features: della voce, indicizzate per uno slot che il socket dichiara nel proprio featuresSchema — gli stessi slot che riempie la voce di connessione dello sviluppatore. Ciascuna porta type, una description facoltativa e infra, e mai values. Sotto uno slot che lo sviluppatore ha già riempito sulla stessa connessione, la voce dimensiona quell’associazione: scrivi solo infra, poiché il tipo e i valori provengono dall’Aggregate (un type scritto qui deve concordare con quello dell’Aggregate, altrimenti la build si arresta su questa voce, indicandoli entrambi). Sotto uno slot che lo sviluppatore ha lasciato vuoto, l’associazione è della Release stessa e type è obbligatorio. In entrambi i casi il riempimento è vincolato al selector dello slot e conta per uno slot required, esattamente come quello dello sviluppatore.

La superficie è crea-non-reindirizzare: una Release può aggiungere un arco verso un socket non vincolato, ma non può reindirizzare un arco che lo sviluppatore ha già dichiarato. Una voce per arco che indica un target diverso da quello dell’arco dello sviluppatore arresta la build; una voce che indica lo stesso target (o lo omette) configura quell’arco. La Release inoltre non può dichiarare values su un arco o su un’associazione che vi scrive (i valori rivolti allo sviluppatore restano nell’Aggregate), vincolare un socket che lo usesSchema non dichiara, né puntare un arco verso un componente che non esiste — ciascuno di questi è un arresto fatale. Lo è anche una voce che imposta infra o features su una connessione che non esiste una volta tracciati tutti gli archi, a meno che il componente consumatore non sia disattivato con active: false. Vedi errors/fatal-halts.md §«Durante la costruzione della topologia».

Altri tre arresti mantengono le associazioni di una connessione sulla loro connessione:

  • Un nome per cui il socket non dichiara alcuno slot provoca un arresto, esattamente come accade sulla voce di connessione dell’Aggregate, su questa voce della Release, indicando gli slot che il socket dichiara e quelli da cui il nome dista una sola modifica.
  • Un’associazione che solo la Release crea, scritta senza type, provoca un arresto sulla voce di connessione, indicando lo slot. Un’associazione creata dalla Release non porta values, quindi si adatta a una Feature i cui values non richiedono nulla; una il cui schema richiede un valore provoca un arresto per il valore mancante sulla stessa voce. Le Features di credenziali della libreria standard che portano il localizzatore di un chiamante non richiedono nulla in values: ciascuna lo accetta anche in infra (vedi sotto).
  • Il nome composto scritto in un punto diverso dalla connessione provoca un arresto. Un’associazione di connessione diventa un’associazione del componente consumatore chiamata <alias>.<slot> (vedi la voce di connessione dell’Aggregate), e sia le chiavi features: proprie di una voce di componente sia quelle di un confine ammettono un punto. Una voce di componente che scrive quel nome, o un confine che lo scrive in modo che raggiunga un componente la cui connessione lo porta — un componente collocato in quel confine o in uno annidato al suo interno, compresi quelli di un sottomodulo instradato — provoca un arresto indicando entrambe le grafie, una volta per ogni componente che raggiunge. Lo slot di un socket si riempie su ciascuna connessione e mai tramite un’associazione che scende in cascata da un ambito più ampio.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Una credenziale su una connessione che la Release collega indica il proprio segreto in infra. Una connessione che la Release collega non ha alcuna voce nell’Aggregate, quindi lì nulla scrive i values della credenziale, e la Release non scrive values da nessuna parte. Ogni Feature di credenziali della libreria standard che porta il localizzatore di un chiamante — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — lo accetta quindi in infra oltre che in values: origin, oppure entries per core/referenced-secret-set, con la stessa forma e la stessa dichiarazione sensitive: true in entrambi i pilastri. Ogni realizzazione legge il pilastro che lo porta.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Il localizzatore si scrive in esattamente un pilastro per associazione. Un’associazione che lo porta in entrambi — i values dell’Aggregate e l’infra della Release per lo stesso slot — o in nessuno dei due si arresta sull’asserzione della Feature stessa (E0033), indicando la Feature, l’associazione e il componente, e dicendo quale dei due casi si è verificato. La regola appartiene alle entità del catalogo di quelle Features, non al compilatore, che valuta la loro asserzione come valuta quella di qualsiasi Feature. I campi diversi dal localizzatore mantengono il proprio pilastro: key resta una foglia di values, quindi un’associazione che solo la Release crea legge la chiave dati predefinita della Feature, value. Il divieto di values: è invariato — il localizzatore dell’operatore è infra.

core/secret-provided è quella che non si adatta a una connessione: pubblica il proprio valore perché lo consegni il blocco inject: dell’associazione stessa, e l’associazione di una connessione non porta alcun blocco inject: in nessuno dei due documenti, quindi su una connessione nessun blocco inject: lo consegna. Lì usa core/referenced-secret o core/secret-value.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

L’infra per arco risolto confluisce nel contesto di rendering del componente consumatore in .context.uses.<alias>.infra.<key>; non compare mai nel contesto del componente target, quindi l’output prodotto per un target è invariante rispetto ai consumatori che configurano archi verso di esso. Anche un’associazione su una connessione arriva sul componente consumatore, come una delle sue associazioni: il suo infra si fonde con i values dell’Aggregate per lo stesso slot, e la sua FeatureRecipe esegue il rendering rispetto a entrambi. La Recipe del componente consumatore la legge sotto la sua connessione, in .context.uses.<alias>.features.<slot>, e il suo Workload la consegna indicando la connessione accanto allo slot — vedi Consegnare una credenziale che una connessione porta.

Il campo aggregates: — instradare i sottomoduli annidati nei confini

Quando l’Aggregate dichiara sottomoduli annidati tramite spec.aggregates:, la Release decide in quale confine finiscono i componenti di ciascun sottomodulo dichiarando aggregates: accanto a components: all’interno del confine di destinazione:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Colloca ogni sotto-aggregato elencato in Aggregate.spec.aggregates: in esattamente un confine.

L’instradamento colloca i componenti. Ogni componente di un sottomodulo instradato finisce nel confine che lo instrada e ne assume directory, subDirectory, syncWave e la cascata di annotazioni — lo stesso contesto che riceve un componente nominato direttamente sotto components:, compresa la provenienza aggrega.ai/boundary-path apposta sugli artefatti emessi. Instradare un sottomodulo e indirizzare ciascuno dei suoi componenti tramite percorso puntato qualificato con un corpo vuoto producono quindi artefatti identici; l’instradamento è il modo più breve per dirlo, e l’unico modo per dirlo senza conoscere il contenuto del sottomodulo.

Un componente appartiene a esattamente un confine, e la build si interrompe quando un documento ne colloca uno due volte — lo stesso sottomodulo instradato in due confini, un sottomodulo instradato in un confine mentre uno dei suoi componenti è nominato in un altro, oppure un componente nominato sia direttamente sia tramite una voce di instradamento. Il messaggio diagnostico nomina entrambi i punti, perché quale mantenere è una decisione dell’autore. Instradare un sottomodulo in un confine e nominare uno dei suoi componenti sotto quello stesso confine non è un conflitto: l’instradamento colloca il componente e la voce nominata lo configura.

Un sotto-aggregato che la Release non colloca da nessuna parte interrompe la build. La collocazione viene letta su entrambe le grafie, quindi la build si interrompe solo quando nessuna delle due raggiunge il sottomodulo: nessun confine lo instrada sotto aggregates:, e nessun confine nomina alcuno dei suoi componenti sotto components: tramite percorso puntato qualificato. Ciascuna grafia da sola lo colloca, e un sottomodulo i cui componenti sono tutti nominati singolarmente non ha bisogno di una voce di instradamento. La correzione va nel blocco aggregates: dell’Aggregate che ha importato il sottomodulo — l’Aggregate che la Release distribuisce, per uno che importa direttamente, e il documento stesso del sottomodulo importatore, per uno annidato. Il messaggio diagnostico nomina quella voce con la chiave con cui la scrive il documento importatore, quindi per un sottomodulo annidato si legge come il nome locale anziché come il percorso puntato.

Due casi volutamente non interrompono la build. Un sottomodulo che non contribuisce alcun componente non ha nulla da collocare. Un sottomodulo il cui interruttore active: si risolve in false non è mai stato composto, quindi nessuno dei suoi componenti esiste per essere collocato.

La collocazione parziale non fa scattare questa regola: un sottomodulo è collocato non appena uno qualsiasi dei suoi componenti raggiunge un confine, quindi nominarne uno soddisfa il sottomodulo. Non ne consegue che gli altri possano essere tralasciati. Ogni componente che il confine non ha nominato non è allora collocato da nulla, e la regola sui componenti più sotto lo segnala alla sua chiave — quindi un sottomodulo collocato in parte interrompe la build una volta per ogni componente che ha lasciato indietro, non al sottomodulo. Le due grafie che collocano un intero sottomodulo in una riga sono la voce di instradamento e la nomina di ogni componente; qualsiasi cosa tra le due colloca ciò che nomina e niente di più.

Anche un componente che la Release non colloca da nessuna parte interrompe la build, un livello più in profondità. La regola precedente chiede se un sottomodulo ha raggiunto un confine; questa chiede lo stesso per ogni componente contenuto nella composizione. Un componente raggiunge un confine venendo nominato sotto components: di quel confine, oppure trovandosi all’interno di un sottomodulo che un confine vi instrada. Uno che non raggiunge né l’uno né l’altro viene renderizzato fuori da ogni confine dichiarato dalla Release, prendendo directory, subDirectory, syncWave, la cascata di annotazioni e infra: per componente dal nulla — quindi la build si ferma e nomina il componente anziché emettere artefatti che la configurazione dei confini non ha mai raggiunto.

Le due regole si dividono il campo chiedendo del sottomodulo del componente, non solo chiedendo se ne ha uno. Un componente di un sottomodulo che la Release non ha collocato da nessuna parte è lasciato alla regola sui sottomoduli, che segnala quell’unico errore dell’autore una sola volta alla voce aggregates: anziché una volta per ogni componente che il modulo contiene. Un componente di un sottomodulo che la Release ha collocato in parte spetta a questa regola, perché la regola sui sottomoduli legge un tale modulo come collocato e non dice nulla al riguardo — quindi ogni componente che il confine non ha nominato è segnalato qui, alla sua chiave all’interno del documento che lo dichiara. Collocare un sottomodulo in parte nomina quindi esattamente ciò che intendevi nominare, e ti segnala ogni componente che non hai nominato.

E una voce di confine che nomina un componente che l’Aggregate distribuito non contiene interrompe la build. Le due regole precedenti leggono la collocazione dal lato del componente — qualcosa lo ha collocato? Questa la legge dal lato della Release: il nome si risolve? Una voce che non si risolve in nulla non colloca nulla, quindi il suo subDirectory, le sue annotazioni, il suo infra: per componente e il suo uses: configurano un componente che non c’è, e la build si ferma anziché emettere una distribuzione che la voce non ha mai raggiunto. Vengono verificate entrambe le grafie: un nome sotto components: di un confine viene letto come l’id che il componente porta una volta completata la composizione, e un nome sotto components: di una voce di instradamento viene letto come il nome locale che porta all’interno di quel sottomodulo. Il messaggio diagnostico riporta l’id indirizzato dalla voce, che nella grafia instradata non è il nome nel file — il file scrive la metà locale e il sottomodulo ne fornisce il prefisso.

Un nome viene rifiutato perché non si risolve in nulla e mai per la sua forma: un nome puntato è normale, perché un componente un modulo più in profondità porta il prefisso di quel modulo. Un componente il cui interruttore active: si risolve in false resta nominabile — disattivare un componente non richiede di modificare la Release che lo configura.

Un sottosistema non contribuisce nulla al percorso qualificato, quindi un confine indirizza un componente con il suo nome semplice comunque l’Aggregate lo raggruppi. Solo la composizione dei sottomoduli qualifica un id. Un componente dell’Aggregate distribuito è store sia che l’autore lo abbia scritto al livello superiore sia all’interno di un sottosistema chiamato data; un componente un modulo più in profondità è data.store, e lì data è il prefisso del modulo anziché quello di un sottosistema. Quindi una voce di confine scritta data.store per un componente che si trova in un sottosistema chiamato data non indirizza nulla: la voce stessa interrompe la build in base alla regola precedente, e nemmeno il componente a cui era destinata raggiunge un confine. Correggere la voce in store risolve entrambe le cose.

Collocare un sottomodulo richiede quindi boundaries:. La forma ad ambito singolo non ha una superficie di instradamento — aggregates: è una chiave di un confine, non di spec: — e la mappa components: di primo livello accetta solo nomi non qualificati, quindi una Release che distribuisce un Aggregate che importa sottomoduli dichiara boundaries:.

Instradamento ricorsivo. aggregates: è ricorsivo — ogni voce sotto aggregates: di un confine può a sua volta dichiarare una mappa aggregates: annidata per una composizione di moduli profondamente annidata.

Blocco di instradamento per aggregato. Una voce di instradamento accetta esattamente due chiavi e nient’altro: components:, per configurare singoli componenti di quel sottomodulo, e un aggregates: annidato per i moduli annidati più in profondità. annotations: appartiene al confine, e infra: per componente appartiene a una voce sotto il components: della voce di instradamento stessa.

All’interno di una voce di instradamento un componente ha come chiave il nome che porta all’interno del suo sottomodulo — consumer, non data.consumer — perché è l’unico nome che ha lì. Il percorso puntato qualificato è il modo in cui la mappa components: di un confine indirizza lo stesso componente; le due grafie non sono intercambiabili, e una voce di instradamento rifiuta una chiave puntata.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

I componenti e le Features propri del sotto-aggregato non vengono ridichiarati nella Release — la Release li instrada anziché ripeterli, e ne nomina uno solo per configurarlo.

Sequenziamento temporale — syncWave per confine

Ogni confine nella Release dichiara facoltativamente un campo intero syncWave:, che dà all’operatore un controllo esplicito sull’ordine di distribuzione senza toccare l’Aggregate dello sviluppatore. Il numero di ondata è una proprietà del confine stesso; ogni componente contenuto nel sottoalbero del confine eredita il valore di ondata del proprio confine quando vengono emessi gli artefatti.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Semantica del valore di ondata. syncWave: è un intero con segno (positivo, zero o negativo). Il valore predefinito quando il campo è omesso è 0. I valori di ondata non vengono ereditati da un confine padre — ogni confine che vuole un’ondata non predefinita ne dichiara una esplicitamente. I Components non possono sovrascrivere l’ondata del proprio confine (l’ondata è una proprietà dell’unità spaziale, non dei singoli componenti).

Emissione per provider. Il compilatore emette il valore di ondata del confine nell’output renderizzato, nella forma nativa del provider. Tre delle forme sono illustrate di seguito; ciò che l’ondata fa su ogni provider della libreria standard, terraform compreso, è riportato in tabella in providers/reference-matrix.md «Cosa fa la syncWave di un confine su ciascun provider».

  • Kubernetes (provider helm / helm-chart). Dove l’ondata non è 0, ogni risorsa Kubernetes che il provider helm renderizza per il confine porta l’annotazione argocd.argoproj.io/sync-wave: "<N>", standard in GitOps; gli hook Helm portano inoltre l’annotazione helm.sh/hook-weight: "<N>", così che lo stesso valore di ondata guidi l’ordinamento pre/post-install proprio di Helm. ArgoCD legge l’annotazione sync-wave e Helm legge il peso di un hook, e ciascuno ordina di conseguenza l’applicazione delle risorse. Il provider helm-chart copia i template di un chart sorgente così come li ha scritti il loro autore, quindi le risorse proprie di un sub-chart portano l’ondata solo dove quei template la scrivono; un artefatto caricato tramite $import: che il provider aggiunge porta argocd.argoproj.io/sync-wave e nessun helm.sh/hook-weight (vedi providers/helm-chart.md).
  • Compose. Ogni servizio nel file compose in cui un confine viene renderizzato attende, tramite depends_on, i servizi dell’ondata immediatamente precedente che hanno contribuito allo stesso file — subordinatamente allo stato di salute del destinatario dove il destinatario dichiara un healthcheck, e al suo avvio dove non lo dichiara. Quindi l’ondata ordina i servizi di un file e nulla al di fuori di esso: i confini che vengono renderizzati in file docker-compose.yaml separati sono progetti compose separati, e sequenziarli è compito dell’operatore. Gli archi uses: continuano a esprimere l’ordinamento per arco accanto all’ondata. Vedi providers/compose.md.
  • CloudFormation. Ogni risorsa nel template dello stack assemblato dipende, tramite DependsOn, dalle risorse dell’ondata immediatamente precedente che hanno contribuito allo stesso stack — quindi l’ondata fissa l’ordine in cui le risorse vengono create e, al contrario, l’ordine in cui vengono eliminate. Non è un ordinamento per disponibilità: un template di stack non ha la nozione di una risorsa pronta all’uso. Il DependsOn proprio di un frammento viene esteso anziché sostituito. I Components che vengono assemblati in uno stack diverso sono fuori portata, e sequenziare due stack è compito dell’operatore. Vedi providers/cloudformation.md.

Unità di scrittura delle ondate e unità distribuibile. Il confine è l’unità in cui si scrivono le ondate. L’unità distribuibile è il percorso di assemblaggio in cui vengono emessi i componenti — per impostazione predefinita 1:1 con il confine, ma due confini fratelli che condividono una directory: confluiscono in un unico output assemblato (un Chart.yaml, un docker-compose.yaml). Quando ciò accade, l’output assemblato può contenere risorse di più ondate; un’Application di ArgoCD che lo legge ordina, all’interno dell’Application, ogni risorsa in base all’annotazione sync-wave che quella risorsa porta — su helm ogni risorsa renderizzata per un’ondata diversa da zero, e su helm-chart solo un artefatto caricato tramite $import:, mentre i template propri di un sub-chart portano ciò che il loro autore ha scritto. Il sequenziamento tra Application su percorsi diversi è compito della CI dell’operatore.

Casi d’uso. L’ordinamento per ondate conta ogni volta che l’avvio di un confine dipende dal completamento precedente di un altro. Schema canonico: un confine infra all’ondata 0 (VPC + database), un confine migrations all’ondata 1 (job di migrazione dello schema) e un confine apps all’ondata 2 (l’applicazione che consuma lo schema migrato). Senza ondate esplicite, tutti e tre vengono distribuiti contemporaneamente e l’applicazione va in crash-loop mentre attende il completamento della migrazione.

Per l’inquadramento architetturale completo — il modello di esecuzione a DAG, la motivazione per collocare il sequenziamento temporale sulla Release anziché sull’Aggregate, e la distinzione tra unità di scrittura delle ondate e unità distribuibile — vedi architecture/12-day-two-lifecycles.md §1.

Associazione di Feature

La Release può associare Features sia a livello di confine (policy ampia) sia a livello di singolo componente (targeting preciso), con un’esecuzione che segue il modello a cipolla a 5 livelli definito in architecture/10-compilation-pipeline.md. Le Features dichiarate nella Release forniscono type, infra e uses; non possono dichiarare values (vedi Vincoli a livello di schema sopra).

Una Feature associata a un confine ha come chiave un nome di istanza che scegli tu, e quel nome non può essere . o ... Su un provider che dà a ogni contributore una propria directory — terraform, sotto modules/, e helm-chart, sotto charts/ — i file di una Feature a livello di confine vengono scritti in una directory che porta il solo nome dell’istanza, e nessuno di quei due nomi è una directory a sé: la build si ferma, nominando la Release, il confine e l’istanza. Un nome che si limita a contenere punti, come audit.v2, è un nome normale.

features: è l’unica superficie di associazione della Release, a entrambi i livelli — come lo è per l’Aggregate. Una credenziale è una Feature che porta l’etichetta feature.aggrega.ai/kind: secret, quindi una credenziale associata dall’operatore viene associata sotto features: come qualsiasi altra Feature, e nomina il proprio segreto in infra esattamente come fa una credenziale su una connessione (vedi Configurazione della connessione per arco) — su un componente che l’Aggregate ha lasciato senza, oppure come dimensionamento di un’associazione che l’Aggregate ha dichiarato senza nominare un segreto. Non esiste una seconda parola chiave di associazione a nessun livello; un documento che ne dichiara una viene rifiutato al caricamento con un errore di envelope che nomina la proprietà inattesa.

Una funzionalità associata all’intero confine può portare un blocco uses:, e quel blocco si proietta su ogni componente instradato nel confine: ogni componente ottiene un arco di dipendenza verso i destinatari nominati dalla funzionalità e riceve per iniezione i provides di quei destinatari. Questo esprime una dipendenza condivisa una sola volta al confine — «ogni componente in questo confine comunica con la cache / il collector / il message bus condivisi» — anziché ripetere lo stesso arco uses: su ogni componente. Un’associazione di Feature a livello di sottosistema nell’Aggregate proietta il proprio uses: allo stesso modo sui componenti del sottosistema. uses è una dichiarazione di cablaggio della topologia, non un valore, quindi è consentita nella Release. La proiezione è indipendente dall’ambito di esecuzione della Feature associata: una Feature la cui FeatureRecipe viene renderizzata una volta per confine proietta comunque il proprio uses: per componente, mentre la risorsa condivisa stessa viene renderizzata una volta.

Una funzionalità associata a un singolo componente porta lo stesso blocco uses: e cabla lo stesso arco a partire da quell’unico componente: il componente ottiene un arco di dipendenza verso ciascun destinatario nominato, riceve per iniezione i provides di quei destinatari, e l’arco registra l’associazione come propria origine esattamente come fa la forma estesa all’intero confine. Le due sono un’unica dichiarazione a due ampiezze — associa al confine per cablare ogni componente in esso, associa su un componente per cablare quello — e la scelta tra le due è una questione di portata, mai di ciò che il cablaggio fa. Nessuna delle due crea risorse di calcolo: il destinatario deve già nominare un componente che l’Aggregate ha dichiarato, e uno che non lo fa interrompe la build. Una connessione tracciata da una Feature non porta associazioni proprie: la sua voce accetta target e inject, e una chiave features: lì viene rifiutata quando la Release viene caricata.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Come si scrive un destinatario. Un destinatario di arco nomina un componente del grafo assemblato, quindi si scrive con il percorso puntato qualificato — data.store, non store — ogni volta che il destinatario appartiene a un sottomodulo instradato. Questo vale anche dove l’associazione stessa si trova sotto una voce di instradamento, le cui chiavi components: sono locali al modulo: la chiave dice su quale componente si trova l’associazione e il destinatario dice quale componente raggiunge l’arco, e solo il secondo è un nome valido in tutto il grafo. Un destinatario scritto con un nome locale al modulo non corrisponde ad alcun componente e interrompe la build con lo stesso messaggio diagnostico prodotto da qualsiasi arco pendente.

Release composita ed ereditarietà tramite extends:

Una Release può dichiarare spec.extends: puntando a una Release di base di cui eredita la superficie di authoring.

Il riferimento è un percorso verso un file accanto alla Release che lo dichiara — ./base-release.yaml, oppure ../shared/base-release.yaml. Una Release appartiene al lato della distribuzione e non è indicizzata nel catalogo, quindi un riferimento extends: non si risolve mai tramite il catalogo. Il percorso relativo è l’unica forma che accetta: un riferimento scritto come coordinata di registry viene rifiutato, e così un nome semplice, ciascuno con la forma a percorso relativo indicata nella diagnostica. L’extends: di un Manifest è il vicino prossimo che si legge in modo diverso — accetta un percorso relativo oppure il metadata.name semplice di un Manifest accanto alla Release — quindi le due forme non sono intercambiabili, e un nome semplice che si risolverebbe su un Manifest qui non si risolve. Ogni anello di una catena si legge allo stesso modo: una Release genitore conservata in un’altra directory nomina il proprio genitore con un percorso accanto a sé, ovunque si trovi la Release che hai indicato, esattamente come il suo $import: dei parametri si risolve accanto a essa. Il percorso deve condurre a una Release all’interno del workspace, come deve fare ogni percorso che una Release scrive — oppure, per una Release indicata fuori dal workspace, all’interno della directory che contiene quella Release, a cui è vincolato ogni anello della sua catena: un percorso che ne esce risalendo, o che un anello porta fuori, viene rifiutato prima che il file che indica venga letto.

Il compilatore segue la catena quando la Release viene caricata — rifiutando una catena che ritorna a un file già presente in essa, una che supera il limite di profondità e un riferimento che non indica nulla — e poi riduce la catena a un’unica Release risolta.

Ciò che erediti, puoi sostituirlo chiave per chiave. Il tuo valore prevale, fino in fondo, finché non raggiungi un valore che è un’unica cosa indivisibile — uno scalare, una lista, un template — che prendi o sostituisci per intero. Rimuovi qualcosa che hai ereditato scrivendolo null. È la stessa regola che seguono un Component, una Feature e un Manifest che estendono, quindi un autore che ne ha incontrato uno li ha incontrati tutti.

Applicato a una Release: boundaries si compongono per nome di confine e un confine per chiave, components per nome di componente, infra in profondità, features per nome di istanza e poi per pilastro; gli uses di un componente per socket e poi per connessione, dove un target scritto dal figlio sostituisce quello ereditato, l’infra della connessione si compone chiave per chiave, e le sue features si compongono per slot e poi per pilastro secondo la stessa regola seguita dalle features proprie di un componente; directory, subDirectory, syncWave e i puntatori all’Aggregate e al Manifest sono scalari che sostituiscono.

Due cose non si trasmettono:

  • Identità e provenienza. Nessun campo metadata viene ereditato. metadata.environment è quello da tenere presente: è obbligatorio in ogni Release ed è per natura specifico di ciascuna Release, quindi un figlio esegue il rendering con il proprio ambiente nelle etichette di provenienza anziché con quello del genitore.
  • Il puntatore all’Aggregate è ereditato anziché sovrascrivibile. Il figlio non può dichiarare aggregate: — lo schema rifiuta extends: e aggregate: in un unico documento — quindi un figlio distribuisce lo stesso intento dello sviluppatore della sua base.

Il figlio può omettere manifest:, ereditando quello della sua base, oppure sovrascriverlo per il Late Binding.

Una sola forma di instradamento lungo la catena. boundaries: e components: si escludono a vicenda all’interno di una singola Release, e questo vale anche lungo una catena: la combinazione di una base che dichiara confini con nome e di un figlio che dichiara componenti di primo livello viene rifiutata, e la diagnostica nomina entrambi i file ed entrambe le chiavi. Scegli una forma di instradamento e usala fino in fondo.

Il pattern ponte per lo sviluppo locale. Il caso d’uso canonico è uno sviluppatore che esegue in locale l’Aggregate di produzione del proprio team senza fare il fork dell’Aggregate né duplicare la topologia dei confini. Il team pubblica una Release di produzione; una Release locale la estende tramite extends: e sovrascrive solo il puntatore al Manifest, sostituendo le Recipes destinate al cloud con equivalenti locali:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release eredita dalla sua base la topologia dei confini, le associazioni di Feature e le sovrascritture dei componenti; lo sviluppatore mantiene un solo local-release.yaml ed esegue aggrega build --release local-release.yaml senza duplicare alcuna configurazione di produzione.

Scrivi directory: in funzione di un parametro. Poiché una directory si eredita come qualsiasi altro scalare, un figlio che eredita una directory priva di variabili di template esegue il rendering nello stesso percorso della sua base, e nessuna opzione da riga di comando lo reindirizza. È legittimo quando è ciò che intendevi — sostituire solo le Recipes per confrontarne l’output, ad esempio — quindi la build lo segnala e prosegue anziché rifiutarlo. Scrivere la directory in funzione di un parametro, come sopra, mantiene la topologia in un solo posto e invia comunque l’output di ciascuna Release in una posizione propria.

Stratificazione dei parametri su più file. L’ereditarietà tra Release è la sede della stratificazione dei parametri su più file. Una Release di base fornisce l’insieme comune di parametri; i figli per ambiente estendono la base tramite extends: e sovrascrivono gli slot che differiscono:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Ogni figlio vede i parametri ereditati dalla sua base uniti ai propri. I parametri con valore mappa si uniscono in profondità con prevalenza della chiave del figlio; i parametri con valore scalare vengono sostituiti dal figlio; una chiave che un figlio scrive come null viene rimossa anziché impostata a nulla.

Una base può importare i propri parametri e un figlio può comunque sovrascrivere singole chiavi. Le due modalità di authoring descritte sopra in parameters: — inline, oppure un singolo $import: — sono una regola su un documento, non su una catena: ogni Release lungo la catena dichiara l’una o l’altra modalità, e l’import di ciascuna si risolve rispetto alla directory che contiene quella Release prima che la catena venga ridotta. Quindi una base che importa un file condiviso e un figlio che scrive alcune chiavi inline si compongono per chiave, esattamente come farebbero due blocchi inline:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Modalità di errore. Catene extends: cicliche, puntatori al genitore mancanti e dichiarazioni aggregate: lato figlio interrompono tutte il caricamento del workspace con diagnostiche esplicite che nominano la Release incriminata e la violazione a livello di schema. Vedi errors/fatal-halts.md per la forma dei messaggi di ciascun errore.