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

Contesto di template dei parametri

Il pilastro parameters: porta i valori dei parametri forniti dalla Release e validati rispetto al contratto. Due modelli mentali paralleli ne regolano l’accessibilità:

  • Le superfici dei template di valore (le stringhe values: di componenti / feature / sub-aggregate all’interno dell’Aggregate, più valuesMapping della Recipe, injectMapping e provides della FeatureRecipe, i corpi dei Workload) consumano i valori dei parametri come letterali già interpolati. Il passaggio di interpolazione all’interno della risoluzione valuta l’intero testo dell’Aggregate come template e sostituisce ogni riferimento {{ .parameters.<slot> }} con il valore risolto; le superfici dei template di valore a valle non vedono mai .parameters direttamente nel proprio contesto di template.
  • Le superfici dei template di percorso (i template directory: e subDirectory: scritti dall’operatore sui confini della Release) leggono .parameters.<slot> direttamente alla valutazione dei template di percorso durante il rendering. La mappa dei parametri unita resta leggibile fino alla fine del rendering, affinché un template di percorso possa leggere .parameters rispetto alla allowlist chiusa.

La concessione asimmetrica — i template di percorso leggono .parameters direttamente; i template di valore no — mantiene ogni livello padrone di ciò di cui ha bisogno: i values: lato sviluppatore portano avanti verso i template di valore dati già risolti e specifici dell’ambiente; i template di percorso lato operatore fanno riferimento a parametri di regione / ambiente / account-id senza un giro attraverso lo schema values dell’Aggregate.

Questa pagina documenta il passaggio di interpolazione, le forme dei valori per slot, i modelli di accesso all’interno delle stringhe YAML dell’Aggregate, l’eccezione dei template di percorso, e per quanto tempo la mappa unita resta leggibile. Per la forma più ampia del contesto di template di Recipe / FeatureRecipe (.values, .infra, .uses, ecc.), vedi template-context-contract.md. Per la disponibilità per singolo punto di template lungo la pipeline di compilazione, vedi expansion-matrix.md. Per la forma della dichiarazione dei contratti dei parametri tipizzati sull’Aggregate, vedi entities/aggregate.md §«Typed parameter contracts (Contratti di parametri tipizzati)». Per la allowlist delle variabili dei template di percorso che include .parameters.<slot> alla valutazione di directory: / subDirectory: del confine, vedi path-template-variables.md.

Ciclo di vita dei parametri

Il compilatore risolve i parametri in quattro fasi ordinate:

  1. Lettura del contratto — il blocco spec.parameters: dell’Aggregate viene verificato secondo i propri termini prima che venga esaminato qualsiasi valore della Release, quindi uno slot che non potrebbe vincolare nulla arresta la build anche quando nessuna Release lo fornisce. Un minLength o un maxLength negativo sulla dichiarazione propria di un parametro viene rifiutato quando l’Aggregate viene caricato, indicando il parametro e la chiave. Ogni pattern — sullo slot stesso e all’interno di qualsiasi contratto annidato sotto items, properties o valuesType — viene compilato come espressione regolare, e uno che non si compila viene rifiutato indicando il parametro, il pattern e il motivo. Un limite di lunghezza all’interno di un contratto annidato non è soggetto a quel limite inferiore; vedi entities/aggregate.md.
  2. Riempimento dei default — gli slot con default: definito e nessun valore fornito dalla Release ricevono il proprio default. La mappa .parameters è nell’ambito di visibilità a questo punto.
  3. Validazione del contratto dei parametri — ogni valore nella mappa unita, che lo abbia fornito la Release o che lo abbia riempito un default:, viene validato rispetto ai vincoli type / enum / min / max / pattern / di struttura annidata dichiarati in spec.parameters.<slot> dell’Aggregate; un pattern viene confrontato con l’espressione compilata quando il contratto è stato letto. La mappa .parameters esiste nel contesto in memoria del validatore come payload strutturato in fase di verifica.
  4. Interpolazione — il compilatore valuta l’intero testo dell’Aggregate come template, prima di leggerlo come YAML, e sostituisce ogni riferimento {{ .parameters.<slot> }} con il valore risolto; qualsiasi altro {{ nel testo viene letto anch’esso come sintassi di template, quindi un valore che porta doppie graffe proprie scrive ogni {{ come {{"{{"}} (vedi Testo che contiene le proprie doppie graffe). L’interpolazione è il percorso di sostituzione per le superfici dei template di valore — dopo questo passaggio, i contesti dei template di valore non portano più .parameters; consumano i valori risolti scritti nelle stringhe values: circostanti. La mappa unita resta leggibile dopo l’interpolazione, per tutto il rendering, specificamente per supportare la valutazione dei template di percorso. La sua durata di leggibilità è limitata da quella della build: il compilatore consegna la vista risolta alla compilazione che la consuma anziché restituirla a un chiamante, quindi nulla al di fuori di quella build può raggiungere la mappa. La superficie dei template di percorso (directory: / subDirectory: della Release) legge .parameters.<slot> durante il rendering rispetto alla allowlist chiusa documentata in path-template-variables.md.

I template all’interno delle stringhe YAML dell’Aggregate (values: dei componenti, values: delle feature, espressioni di passaggio in parameters: dei sub-aggregate) leggono la mappa .parameters tramite la sintassi standard dei template Go durante il passaggio di interpolazione. I template all’interno dei file di Recipe e FeatureRecipe NON ricevono .parameters nel proprio contesto di template (vedi «Boundary with downstream template contexts (Confine con i contesti di template a valle)» più sotto per il contratto per superficie).

Testo che contiene le proprie doppie graffe

Poiché l’intero testo è un template, anche le doppie graffe che appartengono a un valore anziché a un template vengono lette come azioni di template. La definizione di una piattaforma di flussi portata nei values: di un componente è il caso comune: n8n racchiude in doppie graffe ogni espressione nei parametri di un nodo, come in ={{ $json.body.message }}, un prompt di Flowise nomina una variabile come {{question}} e un chatflow di Flowise scrive {{chatOpenAI_0.data.instance}} per ogni connessione tra due nodi, e un’esportazione di Langflow porta il codice sorgente dei propri componenti, dove le graffe possono comparire anch’esse. Scritte in un Aggregate così come sono, arrestano la build sull’Aggregate con E0158, descritto sotto «A {{ .parameters.* }} reference cannot be interpolated (Un riferimento ai parametri non può essere interpolato)» in Arresti fatali; il suo motivo indica la riga e il primo token che il motore di template non è riuscito a leggere — undefined variable "$json" per un’espressione n8n. Anche un commento YAML è testo di template, quindi un {{ scritto in un commento si arresta allo stesso modo.

Scrivi ogni {{ in un valore di questo tipo come {{"{{"}}. Si tratta di un’azione di template il cui risultato è la stringa {{, quindi l’interpolazione rimette al loro posto le due graffe. Un }} di chiusura non richiede nulla, perché al di fuori di un’azione è testo semplice. L’interpolazione viene eseguita una sola volta, sul testo dell’Aggregate, e un template di Recipe scrive ciò che legge da .values come dati, quindi le graffe ripristinate raggiungono l’output renderizzato così come sono state esportate.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

La piattaforma riceve "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Mantieni una definizione di questo tipo in uno scalare a blocco (|), come sopra, dove le virgolette dell’escape sono caratteri ordinari. Il testo dell’Aggregate viene anche letto come YAML prima di essere interpolato, e all’interno di una stringa YAML tra virgolette doppie il " dell’escape chiude la stringa, quindi il file non viene più analizzato e la build si arresta con l’errore YAML.

Il modello di accesso .parameters.<slot>

Ogni slot di parametro dichiarato è accessibile come campo sulla mappa .parameters. L’accesso corretto rispetto al tipo corrisponde al type dichiarato:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

Il passaggio di interpolazione produce una valutazione di template Go rispetto alla mappa .parameters; il risultato sostituisce sul posto l’espressione di template nel documento. Lo schema values: di Component / Feature valida poi il valore risultante nella fase di validazione dello schema post-interpolazione della risoluzione.

L’uso delle virgolette decide il tipo sollevato

Metti tra virgolette un riferimento destinato a una foglia di tipo stringa; lascialo senza virgolette per ogni altro tipo dichiarato. La regola è quella di YAML stesso, non una che Aggrega aggiunge sopra: l’interpolazione sostituisce il valore fornito nei byte del documento e non fa nient’altro, quindi il parsing che segue legge il risultato esattamente come legge qualsiasi altro scalare. Un {{ .parameters.cache_ttl_seconds }} senza virgolette porta il tipo proprio del valore fornito, ed è ciò che permette a un parametro intero di raggiungere una foglia intera e a un parametro booleano di raggiungere una foglia booleana. Un "{{ .parameters.cache_ttl_seconds }}" tra virgolette porta una stringa, e una foglia dichiarata integer o boolean lo rifiuta: il valore scritto non supera lo schema values: del suo Component o della sua Feature sul tipo, e la diagnostica indica la mancata corrispondenza di tipo anziché qualsiasi vincolo sullo spazio dei valori che la stringa avrebbe anch’essa mancato.

Un riferimento che condivide il proprio scalare con altro testo è una stringa in qualunque modo sia scritto, perché il documento sostituito ha un solo scalare da leggere — image: app:{{ .parameters.tag }} produce app:1.4.0. È questa la forma a cui ricorrere quando un parametro non di tipo stringa deve finire in una foglia di tipo stringa.

Accesso agli slot di tipo oggetto e di tipo array

Gli slot di parametro di tipo oggetto espongono le proprie proprietà dichiarate come campi annidati sulla mappa .parameters.<slot>. Gli slot di tipo array espongono la semantica delle slice dei template Go (range, index, len).

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Gli slot di parametro di tipo array supportano l’iterazione tramite range:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Ogni elemento fornito dalla Release viene verificato rispetto al contratto items prima dell’interpolazione, quindi un valore che non è un nome host — *, ad esempio — arresta la build indicando il parametro, l’elemento e il formato. I nomi che format accetta, e ciò che ciascuno verifica, sono elencati in vocabulary/compact-form-authoring.md.

La libreria di template Sprig è disponibile durante l’interpolazione e fornisce helper come join per conversioni compatte da array a stringa:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Semantica del riempimento dei default

Uno slot di parametro con una dichiarazione default: riceve il proprio valore di default quando la Release omette lo slot. Il default si applica prima che venga eseguito il passaggio di validazione del contratto, quindi la validazione vede il valore risolto (fornito dalla Release o di default):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

Uno slot contrassegnato required: true senza default: provoca un errore in fase di build quando la Release lo omette (E0165). L’errore indica lo slot e la sua posizione nel contratto affinché l’autore lo corregga. Uno slot senza né required: true né un default: è facoltativo: se omesso, ogni riferimento a esso si interpola come vuoto, e lo schema values: del Component giudica poi il risultato.

Parametri di tipo oggetto annidato

Quando un parametro dichiara type: object con properties: i cui figli portano a loro volta valori default:, tre casi di scrittura producono risultati distinti. Comprendere la distinzione è importante quando la dichiarazione del parametro è un oggetto strutturato — una configurazione di database, un insieme di feature flag, una policy di timeout e retry — anziché un singolo scalare.

Caso 1 — la Release omette lo slot padre. Si applicano i default dei figli del contratto. L’autore dell’Aggregate che ha dichiarato i default annidati ottiene il comportamento che intendeva: quando ops non fornisce lo slot, la configurazione usa i default documentati.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Caso 2 — la Release scrive il padre come una mappa vuota esplicita. Il vuoto esplicito viene rispettato come un opt-out deliberato. I default dei figli NON vengono applicati; lo slot resta vuoto. Usa questa forma quando ops vuole sopprimere i default annidati del contratto senza fornire override — ad esempio, quando un consumatore a valle si aspetta lo slot presente ma vuoto.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

La distinzione dal Caso 1 è deliberata: ops può esprimere sia «usa i default» (omettendo lo slot) sia «sopprimi i default» (scrivendo lo slot come {}). Questo rispecchia il modo in cui Aggrega tratta il null esplicito nelle annotazioni — un’annotazione scritta come aggrega.ai/<key>: null è un opt-out deliberato distinto dall’omettere del tutto l’annotazione.

Caso 3 — la Release scrive parzialmente il padre. I figli che la Release ha fornito assumono i valori scritti; i figli che la Release non ha fornito vengono riempiti dai default.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Questo è il caso comune per gli autori di Release che vogliono sovrascrivere campi selezionati lasciando il resto ai default del contratto.

Quando usare ciascuna forma

  • Ometti lo slot quando vuoi che si applichino i default del contratto.
  • Scrivi {} quando vuoi deliberatamente lo slot presente ma vuoto — quando i default del contratto sono sbagliati per il tuo ambiente e non hai override.
  • Scrivi parzialmente quando vuoi alcuni override e vuoi che il resto usi i default del contratto.

Un autore di Release che scrive database: {} aspettandosi «dammi i default» resterà sorpreso — il valore risolto è vuoto, non i default riempiti. Per ottenere i default, ometti del tutto lo slot.

La gestione a tre casi è per fratello a ogni livello di annidamento. Un padre scritto come { connection: {}, other_field: "x" } produce un albero risolto in cui connection è vuoto (Caso 2 a profondità 1) e other_field è il valore fornito dalla Release (Caso 3 a profondità 0) — i casi vengono gestiti in modo indipendente per ciascun fratello, non come un’unica decisione per l’intero sottoalbero.

Confine con i contesti di template a valle

La concessione asimmetrica — i template di percorso leggono .parameters direttamente; i template di valore no — è la distinzione portante a questo confine. La semantica del confine per superficie:

  • Un template values: di componente dell’Aggregate che scrive {{ .parameters.X }} si risolve correttamente all’interpolazione. Il letterale risolto viene scritto sul posto nella stringa YAML.
  • Un template valuesMapping: della Recipe che scrive {{ .parameters.X }} è una superficie di template di valore; il contesto di template non porta .parameters. Gli autori che hanno bisogno di variazione per ambiente in valuesMapping: la esprimono attraverso il percorso di consumo del .values.<key> risolto — l’Aggregate espone un parametro, vi fa riferimento dai values: di un Component, la Release lo soddisfa, e il valore post-interpolazione fluisce fino alla Recipe.
  • Un template injectMapping:, provides: o pipeline.with: della FeatureRecipe è una superficie di template di valore; come valuesMapping: della Recipe. .parameters non è nel contesto di template.
  • Un template del corpo del Workload (contenuto workload: all’interno di una Recipe) è una superficie di template di valore; idem.
  • Un template di percorso (directory: / subDirectory: del confine della Release) è l’eccezione. Il contesto dei template di percorso include .parameters.<slot> rispetto alla allowlist chiusa; i riferimenti si risolvono quando il rendering colloca l’output di ciascun confine. Vedi path-template-variables.md per la matrice completa delle variabili dei template di percorso.

Il confine di proprietà tra i quattro domini è preservato da quale superficie riceve i parametri, non dal fatto che la mappa dei parametri esista in memoria in una determinata fase della pipeline. I template di percorso sono scritti e posseduti dall’operatore; concedere loro l’accesso diretto ai parametri mantiene le preoccupazioni dell’operatore (la disposizione degli artefatti per ambiente) all’interno della superficie dell’operatore. I template di valore sono scritti nel catalogo; negare loro l’accesso diretto ai parametri mantiene la scrittura lato catalogo debolmente accoppiata al contratto dell’Aggregate come unica fonte di verità.

La mappa dei parametri unita resta leggibile finché ogni fase di rendering non è stata completata, e non oltre: è raggiungibile solo dalla compilazione per cui è stata risolta, quindi la sua durata è limitata da quella della build.

Collegamento tra pilastri

I parametri si interpolano nelle stringhe di valori circostanti durante la risoluzione. I valori interpolati possono finire in qualsiasi pilastro che l’Aggregate scrive al proprio livello: stringhe values: dei componenti, stringhe values: delle feature, dichiarazioni di passaggio in parameters: dei sub-aggregate (dove il valore del parametro dell’Aggregate padre si risolve e poi si propaga nello slot di parametro dell’Aggregate figlio), e stringhe name: / labels: dei metadati.

Il collegamento è unidirezionale: un valore di parametro fluisce dal .parameters.<slot> fornito dalla Release (o di default) nella stringa YAML nel punto del riferimento. I parametri non fluiscono nell’altra direzione — un parametro non può leggere un campo values:, un campo provides: o il contenuto di qualsiasi altro pilastro. La direzionalità fa parte della garanzia del contratto dei parametri di valere solo in fase di compilazione.

Riferimenti incrociati

  • Per la forma della dichiarazione dei contratti dei parametri tipizzati sull’Aggregate: entities/aggregate.md §«Typed parameter contracts (Contratti di parametri tipizzati)».
  • Per il contesto di template più ampio che le Recipes consumano nel rendering di base (.values, .infra, .uses, .context.*, ecc.): template-context-contract.md.
  • Per la disponibilità per singolo punto di template lungo la pipeline di compilazione (quali campi sono presenti in quale punto di valutazione): expansion-matrix.md.
  • Per la checklist del sollevamento dei parametri (i quattro punti di intervento sequenziali della scrittura — dichiarazione nell’Aggregate, riferimento nei values, adempimento nella Release, consumo nella Recipe): vocabulary/data-pillars.md §«The parameter-hoisting checklist (La checklist del sollevamento dei parametri)».
  • Per l’insieme più ampio dei pilastri di dati (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.