Variablen der Pfad-Templates
Die Felder directory: und subDirectory: einer Release-Boundary sind Go-Templates, die zur Build-Zeit ausgewertet werden. Sie steuern, wo gerenderte Artefakte auf der Festplatte landen, und damit auch, welche Artefakte gemeinsam assembliert werden — zwei Boundaries, die zum selben Tupel (path, provider) ausgewertet werden, teilen sich einen Assembler und erzeugen eine einzige zusammengeführte Ausgabe (ein Chart.yaml, ein docker-compose.yaml). Diese Seite ist die Authoring-Referenz für die Variablen, auf die diese Templates verweisen können, für die strikte Auswertungssemantik und für die Kaskadenregeln, mit denen Boundaries von ihren übergeordneten Boundaries erben.
Für die konzeptionelle Behandlung der räumlichen Trennung und des Dispatch pro (path, provider) siehe architecture/16-recipe-input-composition.md. Für die Authoring-Oberfläche des Release auf Entitätsebene siehe entities/release.md. Die Provider-seitigen Konsequenzen stehen in providers/architecture.md und auf den Seiten der einzelnen Provider.
Strikte Auswertung: missingkey=error
Pfad-Templates werden im Modus missingkey=error von Go ausgewertet. Ein Verweis auf ein nicht deklariertes Feld, einen nicht gesetzten Schlüssel parameters.X oder ein Tippfehler wie {{ .parmaeters.region }} erzeugt einen expliziten Fehler, statt stillschweigend einen leeren String in einen Pfad zu rendern.
Die Striktheit ist asymmetrisch zum Rest des Compilers — valuesMapping, injectMapping und andere Oberflächen für das Rendern von Werten verwenden missingkey=zero gemäß der Konvention von Helm/Sprig. Die Pfadausgabe ist strukturell anders: Ein Template zum Rendern von Werten, das einen leeren String erzeugt, landet in einem Manifest-Feld, wo die Folge begrenzt ist; ein Pfad-Template, das einen leeren String erzeugt, landet in einem Verzeichnislayout, wo die Folge unbegrenzt ist (Kollisionen, defekte Assemblierung, Geisterpfade). Das strikte Regime der Pfad-Templates existiert, um diese Fehler zur Build-Zeit statt zur Bereitstellungszeit sichtbar zu machen.
Allowlist-Validierung zur Parse-Zeit
Zusätzlich zur Striktheit zur Laufzeit werden Pfad-Templates zur Parse-Zeit gegen eine geschlossene Allowlist von Variablennamen validiert. Ein Verweis auf einen Variablennamen, der nicht in der Allowlist steht, bricht den Build ab, bevor irgendeine Render-Arbeit beginnt, mit einer Diagnose, die das fehlerhafte Feld und die Boundary benennt, auf der es vorkommt.
Die Allowlist ist absichtlich geschlossen: Oberflächen wie .context.inject, .values und .locals werden Pfad-Templates bewusst nicht zur Verfügung gestellt. Die Pfadausgabe ist ein strukturelles Anliegen, kein Anliegen des Renderns von Werten; Assemblierungspfade an Werte pro Komponente zu binden, würde den Pfadgraphen datenabhängig machen und die Invariante der deterministischen Ausgabe aushöhlen.
Die Variablenmatrix
| Variable | directory: | subDirectory: | Beschreibung |
|---|---|---|---|
{{ .capability }} | ja | ja | Die Render-Fähigkeit (helm, helm-chart, compose, terraform, cloudformation), die das Recipe der beitragenden Komponente deklariert, für die Artefakte, die an diesem Pfad ausgegeben werden. |
{{ .boundary_name }} | ja | ja | Der verfasste Name der Boundary im Release (z. B. production, eu-prod). |
{{ .parameters.X }} | ja | ja | Jeder typisierte Parameter, der im Aggregate deklariert und vom Release erfüllt wird. Strikter Zugriff — ein Verweis auf .parameters.unknown bricht den Build ab. |
{{ .manifest.recipe_name }} | ja | ja | Der über das Manifest aufgelöste Recipe-Name für die beitragende Komponente. Nützlich, um Artefakte pro Recipe in Unterordner pro Recipe zu leiten. |
{{ .parent_boundary.* }} | ja | ja | Kaskadenzugriff auf die ausgewerteten Werte der umschließenden Boundary. Siehe Kaskade der übergeordneten Boundary weiter unten. |
{{ .component_id }} | — | ja | Die Instanz-ID der beitragenden Komponente. Für ein an einer Grenze angebundenes Feature, dessen FeatureRecipe einmal für die Grenze läuft (executionScope: boundary), ist es die zusammengesetzte Identität, die die Ressourcen dieser Anbindung in ihrem Label aggrega.ai/component-id tragen — bfr--app--shared für eine Anbindung shared an der Grenze app, gekürzt, wo der Provider der Anbindung Namen begrenzt —, sodass die Ausgabe der Anbindung in einem Verzeichnis landet, das nach diesem Label benannt ist. Nur in subDirectory: verfügbar, weil directory: eine Eigenschaft pro Grenze ist — die Verzeichniszeichenkette wird einmal pro Grenze berechnet, bevor irgendein Routing pro Komponente stattfindet. |
Das Feld directory: hat als Standardwert boundaries/, gefolgt vom Boundary-Pfad (ein stabiler Bezeichner zur Build-Zeit, abgeleitet aus dem Boundary-Baum); ein Release, das seine Komponenten auflistet, ohne Boundaries zu deklarieren, schreibt sie ganz ohne Verzeichnissegment. Das Feld subDirectory: hat als Standardwert {{ .capability }}, sodass die Artefakte jeder Fähigkeit in einem eigenen Unterordner unter dem Verzeichnis der Boundary landen — ob es weggelassen oder als subDirectory: "" geschrieben wird, was sich genau wie ein weggelassenes liest. Das Setzen von subDirectory: "." oder ein Template, das zu einem leeren String ausgewertet wird, hebt diese Gruppierung auf.
Was diese Templates nicht entscheiden: die Platzierung von artifacts:
Ein Segment des Ausgabepfads festzulegen ist nicht Sache eines Pfad-Templates. Eine Datei, die der Block artifacts: eines Recipe benennt, wird unter einem Verzeichnis geschrieben, das nach der Komponente benannt ist, die sie deklariert hat, innerhalb dessen, wozu subDirectory: ausgewertet wird. Dieses Segment ist fest und immer vorhanden, für ein Ziel, das die Dateien seiner Beitragenden nebeneinander schreibt, statt jeden Beitragenden in ein eigenes Chart oder Modul zu verschachteln.
Der Grund ist, was die Datei benennt. Ein Manifest, das ein Ziel rendert oder synthetisiert, wird vom Ziel nach der Komponente benannt, zu der es gehört, und identifiziert seine Komponente daher bereits. Ein Artefakt wird nach dem Schlüssel benannt, den sein Autor geschrieben hat — app-config.yaml, netpol.yaml —, und dieser Schlüssel sagt nichts über die Komponente aus, weil das Recipe, das es deklariert, nicht weiß, welche Komponenten an es gebunden werden. Zwei Komponenten in einer Boundary, die an ein Recipe gebunden sind, würden einen einzigen Pfad schreiben, und weder der Autor des Recipe noch der Autor des Release hat eine Oberfläche, auf der er sie trennen könnte.
Nur das Verzeichnis wird hinzugefügt; der Dateiname bleibt der verfasste Schlüssel, sodass die Datei, die ein Autor in der Ausgabe wiederfindet, den Namen trägt, den er geschrieben hat.
Was subDirectory: weiterhin bringt und wie sich beides kombiniert. subDirectory: verschiebt jede Datei, die ein Beitragender ausgibt — gerenderte Manifeste, synthetisierte Manifeste und Artefakte zusammen —, daher ist es das Werkzeug, um einer Komponente ein eigenes Verzeichnis für nachgelagerte Werkzeuge zu geben, die auf der gesamten Manifestmenge einer einzelnen Komponente arbeiten, oder um mehrere Komponenten in einen gemeinsamen Ordner zu leiten. Das Segment von artifacts: gilt unterhalb dessen, wozu es ausgewertet wird. subDirectory: "{{ .capability }}/{{ .component_id }}" auf einer Komponente zu schreiben, deren Recipe artifacts: deklariert, erzeugt daher den Namen der Komponente zweimal — das Artefakt landet unter <capability>/<component>/<component>/<key>, während die gerenderten Manifeste dieser Komponente unter <capability>/<component>/<key> landen. Greifen Sie zur Überschreibung, wenn Sie die gesamte Ausgabe der Komponente gesammelt haben möchten, und lassen Sie sie weg, wenn Sie nur die Artefakte trennen müssen, was der Standard bereits tut.
.capability wird pro Komponente aufgelöst, und die directory: einer Boundary wird für zwei unterschiedliche Zwecke ausgewertet. Die Auswertung pro Boundary, die .parent_boundary.directory an untergeordnete Boundaries veröffentlicht, läuft, bevor irgendeine Komponente gebunden ist, daher ist .capability dort leer. Die Auswertung pro Komponente, die festlegt, wo die Artefakte eines Beitragenden tatsächlich landen, trägt die Fähigkeit dieser Komponente. Eine übergeordnete Boundary, die directory: "d-{{ .capability }}" verfasst, veröffentlicht daher d- die Kaskade hinab, während ihre eigenen Artefakte unter d-compose landen.
Kaskade der übergeordneten Boundary
Verschachtelte Boundaries erhalten eine Sicht .parent_boundary, die den ausgewerteten Pfad der unmittelbar übergeordneten Boundary und deren eigene kaskadenaufgelöste Daten bereitstellt. Die Kaskade umfasst eine Ebene — die .parent_boundary einer Boundary ist ihre direkte übergeordnete Boundary, nicht die darüberliegende. Um weiter nach oben zu gelangen, verwendet die übergeordnete Boundary selbst .parent_boundary in ihren eigenen Templates und gibt Werte explizit den Baum hinab weiter.
Verfügbare Felder unter .parent_boundary:
| Feld | Beschreibung |
|---|---|
.parent_boundary.directory | Der ausgewertete Wert von directory: der übergeordneten Boundary (nach dem Template). |
.parent_boundary.boundary_name | Der verfasste Name der übergeordneten Boundary. |
.parent_boundary.parameters | Dieselbe Map .parameters.*, die die übergeordnete Boundary gesehen hat (Parameterwerte sind Release-global, aber der Alias wird aus Symmetriegründen bereitgestellt). |
.parent_boundary.annotations | Die kaskadenaufgelösten Annotationen der übergeordneten Boundary. |
Das kanonische Muster: eine übergeordnete Boundary, die einmal eine directory: verfasst, plus untergeordnete Boundaries, die ihre Artefakte unter die übergeordnete leiten, indem sie directory: "{{ .parent_boundary.directory }}" deklarieren. Dadurch fallen die untergeordneten Boundaries auf den Assemblierungspfad der übergeordneten zusammen und erzeugen eine einzige zusammengeführte Ausgabe, die Beitragende aus jeder untergeordneten Boundary enthält. Das Feature core/compose-bridge beruht genau darauf: eine übergeordnete Boundary mit der Bridge-Funktion, zwei untergeordnete Boundaries (zum Beispiel services-net und data-net), die sich die directory: der übergeordneten teilen, und ein einziges zusammengeführtes docker-compose.yaml, das jede Komponente plus den Bridge-Service enthält.
Die Umkehrung: Lassen Sie .parent_boundary.directory bei den untergeordneten Boundaries weg (oder lassen Sie sie zu einem eigenen Pfad ausgewertet werden), und jede erhält ihre eigene Assemblierung. Beide Formen sind vollwertig.
Ausgearbeitete Layouts
Layout 1 — standardmäßige Trennung pro Boundary
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Jede Boundary wird zu einer eigenen directory: ausgewertet, daher erhält jede ihre eigene Assemblierung:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...Der Standard subDirectory: "{{ .capability }}" trennt Artefakte pro Fähigkeit innerhalb jedes Boundary-Verzeichnisses. Zwei Boundaries, zwei Assemblierungsausgaben pro Fähigkeit, keine Zusammenführung.
Layout 2 — zusammengeführte Assemblierung über ein gemeinsames übergeordnetes Verzeichnis
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Beide untergeordneten Boundaries werten directory: zu deploy/cluster aus (dem Verzeichnis der übergeordneten), daher werden alle Beitragenden an einem Assemblierungspfad zusammengeführt. Mit dem Standard subDirectory: "{{ .capability }}" landen die compose-Beitragenden beider untergeordneter Boundaries in deploy/cluster/compose/ und erzeugen ein einziges zusammengeführtes docker-compose.yaml. Das an der übergeordneten Boundary angebundene Feature compose-bridge läuft einmal (Dispatch im Boundary-Bereich) und steuert den Bridge-Service zu derselben zusammengeführten Datei bei.
Die Annotation aggrega.ai/chart-name: "cluster-umbrella" der übergeordneten Boundary kaskadiert zu beiden untergeordneten; enthielten die Boundaries auch helm-chart-Beitragende, würden sich die helm-chart-Subcharts beider untergeordneter Boundaries unter einem einzigen Umbrella namens cluster-umbrella zusammensetzen. Nicht übereinstimmende chart-name-Werte zwischen Beitragenden an einem Pfad brechen den Build ab.
Layout 3 — Routing pro Komponente über subDirectory: plus Parameter
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"Die directory: der Boundary wird zu deploy/eu-west-1 ausgewertet (Parameterersetzung). Überschreibungen von subDirectory: pro Komponente leiten jeden Beitragenden in einen Unterordner pro Komponente, wobei die Komponente ingress auf einen flachen Unterordner shared für übergreifende Artefakte überschreibt:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Dieses Muster passt zu Unternehmen, die Artefaktverzeichnisse pro Komponente für nachgelagerte Werkzeuge wollen, die auf den Manifesten einer einzelnen Komponente arbeiten. Wenn das Recipe einer Komponente auch artifacts: deklariert, lesen Sie vor der Wahl dieser Form Was diese Templates nicht entscheiden weiter oben: Diese Dateien tragen bereits ein Komponentensegment, daher fügt diese Überschreibung ein zweites hinzu.
Diagnose
Die Oberfläche der Pfad-Templates bricht den Build in jeder der folgenden Situationen ab, und errors/fatal-halts.md dokumentiert sie unter diesen Namen. Diese Seite zitiert die Meldung, die jeder Abbruch ausgibt; gleichen Sie die Build-Ausgabe mit diesem Text ab.
- Path-template references a variable outside the allowlist (Das Pfad-Template verweist auf eine Variable außerhalb der Allowlist) — zur Parse-Zeit: Ein Pfad-Template verweist auf eine Variable, die nicht in der Allowlist steht.
- Path collision (Pfadkollision) — zur Assemblierungszeit: Zwei Boundary-Beitragende werden zum selben Pfad ausgewertet, stimmen aber bei einer Eigenschaft nicht überein, die über alle Beitragenden an diesem Pfad einheitlich sein muss.
- Instance-ID collision (Instanz-ID-Kollision) — zur Assemblierungszeit: Zwei Boundaries, die zum selben Tupel
(path, provider)ausgewertet werden, steuern Komponenten mit identischen Instanz-IDs bei. - Chart-name mismatch (Abweichender Chart-Name) — zur Assemblierungszeit: Eine zusammengeführte helm-chart-Assemblierung erhält Beitragende mit widersprüchlichen, kaskadenaufgelösten Annotationen
aggrega.ai/chart-name. - Missing template key (Fehlender Template-Schlüssel) — ein Pfad-Template verweist auf ein Feld unter einer offenen Variable, das zu keinem Wert aufgelöst wird (z. B.
{{ .parameters.region }}, wenn das Releaseregionweglässt, oder ein Schlüssel von.parent_boundaryan einer Boundary der obersten Ebene, die keine übergeordnete hat);missingkey=errorerzeugt eine explizite Meldung, die die Boundary, das Template-Feld (directory:odersubDirectory:) und den fehlenden Schlüssel benennt..parametersund.parent_boundarysind offen — ihre Schlüssel sind verfasste Daten —, während.manifestseine Schlüssel deklariert, sodass ein falsch geschriebener Schlüssel unter.manifeststattdessen zur Parse-Zeit als unbekannter Verweis zurückgewiesen wird, wobei die Diagnose die Schlüssel auflistet, die.manifestdefiniert.
Querverweise
entities/release.md— Authoring des Release, einschließlich der räumlichen Trennung und der Felderdirectory:/subDirectory:.providers/architecture.md— Provider-Dispatch und das Assemblierungsmodell pro(path, provider).providers/compose.md— compose-seitige Ausgabe pro(path, provider), einschließlich des Szenarios mit zusammengeführtem Pfad.providers/helm-chart.md— Umbrella-Komposition von helm-chart und die Kaskadenregel für chart-name bei zusammengeführten Pfaden.entities/featurerecipe.md— FeatureRecipes im Boundary-Bereich (das Featurecore/compose-bridgeberuht auf dem hier dokumentierten Assemblierungsmodell mit zusammengeführtem Pfad).errors/fatal-halts.md— vollständiger Diagnosekatalog, einschließlich der oben aufgeführten Abbrüche beim Pfad-Dispatch.