Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Template-Kontext der Parameter

Die Säule parameters: trägt die vom Release gelieferten, gegen den Vertrag validierten Parameterwerte. Zwei parallele Denkmodelle bestimmen ihre Zugänglichkeit:

  • Value-Template-Oberflächen (Zeichenketten in values: von Komponenten / Features / Sub-Aggregates innerhalb des Aggregate, dazu valuesMapping des Recipe, injectMapping und provides des FeatureRecipe, Workload-Bodies) konsumieren die Parameterwerte als bereits interpolierte Literale. Der Interpolationsdurchlauf innerhalb der Auflösung wertet den gesamten Text des Aggregate als Template aus und ersetzt jede Referenz {{ .parameters.<slot> }} durch den aufgelösten Wert; nachgelagerte Value-Template-Oberflächen sehen .parameters nie direkt in ihrem Template-Kontext.
  • Pfad-Template-Oberflächen (vom Operator verfasste Templates directory: und subDirectory: auf Release-Boundaries) lesen .parameters.<slot> direkt bei der Auswertung der Pfad-Templates während des Renderings. Die zusammengeführte Parameter-Map bleibt bis zum Ende des Renderings lesbar, damit ein Pfad-Template .parameters gegen die geschlossene Allowlist lesen kann.

Die asymmetrische Freigabe — Pfad-Templates lesen .parameters direkt; Value-Templates nicht — sorgt dafür, dass jede Schicht besitzt, was sie braucht: Entwicklerseitige values: tragen bereits aufgelöste, umgebungsspezifische Daten an die Value-Templates weiter; operatorseitige Pfad-Templates referenzieren Parameter für Region / Umgebung / Konto-ID, ohne den Umweg über das Schema values des Aggregate.

Diese Seite dokumentiert den Interpolationsdurchlauf, die Wertformen pro Slot, die Zugriffsmuster innerhalb von YAML-Zeichenketten des Aggregate, die Ausnahme für Pfad-Templates und wie lange die zusammengeführte Map lesbar bleibt. Für die umfassendere Form des Template-Kontexts von Recipe / FeatureRecipe (.values, .infra, .uses usw.) siehe template-context-contract.md. Für die Verfügbarkeit pro Template-Stelle entlang der Kompilierungspipeline siehe expansion-matrix.md. Für die Form der Deklaration typisierter Parameterverträge am Aggregate siehe entities/aggregate.md §„Typed parameter contracts (Typisierte Parameterverträge)“. Für die Allowlist der Pfad-Template-Variablen, die .parameters.<slot> bei der Auswertung von directory: / subDirectory: einer Boundary einschließt, siehe path-template-variables.md.

Lebenszyklus der Parameter

Der Compiler löst Parameter in vier geordneten Phasen auf:

  1. Lesen des Vertrags — der Block spec.parameters: des Aggregate wird für sich geprüft, bevor irgendein Wert des Release betrachtet wird, sodass ein Slot, der nichts einschränken könnte, den Build anhält, selbst wenn kein Release ihn liefert. Ein negatives minLength oder maxLength an der eigenen Deklaration eines Parameters wird beim Laden des Aggregate abgelehnt, unter Nennung des Parameters und des Schlüssels. Jedes pattern — am Slot selbst und innerhalb jedes verschachtelten Vertrags unter items, properties oder valuesType — wird als regulärer Ausdruck kompiliert, und eines, das sich nicht kompilieren lässt, wird unter Nennung des Parameters, des Patterns und des Grundes abgelehnt. Eine Längengrenze innerhalb eines verschachtelten Vertrags unterliegt dieser Untergrenze nicht; siehe entities/aggregate.md.
  2. Standardbefüllung — Slots mit definiertem default: und ohne vom Release gelieferten Wert erhalten ihren Standardwert. Die Map .parameters ist an dieser Stelle im Gültigkeitsbereich.
  3. Validierung des Parametervertrags — jeder Wert in der zusammengeführten Map, ob das Release ihn geliefert oder ein default: ihn befüllt hat, wird gegen die in spec.parameters.<slot> des Aggregate deklarierten Einschränkungen type / enum / min / max / pattern / verschachtelte Struktur validiert; ein pattern wird gegen den Ausdruck abgeglichen, der beim Lesen des Vertrags kompiliert wurde. Die Map .parameters existiert im In-Memory-Kontext des Validators als die strukturierte Nutzlast, die geprüft wird.
  4. Interpolation — der Compiler wertet den gesamten Text des Aggregate als Template aus, bevor er ihn als YAML liest, und ersetzt jede Referenz {{ .parameters.<slot> }} durch den aufgelösten Wert; jedes andere {{ im Text wird ebenfalls als Template-Syntax gelesen, daher schreibt ein Wert, der eigene doppelte geschweifte Klammern trägt, jedes {{ als {{"{{"}} (siehe Text mit eigenen doppelten geschweiften Klammern). Die Interpolation ist der Ersetzungspfad für Value-Template-Oberflächen — nach diesem Durchlauf tragen Value-Template-Kontexte .parameters nicht mehr; sie konsumieren die aufgelösten Werte, die in die umgebenden Zeichenketten in values: geschrieben wurden. Die zusammengeführte Map bleibt nach der Interpolation während des gesamten Renderings lesbar, eigens um die Auswertung von Pfad-Templates zu unterstützen. Ihre lesbare Lebensdauer ist durch die des Builds begrenzt: Der Compiler übergibt die aufgelöste Sicht an die Kompilierung, die sie konsumiert, statt sie an einen Aufrufer zurückzugeben, sodass nichts außerhalb dieses Builds die Map erreichen kann. Die Pfad-Template-Oberfläche (directory: / subDirectory: des Release) liest .parameters.<slot> während des Renderings gegen die geschlossene Allowlist, die in path-template-variables.md dokumentiert ist.

Templates innerhalb von YAML-Zeichenketten des Aggregate (values: von Komponenten, values: von Features, Durchreich-Ausdrücke in parameters: von Sub-Aggregates) lesen die Map .parameters über die Standard-Go-Template-Syntax während des Interpolationsdurchlaufs. Templates innerhalb von Recipe- und FeatureRecipe-Dateien erhalten .parameters in ihrem Template-Kontext NICHT (siehe „Boundary with downstream template contexts (Grenze zu nachgelagerten Template-Kontexten)“ weiter unten für den Vertrag pro Oberfläche).

Text mit eigenen doppelten geschweiften Klammern

Da der gesamte Text ein Template ist, werden doppelte geschweifte Klammern, die zu einem Wert statt zu einem Template gehören, ebenfalls als Template-Aktionen gelesen. Die Definition einer Flow-Plattform, die in den values: einer Komponente getragen wird, ist der häufige Fall: n8n umschließt jeden Ausdruck in den Parametern eines Knotens mit doppelten geschweiften Klammern, wie in ={{ $json.body.message }}, ein Flowise-Prompt benennt eine Variable als {{question}} und ein Flowise-Chatflow schreibt {{chatOpenAI_0.data.instance}} für jede Verbindung zwischen zwei Knoten, und ein Langflow-Export trägt den Quellcode seiner Komponenten, in dem die Klammern ebenfalls vorkommen können. So wie sie sind in ein Aggregate geschrieben, halten sie den Build am Aggregate mit E0158 an, beschrieben unter „A {{ .parameters.* }} reference cannot be interpolated (Ein Parameterverweis kann nicht interpoliert werden)“ auf Fatale Abbrüche; sein Grund nennt die Zeile und das erste Token, das die Template-Engine nicht lesen konnte — undefined variable "$json" für einen n8n-Ausdruck. Ein YAML-Kommentar ist ebenfalls Template-Text, daher hält ein in einem Kommentar geschriebenes {{ auf dieselbe Weise an.

Schreiben Sie jedes {{ in einem solchen Wert als {{"{{"}}. Das ist eine Template-Aktion, deren Ergebnis die Zeichenkette {{ ist, sodass die Interpolation die beiden Klammern wieder einsetzt. Ein schließendes }} braucht nichts, weil es außerhalb einer Aktion einfacher Text ist. Die Interpolation läuft einmal, über den Text des Aggregate, und ein Recipe-Template schreibt, was es aus .values liest, als Daten aus, sodass die wiederhergestellten Klammern die gerenderte Ausgabe so erreichen, wie sie exportiert wurden.

# 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": {}
}

Die Plattform erhält "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Halten Sie eine solche Definition in einem Block-Skalar (|), wie oben, wo die Anführungszeichen der Maskierung gewöhnliche Zeichen sind. Der Text des Aggregate wird außerdem als YAML gelesen, bevor er interpoliert wird, und innerhalb einer YAML-Zeichenkette in doppelten Anführungszeichen schließt das " der Maskierung die Zeichenkette, sodass sich die Datei nicht mehr parsen lässt und der Build mit dem YAML-Fehler anhält.

Das Zugriffsmuster .parameters.<slot>

Jeder deklarierte Parameter-Slot ist als Feld der Map .parameters zugänglich. Typkorrekter Zugriff entspricht dem deklarierten type:

# 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

Der Interpolationsdurchlauf erzeugt eine Go-Template-Auswertung gegen die Map .parameters; das Ergebnis ersetzt den Template-Ausdruck an Ort und Stelle im Dokument. Das Schema values: der Component / des Feature validiert den resultierenden Wert anschließend in der Phase der Schemavalidierung nach der Interpolation innerhalb der Auflösung.

Die Anführungszeichen entscheiden über den hochgezogenen Typ

Setzen Sie eine Referenz, die auf ein Zeichenketten-Blatt zielt, in Anführungszeichen; lassen Sie sie für jeden anderen deklarierten Typ ohne. Die Regel ist die von YAML selbst, keine, die Aggrega obendrauf hinzufügt: Die Interpolation setzt den gelieferten Wert in die Bytes des Dokuments ein und tut sonst nichts, sodass das folgende Parsen das Ergebnis genau so liest, wie es jeden anderen Skalar liest. Ein {{ .parameters.cache_ttl_seconds }} ohne Anführungszeichen trägt den eigenen Typ des gelieferten Werts, und genau das lässt einen Integer-Parameter ein Integer-Blatt und einen booleschen Parameter ein boolesches Blatt erreichen. Ein "{{ .parameters.cache_ttl_seconds }}" in Anführungszeichen trägt eine Zeichenkette, und ein als integer oder boolean deklariertes Blatt lehnt sie ab: Der verfasste Wert scheitert am Schema values: seiner Component oder seines Feature beim Typ, und die Diagnose nennt die Typabweichung statt einer Einschränkung des Wertebereichs, die die Zeichenkette ebenfalls verfehlt hätte.

Eine Referenz, die ihren Skalar mit anderem Text teilt, ist eine Zeichenkette, gleich wie sie geschrieben ist, weil das ersetzte Dokument einen einzigen Skalar zu lesen hat — image: app:{{ .parameters.tag }} ergibt app:1.4.0. Das ist die Form, zu der man greift, wenn ein Parameter, der keine Zeichenkette ist, in einem Zeichenketten-Blatt landen muss.

Zugriff auf Slots vom Typ Objekt und vom Typ Array

Parameter-Slots vom Typ Objekt stellen ihre deklarierten Eigenschaften als verschachtelte Felder der Map .parameters.<slot> bereit. Slots vom Typ Array stellen die Slice-Semantik von Go-Templates bereit (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 }}"

Parameter-Slots vom Typ Array unterstützen die Iteration über 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 }}"

Jedes Element, das das Release liefert, wird vor der Interpolation gegen den Vertrag items geprüft, sodass ein Wert, der kein Hostname ist — etwa * —, den Build unter Nennung des Parameters, des Elements und des Formats anhält. Die Namen, die format akzeptiert, und was jeder prüft, sind in vocabulary/compact-form-authoring.md aufgeführt.

Die Sprig-Template-Bibliothek ist während der Interpolation verfügbar und stellt Helfer wie join für kompakte Umwandlungen von Arrays in Zeichenketten bereit:

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

Semantik der Standardbefüllung

Ein Parameter-Slot mit einer Deklaration default: erhält seinen Standardwert, wenn das Release den Slot weglässt. Der Standardwert wird angewendet, bevor der Durchlauf der Vertragsvalidierung läuft, sodass die Validierung den aufgelösten Wert sieht (vom Release geliefert oder Standardwert):

# 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)

Ein mit required: true markierter Slot ohne default: löst einen Fehler zur Build-Zeit aus, wenn das Release ihn weglässt (E0165). Der Fehler nennt den Slot und seine Position im Vertrag, damit der Autor ihn beheben kann. Ein Slot weder mit required: true noch mit einem default: ist optional: Weggelassen, wird jede Referenz darauf als leer interpoliert, und das Schema values: der Component beurteilt dann das Ergebnis.

Parameter mit verschachtelten Objekten

Wenn ein Parameter type: object mit properties: deklariert, deren Kinder selbst Werte in default: tragen, führen drei Fälle beim Verfassen zu unterschiedlichen Ergebnissen. Die Unterscheidung zu verstehen ist wichtig, wenn die Parameterdeklaration ein strukturiertes Objekt ist — eine Datenbankkonfiguration, ein Bündel von Feature-Flags, eine Timeout-und-Retry-Richtlinie — statt eines einzelnen Skalars.

Fall 1 — das Release lässt den übergeordneten Slot weg. Die Standardwerte der Kinder des Vertrags werden befüllt. Der Autor des Aggregate, der die verschachtelten Standardwerte deklariert hat, erhält das beabsichtigte Verhalten: Wenn Ops den Slot nicht liefert, verwendet die Konfiguration die dokumentierten Standardwerte.

# 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

Fall 2 — das Release verfasst den übergeordneten Slot als explizit leere Map. Das explizit Leere wird als bewusstes Opt-out respektiert. Die Standardwerte der Kinder werden NICHT befüllt; der Slot bleibt leer. Verwenden Sie diese Form, wenn Ops die verschachtelten Standardwerte des Vertrags unterdrücken möchte, ohne Überschreibungen zu liefern — zum Beispiel, wenn ein nachgelagerter Konsument den Slot vorhanden, aber leer erwartet.

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

Die Abgrenzung zu Fall 1 ist beabsichtigt: Ops kann sowohl „die Standardwerte verwenden“ (durch Weglassen des Slots) als auch „die Standardwerte unterdrücken“ (durch Verfassen des Slots als {}) ausdrücken. Das spiegelt wider, wie Aggrega ein explizites null in Annotationen behandelt — eine als aggrega.ai/<key>: null verfasste Annotation ist ein bewusstes Opt-out, das sich vom vollständigen Weglassen der Annotation unterscheidet.

Fall 3 — das Release verfasst den übergeordneten Slot teilweise. Kinder, die das Release geliefert hat, nehmen ihre verfassten Werte an; Kinder, die das Release nicht geliefert hat, werden aus den Standardwerten befüllt.

# 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

Das ist der häufige Fall für Release-Autoren, die ausgewählte Felder überschreiben und den Rest bei den Standardwerten des Vertrags belassen möchten.

Wann welche Form zu verwenden ist

  • Lassen Sie den Slot weg, wenn die Standardwerte des Vertrags gelten sollen.
  • Verfassen Sie {}, wenn Sie den Slot bewusst vorhanden, aber leer haben möchten — wenn die Standardwerte des Vertrags für Ihre Umgebung falsch sind und Sie keine Überschreibungen haben.
  • Verfassen Sie teilweise, wenn Sie einige Überschreibungen möchten und der Rest die Standardwerte des Vertrags verwenden soll.

Ein Release-Autor, der database: {} schreibt und „gib mir die Standardwerte“ erwartet, wird überrascht sein — der aufgelöste Wert ist leer, nicht die befüllten Standardwerte. Um die Standardwerte zu erhalten, lassen Sie den Slot ganz weg.

Die Unterscheidung der drei Fälle erfolgt pro Geschwister auf jeder Verschachtelungstiefe. Ein als { connection: {}, other_field: "x" } verfasster übergeordneter Slot erzeugt einen aufgelösten Baum, in dem connection leer ist (Fall 2 auf Tiefe 1) und other_field der vom Release gelieferte Wert ist (Fall 3 auf Tiefe 0) — die Fälle werden für jedes Geschwister unabhängig entschieden, nicht als eine einzige Entscheidung für den ganzen Teilbaum.

Grenze zu nachgelagerten Template-Kontexten

Die asymmetrische Freigabe — Pfad-Templates lesen .parameters direkt; Value-Templates nicht — ist die tragende Unterscheidung an dieser Grenze. Die Semantik der Grenze pro Oberfläche:

  • Ein Template in values: einer Komponente des Aggregate, das {{ .parameters.X }} schreibt, wird bei der Interpolation korrekt aufgelöst. Das aufgelöste Literal wird an Ort und Stelle in die YAML-Zeichenkette geschrieben.
  • Ein Template in valuesMapping: eines Recipe, das {{ .parameters.X }} schreibt, ist eine Value-Template-Oberfläche; der Template-Kontext trägt .parameters nicht. Autoren, die umgebungsspezifische Variation in valuesMapping: benötigen, drücken sie über den Konsumpfad des aufgelösten .values.<key> aus — das Aggregate stellt einen Parameter bereit, referenziert ihn aus den values: einer Component, das Release erfüllt ihn, und der Wert nach der Interpolation fließt bis zum Recipe durch.
  • Ein Template in injectMapping:, provides: oder pipeline.with: eines FeatureRecipe ist eine Value-Template-Oberfläche; wie valuesMapping: eines Recipe. .parameters ist nicht im Template-Kontext.
  • Ein Workload-Body-Template (Inhalt in workload: innerhalb eines Recipe) ist eine Value-Template-Oberfläche; ebenso.
  • Ein Pfad-Template (directory: / subDirectory: einer Release-Boundary) ist die Ausnahme. Der Pfad-Template-Kontext enthält .parameters.<slot> gegen die geschlossene Allowlist; Referenzen werden aufgelöst, wenn das Rendering die Ausgabe jeder Boundary platziert. Siehe path-template-variables.md für die vollständige Matrix der Pfad-Template-Variablen.

Die Eigentumsgrenze der vier Domänen wird dadurch gewahrt, welche Oberfläche Parameter erhält, nicht dadurch, ob die Parameter-Map in einer bestimmten Pipeline-Stufe im Speicher existiert. Pfad-Templates werden vom Operator verfasst und gehören dem Operator; ihnen direkten Parameterzugriff zu gewähren, hält Operator-Belange (das umgebungsspezifische Artefakt-Layout) innerhalb der Operator-Oberfläche. Value-Templates werden im Katalog verfasst; ihnen direkten Parameterzugriff zu verweigern, hält das katalogseitige Verfassen lose an den Vertrag des Aggregate als einzige Quelle der Wahrheit gekoppelt.

Die zusammengeführte Parameter-Map bleibt lesbar, bis jede Render-Phase abgeschlossen ist, und nicht länger: Sie ist nur aus der Kompilierung erreichbar, für die sie aufgelöst wurde, sodass ihre Lebensdauer durch die des Builds begrenzt ist.

Säulenübergreifende Überbrückung

Parameter werden während der Auflösung in die umgebenden Wert-Zeichenketten interpoliert. Die interpolierten Werte können in jeder Säule landen, die das Aggregate auf seiner Ebene verfasst: Zeichenketten in values: von Komponenten, Zeichenketten in values: von Features, Durchreich-Deklarationen in parameters: von Sub-Aggregates (wobei der Parameterwert des übergeordneten Aggregate aufgelöst und dann in den Parameter-Slot des untergeordneten Aggregate weitergegeben wird) und Zeichenketten in name: / labels: der Metadaten.

Die Überbrückung ist einseitig gerichtet: Ein Parameterwert fließt aus dem vom Release gelieferten (oder standardmäßig gesetzten) .parameters.<slot> in die YAML-Zeichenkette an der Referenzstelle. Parameter fließen nicht in die andere Richtung — ein Parameter kann kein Feld values:, kein Feld provides: und keinen Inhalt einer anderen Säule lesen. Die Gerichtetheit ist Teil der Garantie des Parametervertrags, nur zur Kompilierzeit zu gelten.

Querverweise

  • Für die Form der Deklaration typisierter Parameterverträge am Aggregate: entities/aggregate.md §„Typed parameter contracts (Typisierte Parameterverträge)“.
  • Für den umfassenderen Template-Kontext, den Recipes beim Basis-Rendering konsumieren (.values, .infra, .uses, .context.* usw.): template-context-contract.md.
  • Für die Verfügbarkeit pro Template-Stelle entlang der Kompilierungspipeline (welche Felder an welcher Auswertungsstelle vorhanden sind): expansion-matrix.md.
  • Für die Checkliste zum Hochziehen von Parametern (die vier aufeinanderfolgenden Berührungspunkte beim Verfassen — Deklaration im Aggregate, Referenz in values, Erfüllung im Release, Konsum im Recipe): vocabulary/data-pillars.md §„The parameter-hoisting checklist (Die Checkliste zum Hochziehen von Parametern)“.
  • Für die umfassendere Menge der Datensäulen (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.