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

Matrice di espansione dei template

Riferimento dell’espansione dei template — la matrice completa

Il DSL di Aggrega supporta l’espansione text/template di Go (con la libreria Sprig preregistrata) in più punti delle entità YAML. Ogni punto ha un insieme specifico di riferimenti disponibili, determinato dal momento in cui i dati diventano concreti man mano che la compilazione procede. Questa pagina è il riferimento per ciò che si può referenziare e dove.

1. L’albero temporale della pipeline (quando i dati diventano concreti)

Capire quali riferimenti sono disponibili richiede di capire quando viene risolto ciascun dato. Le fasi qui sotto sono elencate nell’ordine in cui vengono eseguite, e ciascuna prende il nome da ciò che fa — quel nome è il modo in cui il resto di questa pagina vi fa riferimento:

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. La matrice di espansione dei template

Ogni punto del DSL in cui vengono valutate espressioni di template Go, ed esattamente quali riferimenti sono disponibili:

#LocationEntitàValutato inRiferimenti disponibili
1{{ .parameters.X }} nelle stringhe YAML dell’AggregateAggregateRisoluzione (interpolazione)Solo .parameters. Tutti gli altri dati non sono ancora risolti.
2{{ .parameters.X }} nelle stringhe YAML della ReleaseReleaseNon valutatoNessuno. Le stringhe di una Release vengono lette così come sono scritte: un {{ .parameters.X }} sotto infra:, in un’annotazione o come valore di parameters: raggiunge la sua destinazione come quel testo letterale. La Release fornisce i valori dei parametri (la mappa parameters: inline e i valori caricati con $import: combinati nella mappa dei parametri unita); le stringhe dell’Aggregate li leggono (#1), e così fanno i template di percorso (#3).
3Template directory / subDirectoryConfine della ReleaseRendering (valutazione dei percorsi).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* e .component_id (solo subDirectory: — un template directory: lo rifiuta).
4Stringhe value: di inject del ComponentComponente dell’AggregateRisoluzione di self-inject.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (tutti e 3 i contenitori), .metadata.* (release_name, release_version, environment, aggregate_name). VIETATO: .context.inject (circolare — la pipe è in costruzione), .context.uses (usa invece uses[].inject per il cablaggio tra componenti). Il template si trova nel testo dell’Aggregate, che l’interpolazione dei parametri di #1 legge per prima, quindi scrivilo con l’escape — value: '{{"{{"}} .metadata.release_name }}' — perché raggiunga questa fase; scritto in modo semplice, l’interpolazione lo valuta e si arresta, poiché il testo di un Aggregate non definisce alcuna radice tranne .parameters.
5Stringhe del campo source (stringa di primo livello OPPURE sottocampi con valore stringa di una mappa source: strutturata)Recipe / FeatureRecipeRisoluzione della sorgenteDue superfici, decise da ciò che la sorgente nomina. Una coordinata remota — version, chart, ref e module_subdir di un blocco strutturato che nomina un registry, un repository di chart o un repository git — viene valutata quando aggrega pull risolve l’artefatto per fissarlo: solo .values, .infra, .locals e stringhe statiche, con gli helper propri di Aggrega (optional, capitalizedWords, index) e nessuna delle funzioni di Sprig, e nessuna radice .context. Le voci di .locals valutate lì sono quelle che quei campi leggono, direttamente o tramite un’altra voce — tutte le voci, dove un campo legge .locals in un modo che non nomina alcuna voce singola — quindi una voce che nessun campo legge viene lasciata al rendering. Una sorgente che nomina un percorso nel workspace viene valutata mentre l’entità esegue il rendering: .context.instance_id, .values, .infra, .locals (l’intero blocco risolto dell’entità dichiarante), stringhe statiche. Lì la sorgente di una FeatureRecipe legge inoltre .attachment_name — ciò che viene risolto è un’associazione — e il suo .context.instance_id nomina il componente host, accanto a .context.rendered_name, il nome riportato del componente host (vedi #9); una FeatureRecipe con ambito di confine legge .boundary.* e nessuno dei pilastri per componente. VIETATO su entrambe: .context.inject, .context.uses, .provides (invariante di autocontenimento — la superficie della sorgente nel workspace condivide il proprio contesto con i locals propri dell’entità dichiarante, quindi le due ammettono e rifiutano gli stessi riferimenti, e una coordinata remota legge un sottoinsieme di quel contesto; la risoluzione della sorgente deve completarsi prima che la pipe della topologia venga idratata e prima che venga caricato qualsiasi chart, modulo o corpo di artefatto).
6Template provides della RecipeRecipeValutazione dei provides.context.instance_id, .context.rendered_name (il nome che il provider del nodo dà all’output che renderizza per il nodo — da una sorgente fornita dall’autore, o da un workload che sintetizza; leggerlo su un nodo il cui provider non riporta alcun nome di questo tipo provoca un arresto — vedi Assegnare un nome a una risorsa renderizzata), .values, .infra, .locals (l’intero blocco risolto del nodo — i locals si risolvono nel preambolo di questa fase, prima dei provides), stringhe statiche. VIETATO: ogni altra radice — .context.inject, .context.uses (tra nodi), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (legato a collocazione/distribuzione) e .attachment_name (nessuna associazione viene risolta durante la valutazione dei provides di una Recipe di base). Il controllo è una allowlist positiva: fare riferimento a qualsiasi radice che il contesto dei provides non espone provoca un arresto (invariante di autocontenimento — consente la valutazione parallela senza alcun ordinamento topologico). Anche un .locals.<key> che nomina una chiave che il blocco dei locals non dichiara provoca un arresto, poiché il pilastro è una mappa aperta con chiavi che il solo controllo della radice non può sorvegliare.
7valuesMapping della Recipe (inline, $import: di file o $import: di libreria)RecipeRendering di baseContesto di template completo: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Un riferimento .context.rendered_name scritto inline provoca un arresto su un nodo il cui provider non riporta alcun nome di questo tipo, come in #6; uno all’interno di un corpo caricato con $import: non viene controllato, e su un tale nodo viene renderizzato vuoto.
8injectMapping della FeatureRecipeFeatureRecipeMappatura di injectContesto di template completo: .values, .infra, .context.* (incluso .context.inject — la pipe che viene intercettata — e .context.uses). .context.used_by qui è vuoto: l’output della mappatura arriva sulla pipe di consegna propria dell’host. .context.render_facts è assente: la mappatura viene eseguita prima che l’host esegua il rendering. .context.rendered_name è il nome riportato del componente host, come in #9; una mappatura che lo legge non viene controllata, e lo renderizza vuoto su un host il cui provider non ne riporta alcuno. Lo stesso contesto qualunque sia l’impostazione executionScope della FeatureRecipe: la mappatura di una FeatureRecipe con ambito di confine viene eseguita una volta per ciascun componente che l’associazione raggiunge, legge il .context.* di quel componente, e legge .features.<attachment>.provides e .locals come l’unica valutazione del confine. VIETATO: .boundary, che il contesto di nessun componente porta — un riferimento arresta la build.
9valuesMapping della FeatureRecipe (e i suoi workload: e artifacts:)FeatureRecipeRendering di baseContesto di template completo + .attachment_name, .inject (le voci inject: proprie dell’associazione, dove l’associazione scrive un blocco inject:), .context.render_facts — ciò che il provider dell’host ha riportato sul rendering dell’host — e .context.used_by — i componenti che usano l’host, ciascuno con i propri fatti di rendering dove la FeatureRecipe imposta readsCallerRenderFacts: true. Ogni connessione su .context.uses porta i fatti di rendering della propria destinazione, in .render_facts, dove la FeatureRecipe imposta readsTargetRenderFacts: true. .context.instance_id e .context.rendered_name sono l’identità del componente host e il nome che il provider proprio dell’host riporta per esso — lo stesso valore che legge la Recipe dell’host, anche sui locals: e provides: della FeatureRecipe — e un riferimento a .context.rendered_name scritto inline provoca un arresto su un host il cui provider non riporta alcun nome di questo tipo. .source è il source: valutato proprio della FeatureRecipe, mai quello del componente host, e non contiene nulla dove la FeatureRecipe non ne dichiara alcuno.
10Blocchi with: della pipelineRecipe / FeatureRecipeLa pipeline di pluginContesto di template completo + .steps (output tra i passi provenienti dai passi precedenti della pipeline). .context.used_by qui è vuoto, e nessuna connessione su .context.uses porta i fatti di rendering della propria destinazione: un passo può riscrivere i documenti propri dell’host. Il passo di una FeatureRecipe associata legge .context.render_facts, i fatti di rendering propri dell’host, come fa #9.
11Corpo workload: della Recipe (ogni campo con template al suo interno, sia inline sia caricato con $import:)RecipeRendering di baseContesto di template completo. Ogni campo all’interno del corpo del Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — fa parte della stessa valutazione di template che consuma l’intera stringa del Workload. Il contenuto del Workload è un unico template Go valutato una sola volta rispetto al contesto di template completo; i template a livello di campo al suo interno si risolvono nella stessa valutazione anziché in una separata.

Nota sull’autocontenimento. Le stringhe source (#5) condividono l’invariante di autocontenimento di provides (#6): entrambe le superfici rifiutano i riferimenti a .context.inject e .context.uses. La risoluzione della sorgente viene eseguita prima dell’idratazione di inject che popola .context.inject, e prima che qualsiasi elemento a valle consumi la sorgente risolta — quindi la regola e la sua motivazione valgono per entrambe le superfici. Dove le due differiscono è il pilastro provides: una source del workspace condivide il proprio contesto con i locals dell’entità dichiarante, e una coordinata remota ne legge un sottoinsieme, quindi entrambe rifiutano .provides, mentre provides è esso stesso la superficie che viene risolta. Entrambe leggono .locals. La regola raggiunge la source di una FeatureRecipe alle stesse condizioni in cui raggiunge quella di una Recipe, ciascuna controllata rispetto alla superficie locals propria di quell’entità.

Nota sui template nel corpo del Workload (#11). Il corpo del Workload è un’unica stringa con template che il renderer valuta nel suo insieme, per poi analizzare il risultato come documento Workload. I template a livello di campo al suo interno (un replicas: {{ .infra.replicas | default 1 }} qui, un LOG_LEVEL: "{{ .values.log_level }}" dentro containers.app.variables là) non sono punti di valutazione dei template separati — partecipano tutti all’unica valutazione del rendering di base che produce il Workload. Gli autori non hanno bisogno di una regola di disponibilità separata per i campi interni al Workload; la regola per il Workload nel suo insieme (#11) copre ogni template a livello di campo al suo interno.

Fallback consapevole del discriminante all’interno del corpo del Workload. L’esempio replicas: {{ .infra.replicas | default 1 }} qui sopra confonde «l’autore non ha impostato replicas» con «l’autore ha impostato replicas a 0» — default scatta in entrambi i casi. Quando una Release scrive legittimamente infra.replicas: 0 per esprimere lo scale-to-zero (un pattern comune di Knative / KEDA), la forma | default 1 scavalca silenziosamente l’intento. La forma consapevole del discriminante è replicas: {{ optional .infra "replicas" 1 }} — optional controlla la presenza della chiave e restituisce il valore scritto dall’autore (zero scritto incluso) quando la chiave è impostata, ripiegando su 1 solo quando la chiave è assente. Vedi sprig-functions.md per la semantica completa e le indicazioni su quando preferirla.

3. Riferimenti vietati & motivazione

LocationRiferimento vietatoMotivazione
value: di inject del Component (#4).context.injectA quel punto la pipe di inject è in costruzione — un template value: di self-inject non può leggere dalla pipe a cui contribuisce.
value: di inject del Component (#4).context.usesIl cablaggio tra componenti si trova in uses[].inject. I template value: di self-inject di un componente restano chiusi sui dati propri del componente.
provides della Recipe (#6).context.injectI template dei provides vengono valutati in qualsiasi ordine e si chiudono solo sui dati propri del nodo (.values, .infra, .locals, .context.instance_id, .context.rendered_name). La pipe di inject non viene popolata fino all’idratazione di inject, che viene eseguita dopo che i provides di ogni nodo sono stati valutati.
provides della Recipe (#6).attachment_nameIl passaggio dei provides di una Recipe di base non risolve alcuna associazione, quindi il nome verrebbe renderizzato vuoto. La radice viene rifiutata anziché consegnata vuota.
source (#5).providesNessuna delle due superfici della sorgente porta un pilastro provides: la superficie della sorgente nel workspace condivide il proprio contesto con i locals propri dell’entità dichiarante, che non ne ha, e una coordinata remota legge un sottoinsieme di quel contesto. I locals si risolvono prima dei provides affinché provides: possa leggere .locals; il template della sorgente legge gli stessi locals anziché tornare indietro a cercare i provides.
locals della Recipe (preambolo di #6).providesI locals si risolvono prima dei provides, quindi i provides propri del nodo non esistono ancora quando un local viene valutato. Un local che ha bisogno di un valore che anche i provides pubblicano lo calcola direttamente da .values / .infra — e la voce provides legge poi il local.
locals della Recipe (preambolo di #6).context.rendered_nameI locals di una Recipe condividono il proprio contesto con il suo template source (#5), e quella superficie non offre il nome: se il nodo fornisce una sorgente, cosa che decide il template source, è una delle cose da cui dipende il nome. Il riferimento si arresta con la diagnostica di radice sconosciuta, che elenca .context.instance_id come ciò che .context definisce lì. Leggi invece la chiave in una voce provides, o in un template della fase di rendering di base.
provides della Recipe (#6).context.uses.context.uses fa riferimento ai provides di altri nodi, e la valutazione dei provides li esegue in ordine arbitrario. I template dei provides restano autocontenuti affinché la valutazione resti indipendente dall’ordine.
locals, provides, source (#5) della FeatureRecipe e template di rendering inline (#9, #10), su un host il cui provider non riporta alcun nome.context.rendered_nameSu un’associazione di Feature la chiave porta il nome riportato del componente host, e un host che colloca da solo un insieme di artefatti, o che esegue il rendering tramite un provider che non ricava alcun nome di questo tipo, non ne ha alcuno da portare. Il riferimento si arresta con la diagnostica di radice sconosciuta, che elenca .context.instance_id tra ciò che .context definisce lì; leggi invece l’identità, che è ciò da cui prendono il nome le risorse proprie dell’host su un tale host.
source (#5).context.injectLa risoluzione della sorgente viene eseguita prima dell’idratazione di inject che popola .context.inject. La pipe non è ancora popolata quando viene valutato l’URI della sorgente.
source (#5).context.usesLa risoluzione della sorgente deve completarsi prima che qualsiasi elemento a valle carichi il chart, il modulo o il corpo di artefatto dell’entità dichiarante. Consentire riferimenti tra nodi legherebbe la risoluzione della sorgente all’ordine di iterazione della topologia, cosa che essa evita deliberatamente.
Parametri (ovunque tranne nei template di percorso)Qualsiasi superficie di template di valore dopo l’interpolazioneL’interpolazione consuma ogni riferimento {{ .parameters.X }} nello YAML scritto dall’autore e scrive al suo posto il valore risolto, quindi una superficie di template di valore riceve il letterale risolto anziché il pilastro dei parametri. I template di percorso scritti dall’operatore sono l’unica eccezione e leggono .parameters.X direttamente.

4. Il percorso di risoluzione di self-inject

La risoluzione di self-inject è la prima metà dell’idratazione di inject, e viene eseguita dopo che i provides di ogni nodo sono stati valutati. Quando un componente dichiara un blocco inject: a livello di componente, il compilatore lo valuta lì:

  1. Stringhe value: letterali: se il valore contiene espressioni di template Go, il compilatore le valuta con il contesto della riga #4 della matrice (.values, .infra, .context.instance_id, .metadata.*, ecc.), scritte con l’escape come mostra la riga #4. Le stringhe semplici passano invariate.
  2. Riferimenti from:: il compilatore cerca la chiave nel dizionario provides proprio del nodo, già risolto a quel punto. Se la chiave non esiste, il compilatore arresta la build con un errore di chiave di inject non valida.
  3. Controllo delle collisioni: prima dell’unione nella pipe .context.inject, il compilatore verifica che nessuna chiave collida con le chiavi di uses-inject che la seconda metà dell’idratazione di inject risolve. Le collisioni arrestano la build con un errore di chiave di consegna duplicata.

Le stringhe risultanti vengono unite in .context.inject.env, .context.inject.file, .context.inject.arg (e in eventuali meccanismi personalizzati), accanto a quelle risoluzioni di uses-inject. Nel momento in cui viene eseguita la mappatura di inject (injectMapping), la pipe contiene tutti i valori di inject scritti dallo sviluppatore provenienti da entrambe le origini.