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

Template-Expansionsmatrix

Template-Expansionsreferenz — Die vollständige Matrix

Die Aggrega-DSL unterstützt die Go-Expansion text/template (mit vorregistrierter Sprig-Bibliothek) an mehreren Stellen in den YAML-Entitäten. Jede Stelle hat eine bestimmte Menge verfügbarer Referenzen, bestimmt dadurch, wann die Daten im Verlauf der Kompilierung konkret werden. Diese Seite ist die Referenz dafür, was wo referenziert werden kann.

1. Der Zeitablaufbaum der Pipeline (wann Daten konkret werden)

Um zu verstehen, welche Referenzen verfügbar sind, muss man verstehen, wann jede einzelne Angabe aufgelöst wird. Die folgenden Stufen sind in der Reihenfolge aufgeführt, in der sie laufen, und jede ist nach dem benannt, was sie tut — unter diesem Namen bezieht sich der Rest dieser Seite auf sie:

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. Die Template-Expansionsmatrix

Jede Stelle in der DSL, an der Go-Template-Ausdrücke ausgewertet werden, und genau welche Referenzen verfügbar sind:

#LocationEntitätAusgewertet inVerfügbare Referenzen
1{{ .parameters.X }} in YAML-Zeichenketten des AggregateAggregateAuflösung (Interpolation)Nur .parameters. Alle anderen Daten sind noch nicht aufgelöst.
2{{ .parameters.X }} in YAML-Zeichenketten des ReleaseReleaseNicht ausgewertetKeine. Die Zeichenketten eines Release werden so gelesen, wie sie geschrieben sind: Ein {{ .parameters.X }} unter infra:, in einer Annotation oder als Wert von parameters: erreicht sein Ziel als genau dieser literale Text. Das Release liefert die Parameterwerte (die Inline-Map parameters: und die über $import: geladenen Werte, kombiniert zur zusammengeführten Parameter-Map); die Zeichenketten des Aggregate lesen sie (#1), und ebenso die Pfad-Templates (#3).
3Templates directory / subDirectoryRelease-BoundaryRendering (Pfadauswertung).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* und .component_id (nur subDirectory: — ein Template in directory: lehnt es ab).
4Zeichenketten value: im inject einer ComponentAggregate-KomponenteSelf-Inject-Auflösung.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (alle 3 Buckets), .metadata.* (release_name, release_version, environment, aggregate_name). VERBOTEN: .context.inject (zirkulär — die Pipe wird gerade aufgebaut), .context.uses (verwenden Sie stattdessen uses[].inject für die komponentenübergreifende Verdrahtung). Das Template steht im Text des Aggregate, den die Parameterinterpolation von #1 zuerst liest, schreiben Sie es daher maskiert — value: '{{"{{"}} .metadata.release_name }}' —, damit es diese Stufe erreicht; einfach geschrieben, wertet die Interpolation es aus und hält an, da der Text eines Aggregate keine Wurzel außer .parameters definiert.
5Zeichenketten im Feld source (Zeichenkette auf oberster Ebene ODER zeichenkettenwertige Unterfelder einer strukturierten Map source:)Recipe / FeatureRecipeQuellauflösungZwei Oberflächen, entschieden danach, was die Quelle benennt. Eine entfernte Koordinate — version, chart, ref und module_subdir eines strukturierten Blocks, der eine Registry, ein Chart-Repository oder ein Git-Repository benennt — wird ausgewertet, wenn aggrega pull das Artefakt auflöst, um es festzupinnen: nur .values, .infra, .locals und statische Zeichenketten, mit den eigenen Helfern von Aggrega (optional, capitalizedWords, index) und keiner der Funktionen von Sprig, und ohne Wurzel .context. Die dort ausgewerteten Einträge von .locals sind diejenigen, die diese Felder lesen, direkt oder über einen anderen Eintrag — alle Einträge, wo ein Feld .locals auf eine Weise liest, die keinen einzelnen Eintrag benennt —, sodass ein Eintrag, den kein Feld liest, dem Render überlassen bleibt. Eine Quelle, die einen Pfad im Workspace benennt, wird ausgewertet, während die Entität rendert: .context.instance_id, .values, .infra, .locals (der gesamte aufgelöste Block der deklarierenden Entität), statische Zeichenketten. Dort liest die Quelle eines FeatureRecipe zusätzlich .attachment_name — aufgelöst wird eine Anbindung —, und ihre .context.instance_id benennt die Host-Komponente, neben .context.rendered_name, dem gemeldeten Namen der Host-Komponente (siehe #9); ein FeatureRecipe mit Boundary-Geltungsbereich liest .boundary.* und keine der Säulen pro Komponente. VERBOTEN auf beiden: .context.inject, .context.uses, .provides (Invariante der Selbstabgeschlossenheit — die Oberfläche der Workspace-Quelle teilt ihren Kontext mit den eigenen locals der deklarierenden Entität, sodass beide dieselben Referenzen zulassen und ablehnen, und eine entfernte Koordinate liest eine Teilmenge dieses Kontexts; die Quellauflösung muss abgeschlossen sein, bevor die Topologie-Pipe hydratisiert wird und bevor irgendein Chart, Modul oder Artefakt-Body geladen wird).
6Templates in provides des RecipeRecipeProvides-Auswertung.context.instance_id, .context.rendered_name (der Name, den der Provider des Knotens der Ausgabe gibt, die er für den Knoten rendert — aus einer vom Autor gelieferten Quelle oder aus einer Workload, die er synthetisiert; ihn auf einem Knoten zu lesen, dessen Provider keinen solchen Namen meldet, führt zum Anhalten — siehe Benennung einer gerenderten Ressource), .values, .infra, .locals (der gesamte aufgelöste Block des Knotens — die locals lösen sich in der Präambel dieser Stufe auf, vor provides), statische Zeichenketten. VERBOTEN: jede andere Wurzel — .context.inject, .context.uses (knotenübergreifend), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (an Platzierung/Bereitstellung gekoppelt) und .attachment_name (während der Provides-Auswertung eines Basis-Recipe wird keine Anbindung aufgelöst). Die Prüfung ist eine positive Allowlist: Eine Referenz auf irgendeine Wurzel, die der Provides-Kontext nicht offenlegt, führt zum Anhalten (Invariante der Selbstabgeschlossenheit — ermöglicht parallele Auswertung ohne jede topologische Sortierung). Auch ein .locals.<key>, das einen Schlüssel benennt, den der locals-Block nicht deklariert, führt zum Anhalten, da die Säule eine offene geschlüsselte Map ist, die die Wurzelprüfung allein nicht überwachen kann.
7valuesMapping des Recipe (inline, $import: aus einer Datei oder $import: aus einer Bibliothek)RecipeBasis-RenderingVollständiger Template-Kontext: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Eine inline geschriebene Referenz .context.rendered_name führt auf einem Knoten, dessen Provider keinen solchen Namen meldet, zum Anhalten, wie in #6; eine innerhalb eines über $import: geladenen Body wird nicht geprüft und rendert auf einem solchen Knoten leer.
8injectMapping des FeatureRecipeFeatureRecipeInject-MappingVollständiger Template-Kontext: .values, .infra, .context.* (einschließlich .context.inject — der Pipe, die abgefangen wird — und .context.uses). .context.used_by ist hier leer: Die Ausgabe des Mappings landet auf der eigenen Zustellungs-Pipe des Hosts. .context.render_facts fehlt: Das Mapping läuft, bevor der Host rendert. .context.rendered_name ist der gemeldete Name der Host-Komponente, wie in #9; ein Mapping, das ihn liest, wird nicht geprüft und rendert ihn auf einem Host, dessen Provider keinen meldet, leer. Derselbe Kontext unabhängig vom executionScope des FeatureRecipe: Das Mapping eines FeatureRecipe mit Boundary-Geltungsbereich läuft einmal für jede Komponente, die die Anbindung erreicht, liest den .context.* dieser Komponente und liest .features.<attachment>.provides und .locals als die eine Boundary-Auswertung. VERBOTEN: .boundary, das der Kontext keiner Komponente trägt — eine Referenz hält den Build an.
9valuesMapping des FeatureRecipe (und seine workload: und artifacts:)FeatureRecipeBasis-RenderingVollständiger Template-Kontext + .attachment_name, .inject (die eigenen Einträge in inject: der Anbindung, wo die Anbindung einen Block inject: verfasst), .context.render_facts — was der Provider des Hosts über das Rendern des Hosts gemeldet hat — und .context.used_by — die Komponenten, die den Host verwenden, jede mit ihren eigenen Render-Fakten, wo das FeatureRecipe readsCallerRenderFacts: true setzt. Jede Verbindung auf .context.uses trägt die Render-Fakten ihres Ziels, unter .render_facts, wo das FeatureRecipe readsTargetRenderFacts: true setzt. .context.instance_id und .context.rendered_name sind die Identität der Host-Komponente und der Name, den der eigene Provider des Hosts für sie meldet — derselbe Wert, den das Recipe des Hosts liest, auch in den locals: und provides: des FeatureRecipe —, und eine inline geschriebene Referenz auf .context.rendered_name führt auf einem Host, dessen Provider keinen solchen Namen meldet, zum Anhalten. .source ist das ausgewertete eigene source: des FeatureRecipe, nie das der Host-Komponente, und enthält nichts, wo das FeatureRecipe keines deklariert.
10Pipeline-Blöcke with:Recipe / FeatureRecipeDie Plugin-PipelineVollständiger Template-Kontext + .steps (Ausgaben zwischen Schritten aus vorangehenden Pipeline-Schritten). .context.used_by ist hier leer, und keine Verbindung auf .context.uses trägt die Render-Fakten ihres Ziels: Ein Schritt kann die eigenen Dokumente des Hosts umschreiben. Der Schritt eines angebundenen FeatureRecipe liest .context.render_facts, die eigenen Render-Fakten des Hosts, wie es #9 tut.
11Body workload: des Recipe (jedes Feld mit Template darin, ob inline oder über $import: geladen)RecipeBasis-RenderingVollständiger Template-Kontext. Jedes Feld im Workload-Body — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — ist Teil derselben Template-Auswertung, die die gesamte Workload-Zeichenkette verarbeitet. Der Workload-Inhalt ist ein einzelnes Go-Template, das einmal gegen den vollständigen Template-Kontext ausgewertet wird; Templates auf Feldebene darin lösen sich in derselben Auswertung auf statt in einer separaten.

Hinweis zur Selbstabgeschlossenheit. Zeichenketten in source (#5) teilen die Invariante der Selbstabgeschlossenheit von provides (#6): Beide Oberflächen lehnen Referenzen auf .context.inject und .context.uses ab. Die Quellauflösung läuft vor der Inject-Hydratation, die .context.inject befüllt, und bevor irgendetwas Nachgelagertes die aufgelöste Quelle konsumiert — daher gelten die Regel und ihre Begründung für beide Oberflächen. Worin sich die beiden unterscheiden, ist die provides-Säule: Eine source im Workspace teilt ihren Kontext mit den locals der deklarierenden Entität, und eine entfernte Koordinate liest eine Teilmenge davon, sodass beide .provides ablehnen, während provides selbst die Oberfläche ist, die aufgelöst wird. Beide lesen .locals. Die Regel erreicht die source eines FeatureRecipe zu denselben Bedingungen wie die eines Recipe, jeweils geprüft gegen die eigene Oberfläche locals dieser Entität.

Hinweis zu Templates im Workload-Body (#11). Der Workload-Body ist eine einzige Zeichenkette mit Templates, die der Renderer als Ganzes auswertet und deren Ergebnis er dann als Workload-Dokument parst. Templates auf Feldebene darin (hier ein replicas: {{ .infra.replicas | default 1 }}, dort ein LOG_LEVEL: "{{ .values.log_level }}" innerhalb von containers.app.variables) sind keine separaten Stellen der Template-Auswertung — sie nehmen alle an der einen Auswertung des Basis-Renderings teil, die die Workload erzeugt. Autoren brauchen keine separate Verfügbarkeitsregel für Workload-interne Felder; die Regel für die Workload als Ganzes (#11) deckt jedes Template auf Feldebene darin ab.

Diskriminatorbewusster Fallback im Workload-Body. Das obige Beispiel replicas: {{ .infra.replicas | default 1 }} vermengt „Autor hat replicas nicht gesetzt“ mit „Autor hat replicas auf 0 gesetzt“ — default greift in beiden Fällen. Wenn ein Release legitimerweise infra.replicas: 0 verfasst, um Scale-to-Zero auszudrücken (ein gängiges Knative- / KEDA-Muster), überschreibt die Form | default 1 stillschweigend die Absicht. Die diskriminatorbewusste Form ist replicas: {{ optional .infra "replicas" 1 }} — optional prüft das Vorhandensein des Schlüssels und gibt den verfassten Wert zurück (einschließlich einer verfassten Null), wenn der Schlüssel gesetzt ist, und fällt nur dann auf 1 zurück, wenn der Schlüssel fehlt. Siehe sprig-functions.md für die vollständige Semantik und die Hinweise, wann es vorzuziehen ist.

3. Verbotene Referenzen & Begründung

LocationVerbotene ReferenzBegründung
value: in inject der Component (#4).context.injectDie inject-Pipe wird an diesem Punkt gerade aufgebaut — ein Self-Inject-Template in value: kann nicht aus der Pipe lesen, zu der es beiträgt.
value: in inject der Component (#4).context.usesKomponentenübergreifende Verdrahtung gehört in uses[].inject. Die Self-Inject-Templates in value: einer Komponente bleiben über den eigenen Daten der Komponente geschlossen.
provides des Recipe (#6).context.injectProvides-Templates werden in beliebiger Reihenfolge ausgewertet und schließen nur über den eigenen Daten des Knotens (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Die inject-Pipe wird erst bei der Inject-Hydratation befüllt, die läuft, nachdem die provides jedes Knotens ausgewertet sind.
provides des Recipe (#6).attachment_nameDer Provides-Durchlauf eines Basis-Recipe löst keine Anbindung auf, daher würde der Name leer gerendert. Die Wurzel wird abgelehnt, statt leer geliefert zu werden.
source (#5).providesKeine der beiden Quelloberflächen trägt eine provides-Säule: Die Oberfläche der Workspace-Quelle teilt ihren Kontext mit den eigenen locals der deklarierenden Entität, die keine hat, und eine entfernte Koordinate liest eine Teilmenge dieses Kontexts. Locals lösen sich vor provides auf, damit provides: .locals lesen kann; das Quell-Template liest dieselben locals, statt auf provides zurückzugreifen.
locals des Recipe (Präambel von #6).providesLocals lösen sich vor provides auf, sodass die eigenen provides des Knotens noch nicht existieren, wenn ein Local ausgewertet wird. Ein Local, das einen Wert braucht, den auch die provides veröffentlichen, berechnet ihn direkt aus .values / .infra — und der Eintrag in provides liest dann das Local.
locals des Recipe (Präambel von #6).context.rendered_nameDie locals eines Recipe teilen ihren Kontext mit seinem Template source (#5), und diese Oberfläche bietet den Namen nicht an: Ob der Knoten eine Quelle liefert, was das Template source entscheidet, ist eines der Dinge, von denen der Name abhängt. Die Referenz hält mit der Diagnose für eine unbekannte Wurzel an, die .context.instance_id als das aufführt, was .context dort definiert. Lesen Sie den Schlüssel stattdessen in einem Eintrag in provides oder in einem Template der Stufe des Basis-Renderings.
provides des Recipe (#6).context.uses.context.uses verweist auf die provides anderer Knoten, und die Provides-Auswertung führt diese in beliebiger Reihenfolge aus. Provides-Templates bleiben in sich geschlossen, damit die Auswertung reihenfolgeunabhängig bleibt.
locals, provides, source (#5) eines FeatureRecipe und Inline-Render-Templates (#9, #10), auf einem Host, dessen Provider keinen Namen meldet.context.rendered_nameBei einer Feature-Anbindung trägt der Schlüssel den gemeldeten Namen der Host-Komponente, und ein Host, der allein eine Artefaktmenge platziert oder über einen Provider rendert, der keinen solchen Namen ableitet, hat keinen zu tragen. Die Referenz hält mit der Diagnose für eine unbekannte Wurzel an, die .context.instance_id unter dem aufführt, was .context dort definiert; lesen Sie stattdessen die Identität, nach der auf einem solchen Host die eigenen Ressourcen des Hosts benannt sind.
source (#5).context.injectDie Quellauflösung läuft vor der Inject-Hydratation, die .context.inject befüllt. Die Pipe ist noch nicht befüllt, wenn die Quell-URI ausgewertet wird.
source (#5).context.usesDie Quellauflösung muss abgeschlossen sein, bevor irgendetwas Nachgelagertes das Chart, das Modul oder den Artefakt-Body der deklarierenden Entität lädt. Knotenübergreifende Referenzen zuzulassen, würde die Quellauflösung an die Iterationsreihenfolge der Topologie koppeln, was sie bewusst vermeidet.
Parameter (überall außer in Pfad-Templates)Jede Value-Template-Oberfläche nach der InterpolationDie Interpolation verbraucht jede Referenz {{ .parameters.X }} im verfassten YAML und schreibt an ihre Stelle den aufgelösten Wert, sodass eine Value-Template-Oberfläche das aufgelöste Literal statt der Parameter-Säule erhält. Vom Operator verfasste Pfad-Templates sind die eine Ausnahme und lesen .parameters.X direkt.

4. Der Pfad der Self-Inject-Auflösung

Die Self-Inject-Auflösung ist die erste Hälfte der Inject-Hydratation und läuft, nachdem die provides jedes Knotens ausgewertet wurden. Wenn eine Komponente einen Block inject: auf Komponentenebene deklariert, wertet der Compiler ihn dort aus:

  1. Literale Zeichenketten in value:: Wenn der Wert Go-Template-Ausdrücke enthält, wertet der Compiler sie mit dem Kontext aus Zeile #4 der Matrix aus (.values, .infra, .context.instance_id, .metadata.* usw.), maskiert geschrieben, wie Zeile #4 zeigt. Einfache Zeichenketten werden unverändert durchgereicht.
  2. Referenzen in from:: Der Compiler sucht den Schlüssel im eigenen Dictionary provides des Knotens, das bis dahin bereits aufgelöst ist. Existiert der Schlüssel nicht, hält der Compiler den Build mit einem Fehler wegen eines ungültigen inject-Schlüssels an.
  3. Kollisionsprüfung: Vor dem Zusammenführen in die Pipe .context.inject prüft der Compiler, dass kein Schlüssel mit den uses-inject-Schlüsseln kollidiert, die die zweite Hälfte der Inject-Hydratation auflöst. Kollisionen halten den Build mit einem Fehler wegen eines doppelten Zustellungsschlüssels an.

Die resultierenden Zeichenketten werden in .context.inject.env, .context.inject.file, .context.inject.arg (und alle benutzerdefinierten Mechanismen) zusammengeführt, neben diesen uses-inject-Auflösungen. Wenn das Inject-Mapping (injectMapping) läuft, enthält die Pipe alle vom Entwickler verfassten inject-Werte aus beiden Quellen.