FeatureRecipe
Die konzeptionelle Rolle der Entität FeatureRecipe (Domäne 3 — die durch Wasm-Plugins gesteuerte Implementierung einer Feature-Schnittstelle) ist in architecture/04-entity-taxonomy.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche des Katalogs für FeatureRecipe.
Ort im Katalog
FeatureRecipes sind mit dem Provider im ersten Pfadsegment organisiert (nach demselben Muster wie Recipes):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlOCI-URI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (z. B. hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Authoring-Vertrag
FeatureRecipes binden sich über implements an eine Feature-Schnittstelle und deklarieren einen konkreten Provider. Ihre Authoring-Oberfläche ist der vollständige Satz an Eingabearten des Basis-Recipe plus zwei FeatureRecipe-spezifische Blöcke:
- Die drei Eingabearten —
source+valuesMapping(bezogen),workload(synthetisiert) undartifacts: in ihrer Form identisch mit dem Basis-Recipe (siehe Komposition der Recipe-Eingaben undentities/recipe.md). Ein FeatureRecipe, das eine davon trägt, ist ressourcenerzeugend — es rendert Ressourcen neben der Basiskomponente. Wo diese Ressourcen landen, trägt die Komponente, an die das Feature angebunden ist, und dann den Namen, unter dem es angebunden ist, in derjenigen der beiden Formen, die das eigene Layout des Ziels zulässt: als Verzeichnis{component}--{instance}/neben dem des Hosts, unter dem Verzeichnis, das dieses Ziel für seine Beitragenden vorsieht, auf einem Ziel, dessen Provider jedem Beitragenden eine eigene Position gibt; als Dateinamenpräfix{component}--{instance}--neben den eigenen Dateien der Komponente, auf einem Ziel, das nur die Dateien liest, die direkt in einem Verzeichnis liegen. Auf einem Provider, der seine Beitragenden zu einem einzigen Dokument zusammensetzt, werden die Ressourcen stattdessen in dieses Dokument eingefügt — gleich, zu welcher Familie das Feature gehört: eine CRDServiceMonitoroderExternalSecretals inline oder per$importeingebundeneartifacts:; ein externes Chart oder Modul übersource:+valuesMapping:; oder eigene Rechenleistung (zum Beispiel ein Sidecar-Agent-Deployment) überworkload:.valuesMapping:teilt die drei Authoring-Modi des Basis-Recipe (Inline-Block-Scalar, Datei-$import:, Bibliotheks-$import:auf einen Eintrag einer MappingLibrary) — sieheentities/recipe.md„Das FeldvaluesMapping— drei Authoring-Modi“. Per Konvention modifiziert ein FeatureRecipe die Basiskomponente oder fügt Ressourcen neben ihr hinzu, aber das Schema schränkt nicht ein, welche Eingabearten es verwenden darf — der Compiler rendert, was auch immer das FeatureRecipe deklariert, begrenzt nur durch die Fähigkeit des gebundenen Providers, und bleibt meinungslos darüber, ob eine bestimmte Art „für Modifikatoren geeignet“ ist (siehe die grundlegenden Invarianten). Synthese (workload:) erfordert einen Provider, der sie unterstützt; andernfalls hält der Build beim Rendern mit der Diagnose zur Provider-Fähigkeit an. injectMapping(Abfangen vor dem Rendern): Ein nativer Go-Template-Block, der vor dem Rendern des Basis-Recipe ausgeführt wird. Er gibt ein JSON- oder YAML-Dictionary aus, das der Compiler nativ per Deep-Merge über die Speicher-Pipe.context.injectdes Aufrufers legt, und ermöglicht so eine Wasm-freie, aufruferseitige Mutation von Umgebungsvariablen und Verbindungszeichenfolgen.pipeline: Ein sequenzielles Array von WebAssembly-(Wasm-)Plugin-Schritten für die Workload-Mutation nach dem Rendern (z. B. das Injizieren eines Envoy-Sidecars per JSONPatch oder das Einhängen eines Secret-Volumes). Das Feldpluginjedes Schritts benennt einePlugin-Entität über ihre URI, stets nach dem eigenen Socket-Typ des Plugins qualifiziert (<pluginType>/<name>, optional versioniert, wie inparser/yamloderparser/yaml:1.0.0); der Build löst die Entität zu ihrem inhaltsadressierten.wasm-Artefakt auf, das anhand der Identität des Plugins und der konfigurierten Registry gefunden wird, und ein bloßes.wasmoder eine Artefaktreferenz wird hier nicht akzeptiert. Siehe den Entwicklerleitfaden für Wasm-Plugins zum Verfassen und Referenzieren eines Plugins und architecture/04-entity-taxonomy.md §„Domäne 3: Infrastrukturbasis“ für das Prinzip des zweiteiligen Plugins (Fetcher / Injector). Der Compiler führt jeden Schritt in der deklarierten Reihenfolge aus: Er ruft den Guest-Export des benannten Plugins gegen die gerenderte Ausgabe auf und wendet die zurückgegebenen JSON Patches und die ausgegebenen Nebeneffekte an; siehe Status der Sprache für den Ausführungsstand jeder Pipeline-Oberfläche. Einepipeline:steht für sich: Ein FeatureRecipe kann eine deklarieren und gar keine Eingabeart, in welchem Fall es keine eigenen Ressourcen ausgibt und seine gesamte Wirkung darin besteht, was seine Schritte in die bereits vom Build gerenderten Dokumente patchen oder neben ihnen ausgeben.
Ein FeatureRecipe kann auch keinen dieser Blöcke tragen: Ein reines Verdrahtungs-Feature, dessen Wirkung die uses-Kante ist, die es trägt, rendert nichts, und sein FeatureRecipe existiert nur, um die Auflösung zu erfüllen — jede Feature-Instanz wird zu einem FeatureRecipe aufgelöst, so wie jede Komponente zu einem Recipe aufgelöst wird. Unter den obigen Blöcken ist injectMapping das einzige Feld ohne Gegenstück im Basis-Recipe; die drei Eingabearten und pipeline werden mit dem Basis-Recipe geteilt.
Was neben einem FeatureRecipe gepinnt wird, ist das, was neben einem Recipe gepinnt wird: der Digest jeder Datei, die ein artifacts-Eintrag importiert, und jeder entfernten source:, deren Koordinaten vollständig ausgeschrieben sind, in einer entity.lock im eigenen Verzeichnis des FeatureRecipe, die aggrega pin schreibt und die Sie daneben committen. Ein Pull über ein FeatureRecipe, dessen Lock diese Pins nicht verzeichnet, hält an und benennt diesen Schritt, es sei denn, der Pull wird angewiesen, ihn auszuführen. Ein Build hält an, wenn eine importierte Datei nicht mehr zu ihrem Digest passt, und wenn der Digest einer Quelle von dem abweicht, den die Lockfile des Release verzeichnet (eine an einem git-ref: geschriebene Quelle wird mit dem Commit verzeichnet, zu dem sie aufgelöst wurde, und nicht verglichen); die FeatureRecipe-Datei selbst wird nie beschrieben. aggrega pull beschreibt die Datei und wie auf jeden Halt zu reagieren ist.
Templating des Source-Felds
Das source: eines FeatureRecipe ist eine Templating-Oberfläche zu denselben Bedingungen wie das eines Recipe: Das Template wird bei der Auflösung der Quelle ausgewertet, und was es erzeugt hat, ist das, was der Build anschließend auflöst. Beide Formen akzeptieren Go-Templates — die universelle String-Form und die strukturierte Objektform, deren String-wertige Unterfelder als Template ausgewertet werden, während Unterfelder, die keine Strings sind, unverändert durchgereicht werden. Die Übersicht der Formen, die Behandlung der Schemata und die Lesart der Verankerung sind diejenigen, die in entities/recipe.md unter „Templating des Source-Felds“, „Übersicht der Schemata des Source-Felds“ und „Wie ein source:-Pfad verankert wird“ dargelegt sind; dieser Abschnitt nennt nur, was sich für eine Anbindung unterscheidet.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Wogegen ein relatives Ergebnis aufgelöst wird. Gegen das Verzeichnis, das das FeatureRecipe-Dokument enthält, das es deklariert hat — die eigene Datei der Anbindung, nie die der Komponente —, und das Ergebnis muss innerhalb dieses Verzeichnisses bleiben, genau wie bei einem Recipe: Ein Ergebnis, das es verlässt oder ein absoluter Pfad ist, benennt eine Datei, die nicht mit dem FeatureRecipe mitwandern würde, und bricht den Build ab. Eines mit einem Transportschema wird abgerufen, statt mit einem Verzeichnis verbunden zu werden. Ein FeatureRecipe, das aus einer Registry aufgelöst wird, wird aus den Dateien gelesen, die sein veröffentlichtes Archiv enthält und die im Content-Cache abgelegt sind, sodass ein relatives Ergebnis innerhalb des Veröffentlichten genau so aufgelöst wird, wie es neben dem FeatureRecipe in einem Katalogverzeichnis aufgelöst wird, mit derselben Grenze.
Was das Template lesen darf. Die Referenzmenge ist diejenige, gegen die die eigenen locals:-Einträge des FeatureRecipe geprüft werden; sie unterscheidet sich von der eines Recipe in zwei Punkten, die daraus folgen, dass eine Anbindung statt einer Komponente aufgelöst wird:
.attachment_nameist verfügbar und benennt die Instanz, unter der das Feature angebunden ist. Das Source-Template eines Recipe lehnt es ab, weil die Quelle eines Recipe für einen Knoten aufgelöst wird und keine Anbindung im Spiel ist..context.instance_idbenennt die Host-Komponente, für die die Anbindung aufgelöst wird, nicht die Anbindung, und.context.rendered_nameenthält den Namen, den der eigene Provider des Hosts für den Host meldet — nur vorhanden, wo dieser Provider einen meldet, und mit Abbruch des Builds, wo er das nicht tut. Siehe Benennen einer gerenderten Ressource.
.locals enthält die Menge, die die anderen Templates dieses FeatureRecipe lesen: seinen eigenen aufgelösten Block, darunter den des Host-Recipe, sodass ein Schlüssel, den die Anbindung deklariert, Vorrang vor einem gleichnamigen Host-Schlüssel hat. Ein Verweis auf einen Schlüssel, den diese Menge nicht enthält, bricht ab und benennt ihn, statt den Schlüssel beim Rendern wegfallen zu lassen. .provides, .context.inject und .context.uses werden aus denselben Gründen der Selbstständigkeit abgelehnt, aus denen die Source-Oberfläche eines Recipe sie ablehnt.
Ein FeatureRecipe mit Grenz-Scope liest stattdessen die Grenze. Ein Feature, dessen FeatureRecipe executionScope: boundary deklariert, wird einmal für die Grenze statt einmal pro Komponente gerendert, sodass sein Source-Template keine Host-Komponente zu lesen hat. Es liest .boundary.* — dieselben Säulen, die seine locals: und provides: lesen —, und die komponentenspezifischen Säulen (.context, .workload, .attachment_name, .inject) stehen ihm nicht zur Verfügung.
Ein leeres Ergebnis. Ein Template, das nichts erzeugt, lässt die Anbindung ohne Quelle, was der quelllose Modus ist — dieselbe Lesart, die die Quelle eines Recipe annimmt, und etwas anderes, als selbst source: "" zu schreiben.
Was .source danach liest. Die Source wird vor dem valuesMapping: ausgewertet, so wie die eines Recipe vor dessen eigenem, und was sie erzeugt hat, ist .source in jedem Template, das danach läuft: im valuesMapping:, im omits:, in den Inhalten von workload: und artifacts: und in den pipeline:-Schritten. Ein valuesMapping:, das .source liest, liest also die eigene Source dieses FeatureRecipe, nie die Source der Komponente, an die es angebunden ist, und liest nichts, wo dieses FeatureRecipe keine Source deklariert oder sein Template nichts erzeugt. Ein FeatureRecipe mit Boundary-Scope liest seine eigene Source auf dieselbe Weise. Das injectMapping: läuft, bevor die Source der Anbindung ausgewertet wird, daher ist .source dort die der Host-Komponente.
Exklusivität von injectMapping
Das Feld injectMapping ist exklusiv für FeatureRecipes — es fehlt absichtlich im Basisschema von Recipe. Diese Exklusivität trennt das Abfangen von Variablen von valuesMapping: Das valuesMapping des Basis-Recipe konsumiert, ohne es zu wissen, die umgeschriebenen .context.inject-Strings, die von den injectMapping-Blöcken des FeatureRecipe erzeugt werden, sodass beide entkoppelt bleiben. Wie der Mechanismus abläuft, beschreibt der Abschnitt zum Abfangen per Inject-Mapping weiter unten; die vollständige Semantik des Abfangens vor dem Rendern beschreibt architecture/10-compilation-pipeline.md zum Inject-Mapping.
Abfangen per Inject-Mapping: Wie injectMapping funktioniert
Wenn ein Aufrufer die Verbindungszeichenfolge zu seinem Ziel anders geformt benötigt als das unveränderte .provides.host des Ziels — durch Anhängen eines Namespace für grenzüberschreitendes Kubernetes-DNS, Voranstellen eines Regionscodes für ein Multi-Region-Gateway oder Hinzufügen eines SSL-Modus-Suffixes an einen DSN —, übernimmt injectMapping die Änderung beim Aufrufer, bevor das valuesMapping des Basis-Recipe den Inject-Kanal überhaupt sieht.
Das Feld injectMapping ist ein Go-text/template, das der Renderer beim Inject-Mapping auswertet, bevor das Rendern des Basis-Recipe läuft. Das Template gibt ein JSON- oder YAML-Dictionary mit optionalen Mechanismus-Schlüsseln (env, file, arg oder ein eigener Mechanismus, den das Recipe der Komponente unter .context.inject.<name> liest) aus — oder eine flache Map, die standardmäßig env ist —, und der Renderer führt dieses Overlay per Deep-Merge über den .context.inject-Kanal des aufrufenden Knotens zusammen. Aufruferseitiges Routing über injectMapping läuft beim Inject-Mapping, ohne für einfache String-Manipulation eine Wasm-Sandbox aufzurufen; Wasm-Plugins bleiben strukturellen AST-Änderungen über das pipeline-Array vorbehalten.
Schreiben Sie jeden Wert über toJson. Der Renderer liest die Ausgabe des Templates als YAML, sodass ein unverändert zwischen Anführungszeichen interpolierter Wert diese Ausgabe entweder zerstört oder verändert zurückgelesen wird, sobald er ein doppeltes Anführungszeichen oder einen Backslash enthält — ein Passwort ist der übliche Fall. toJson schreibt den Wert als JSON-String, den YAML exakt zurückliest, sodass der Wert mit jedem Zeichen ausgeliefert wird, das er enthält:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}Ein Wert, der aus mehreren Teilen zusammengesetzt wird, wird zuerst zusammengesetzt und dann einmal über toJson geschrieben, wie es die folgenden Beispiele tun.
Eine Ausgabe, die nicht gelesen werden kann, stoppt den Build. Wenn sich die Ausgabe des Templates als keine der beiden Formen lesen lässt — die übliche Ursache ist ein in Anführungszeichen gesetzter Skalar, den der darin enthaltene Wert zerstört —, könnte keiner ihrer Schlüssel ausgeliefert werden, sodass der Build anhält und die Anbindung sowie das FeatureRecipe nennt, statt die Komponente zu rendern, als wäre nichts ausgeliefert worden; siehe fatal-halts.md „An attached Feature’s injectMapping output cannot be read (Die injectMapping-Ausgabe eines angebundenen Feature kann nicht gelesen werden)“. Der angegebene Grund wird zurückgehalten, wenn er von einem als sensibel deklarierten Wert abhängt. Eine Ausgabe, die leer ist oder als Dictionary geparst wird, das nichts ausliefert, liefert nichts aus und ist kein Fehler.
Ein Schlüssel der obersten Ebene ist ein Mechanismus, und all ist keiner. Jeder Schlüssel der obersten Ebene einer Dictionary-Ausgabe nennt den Mechanismus, über den seine Einträge ausgeliefert werden: env, file und arg oder jeder andere Name, der als eigener Mechanismus unter diesem Namen ausgeliefert wird. .context.inject.all wird nach dem Merge aus diesen Mechanismen aufgebaut und nie aus einer Ausgabe zusammengeführt, sodass unter all: geschriebene Einträge nichts erreichen würden; stattdessen hält der Build an, nennt die Anbindung, den Schlüssel und das FeatureRecipe und gibt an, welche Schlüssel eine Ausgabe enthalten darf — siehe fatal-halts.md „An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Die injectMapping-Ausgabe eines angebundenen Feature schreibt Auslieferungen unter einen Schlüssel, den nichts ausliefert)“. Schreiben Sie solche Einträge unter den Mechanismus, aus dem die Komponente sie liest.
Die Änderung ist streng lokal beim Aufrufer. Das FeatureRecipe ändert nur den Inject-Kanal des Knotens, an den es angebunden ist, nie die .provides-Ausgabe des Ziels. Das .provides.host eines Ziels wird potenziell von vielen Aufrufern im gesamten Cluster konsumiert; aufruferseitiges injectMapping führt nur in den Kanal des jeweiligen Aufrufers zusammen, sodass Routing-Änderungen auf die Kante beschränkt bleiben, die sie angefordert hat.
Was ein Mapping umschreiben darf. Jeder inject:-Block hat bereits geliefert, wenn die Mappings gerendert werden, sodass die Ausgabe eines Mappings immer über Schlüssel zusammengeführt wird, die bereits etwas anderes geschrieben hat — und wer einen Schlüssel geschrieben hat, entscheidet, was geschieht. Einen Schlüssel, den der eigene inject:-Block des Aufrufers oder der inject:-Block einer seiner Verbindungen geliefert hat, darf das Mapping umschreiben: Das ist Abfangen, und der Wert des Mappings ersetzt genau diesen einen Eintrag. Einen Schlüssel, den die eigene Anbindung des Mappings über ihren inject:-Block geliefert hat, darf es ebenfalls umschreiben. Einen Schlüssel, den ein anderes angebundenes Feature bereits geliefert hat — über seinen eigenen inject:-Block oder das injectMapping seines eigenen FeatureRecipe —, darf es nicht: Der Build bricht ab und benennt beide Anbindungen, statt das zuletzt ausgeführte Mapping entscheiden zu lassen, welchen Wert der Aufrufer liest. Zwei Routing-Features können also jeweils einen eigenen Schlüssel qualifizieren, aber zwei Features können nicht beide denselben Schlüssel liefern — einschließlich zweier Routing-Features, die den Schlüssel derselben Verbindung umschreiben, da das erste Abfangen ist und das zweite auf die Lieferung des ersten trifft; siehe fatal-halts.md „Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping“ (Zwei angebundene Features liefern denselben Schlüssel, das spätere über das injectMapping seines FeatureRecipe).
Zielableitung ohne Kopplung
Da der Compiler die kaskadierten Annotationen jedes Ziels in den .context.uses-Kanal des Aufrufers einbettet, kann das injectMapping-Template Routing-Koordinaten extrahieren, ohne dass Ops die Identität des Ziels fest im infra des Features codiert:
- Das Template durchsucht
.context.uses, um genau die topologische Kante zu finden, die die vom Entwickler angeforderte Variable injiziert hat. - Es extrahiert die kaskadierten
release_annotationsdes Ziels (z. B.aggrega.ai/namespace). - Es formatiert den vollqualifizierten Domänennamen (FQDN) oder die Verbindungszeichenfolge.
- Es gibt das Override-Dictionary aus.
Der Compiler bleibt agnostisch gegenüber der Netzwerksemantik — Kubernetes-Namespaces, Cloud-Regionen, Bridge-Proxy-Topologien — und führt einfach den Deep-Merge mit dem aus, was das Template erzeugt hat. Wenn anschließend das valuesMapping des Basis-Recipe läuft, konsumiert es die abgefangenen, umgeschriebenen Strings aus .context.inject.env, als wären sie die Originale des Entwicklers.
Ausgearbeitetes Beispiel: K8s-DNS-Resolver
Der Standardkatalog liefert dies als core/k8s-dns-resolver mit einem Helm-FeatureRecipe aus. Da Namen von Umgebungsvariablen innerhalb eines Containers eindeutig sein müssen, dient die target_var (z. B. API_HOST) als global eindeutiger Bezeichner für einen bestimmten Injektionsvertrag innerhalb des Aufrufers. Indem das Template über die expliziten Kanten in .context.uses iteriert und prüft, welche Kante die target_var beansprucht hat, findet es den richtigen Zielknoten und liest dessen Namespace. Der einzige Parameter ist die umzuschreibende Variable; das Ziel und sein Namespace werden ermittelt, nie fest codiert.
Das Schema des Routing-Features (core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}Die FeatureRecipe-Implementierung:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}Anwendungsfälle über Routing hinaus
injectMapping wird am häufigsten für grenzüberschreitende Adressauflösung verwendet (wie beim K8s-DNS-Resolver oben), doch diese aufruferseitige Änderung gilt für jedes Szenario, das das Abfangen und Formatieren der Entwicklerabsicht vor dem Rendern der Infrastruktur erfordert. Zwei weitere Muster veranschaulichen die Bandbreite.
Dynamische Sicherheitsformatierung (der SSL-Appender). Wenn ein Unternehmen vorschreibt, dass alle externen Datenbankverbindungen eine strikte TLS-Verifizierung verwenden, kann ein Feature die vom Entwickler angeforderte DB_URL abfangen und den erforderlichen SSL-Modus anhängen, sodass die Anwendung mit den richtigen Sicherheitsparametern startet.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}Präfixe für Multi-Region-Gateways. Wenn eine generische API-Komponente global bereitgestellt wird, kann ein regionales Routing-Feature selbstständig die Annotationen seiner eigenen Umgebungsgrenze nachschlagen, um den injizierten Verbindungszeichenfolgen für seine Aufrufer ein Präfix voranzustellen.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}Die Grenze von injectMapping. Der Mechanismus beschränkt sich auf das Ändern des Speicherkanals .context.inject (des Liefervertrags). Er kann keine neuen Container anhängen, keine Volumes einhängen und die valuesMapping-Ausgabe des Basis-Recipe nicht verändern. Jede Änderung, die strukturelle Änderungen am gerenderten AST erfordert (etwa an JSON- oder YAML-Arrays), gehört in das pipeline-Array des FeatureRecipe und wird über WebAssembly-Plugins ausgeführt.
Die Grenze der Patch-Ziele von pipeline. Ein pipeline-Schritt patcht nur Ausgabe, die der Provider in einen strukturierten Baum rendert. YAML- und JSON-förmige Ausgabe ist strukturiert — einschließlich in JSON verfasster Terraform-Module .tf.json —, sodass der JSONPatch eines Schritts die adressierten Werte direkt bearbeitet und jedes andere Byte (Kommentare, Reihenfolge, Formatierung) unberührt lässt. Ausgabe, die der Provider als opaken Body ausgibt, etwa Terraform-Konfiguration in nativem HCL, ist kein Patch-Ziel: Ein Patch gegen einen opaken Body bricht den Build mit einer Diagnose ab, statt Text zu verändern, den er nicht strukturell adressieren kann. Einen pipeline-Schritt gegen opake Ausgabe zu schreiben, ist daher ein Entwurfsfehler, der als lauter Abbruch sichtbar wird, nicht als stilles No-op.
Die Eingaben eines vendorten Terraform-Moduls sind kein Patch-Ziel, und dieses Fehlen ist erwähnenswert. Sie sind die Argumente des module-Blocks dieser Komponente, den der Terraform-Provider in die Root-Konfiguration der Grenze schreibt: natives HCL, also nach der obigen Regel opak, und ein Artefakt der gesamten Grenze statt des Knotens, dessen Ausgabe der Schritt patcht. Es gibt also keine Position, von der aus ein pipeline-Schritt sie adressieren könnte, und nichts, was er tun kann, um zu ändern, was ein über source bezogenes Terraform-Modul erhält. Diese Werte werden dort geformt, wo sie verfasst werden — im valuesMapping: des Basis-Recipe.
Bedingte Schritte — when:
Ein pipeline-Schritt kann ein optionales Feld when: tragen: ein Inline-Go-Template, das der Compiler beim Durchlaufen der Pipeline auswertet, gegen denselben Template-Kontext und denselben Evaluator, die der with:-Body des Schritts verwendet. Das gerenderte Ergebnis entscheidet, ob der Schritt läuft.
- Ein falsy Ergebnis überspringt den Schritt als Durchreichung: Die Dokumentmenge fließt unverändert zum nächsten Schritt, und der übersprungene Schritt trägt nichts bei — keinen Patch, keinen Nebeneffekt, keinen Nachweis, gelaufen zu sein.
- Ein leeres oder fehlendes
when:führt den Schritt immer aus.
when: und optional: sind unabhängig. when: entscheidet, ob ein Schritt überhaupt läuft; optional: mildert das Fehlschlagen eines laufenden Schritts ab. Ein Schritt kann beide deklarieren — when: steuert den Eintritt, und wenn der Schritt läuft, regelt optional:, wie ein Fehler darin behandelt wird. Ein when:-Template, das sich nicht rendern lässt, ist ein Autorenfehler und bricht den Build unabhängig von optional: ab.
Der gerenderte when:-Text wird nach der gemeinsamen Regel für boolesche Templates beurteilt: Die Strings true, True und TRUE, jede Zahl ungleich null und jeder andere nicht leere String sind wahr; die Strings false, False und FALSE, der leere String und eine Null sind falsch.
FeatureRecipe-Muster für Zugangsdaten
Wenn ein FeatureRecipe ein Zugangsdaten-Feature implementiert (eines mit dem Label feature.aggrega.ai/kind: secret), kann es dem Zwei-Teile-Plugin-Prinzip folgen: eine pipeline, die ein Fetcher-Plugin (das die vault-spezifische CRD erzeugt) und ein Injector-Plugin (das das Secret in den Zielcontainer einhängt) verkettet, die Form, die examples/04-secrets beschreibt. Die Zugangsdaten-FeatureRecipes der Standardbibliothek deklarieren keine pipeline: und rendern die Secret-Ressource selbst; siehe examples/05-credential-features.
Ein Zugangsdaten-FeatureRecipe rendert über denselben Durchlauf der Ressourcenerzeugung wie das jeder anderen Anbindung, und seine pipeline: wird zu denselben Bedingungen ausgeführt: Der Compiler durchläuft jede Anbindung, die in diesem Durchlauf Arbeit hat, als eine geordnete Folge und führt die jeweils deklarierte Pipeline aus, mit derselben Semantik der Dokumentmengen /own und /host. Eine Anbindung tritt dieser Folge aus einem von zwei Gründen bei — ihr FeatureRecipe deklariert eine Eingabeart und erzeugt also eigene Ressourcen, oder es deklariert eine pipeline: und schreibt also bereits ausgegebene Dokumente um. Eine Zugangsdaten-Anbindung kann daher in die gerenderten Dokumente der Host-Komponente eingreifen — ein Secret-Volume einhängen, eine Env-Referenz hinzufügen — genau wie eine operative Anbindung, und der einzige Unterschied zwischen beiden ist, wo ihre eigenen erzeugten Dateien landen.
Auf einer Komponente folgt eine Sensitivitätsdeklaration am Feature dem valuesMapping: des FeatureRecipe genau so, wie die einer Component dem ihres Recipe folgt. Wo ein FeatureRecipe aus einer source: ohne valuesMapping: rendert, tragen die Werte, die sein Ziel erhält, als Schlüssel die Blattpfade, die das Feature deklariert, sodass ein als sensitive: true deklariertes Blatt seinen gerenderten Schlüssel markiert. Wo das FeatureRecipe ein valuesMapping: deklariert, sind die Schlüssel eine eigene Erfindung dieses Templates, keine Deklaration benennt sie, und der Build gibt pro solchem Blatt einen Hinweis aus, der die Anbindung, das Blatt und das FeatureRecipe benennt. Ein an eine Grenze angebundenes Feature erzeugt keinen: Sein .values ist immer leer, sodass kein deklariertes Blatt einen zu markierenden Wert hat — siehe A declared-sensitive value reaches the target through a values mapping (Ein als sensibel deklarierter Wert erreicht das Ziel über ein Values-Mapping).
Der provides:-Block — Veröffentlichung an den Konsumenten
Der provides:-Block eines FeatureRecipe ist seine veröffentlichte Ausgabe: eine Map mit String-Werten aus Go-Templates, die im eigenen Scope der Anbindung ausgewertet werden (.values, .infra, die vollständig aufgelösten .locals des FeatureRecipe sowie .context.instance_id und .context.rendered_name des Host-Knotens). Die Locals werden zuerst aufgelöst, sodass ein provides:-Eintrag sie liest und aufgelöste Werte erhält; einen Schlüssel zu nennen, den der locals:-Block nicht deklariert, führt zum Abbruch. So teilt eine Anbindung ihrem Konsumenten mit, was sie erzeugt hat — den Namen einer ausgegebenen Ressource, einen erzeugten Datenschlüssel, eine Cloud-Identität —, ohne dass der Konsument diese Identität aus denselben Eingaben erneut ableitet.
Der Konsument liest sie unter .features.<instance-name>.provides.<key> (oder .features.<slot>.provides.<key> für eine Zugangsdaten-Anbindung), analog zu .context.uses.<alias>.provides für eine uses-Kante. Wo die Anbindung auf einer der Verbindungen des Konsumenten geschrieben ist, liest der Konsument dieselbe Map unter dieser Verbindung, unter .context.uses.<alias>.features.<slot>.provides.<key>, und die Anbindung gehört nicht zu seinen .features (siehe Die Anbindungen einer Verbindung). Der eigene inject:-Block der Anbindung löst seine from:-Verweise gegen dieselbe Map auf, sodass ein Autor einen der beiden Kanäle wählen kann: provides für einen Template-Lesezugriff, inject für die Lieferung in eine Umgebungsvariable, eine Datei oder ein Argument.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"Wenn das Feature, das dieses FeatureRecipe per implements implementiert, einen schema.provides-Vertrag deklariert, wird der Vertrag gegen das FeatureRecipe durchgesetzt: Jeder Schlüssel, den das Feature deklariert, muss im provides: des FeatureRecipe erscheinen, sonst bricht der Build ab und benennt den fehlenden Schlüssel. Zusätzliche veröffentlichte Schlüssel sind erlaubt — der Vertrag ist eine Untergrenze, keine Obergrenze. Werte werden nie inspiziert; sie sind opake deterministische Zeiger, die die Laufzeit auflöst.
Die Auflösung erfolgt einmal pro Anbindung, bevor der Konsument rendert, und dieselbe aufgelöste Map speist den Lesezugriff des Konsumenten, die Vertragsprüfung und die eigene Ressourcenerzeugung der Anbindung — sodass das, was der Konsument liest, und das, was die Anbindung ausgibt, nicht voneinander abweichen können.
Provider & implements
spec.capability ist erforderlich und benennt den Provider, dessen Wasm-Rendering-Plugin die Ausgabe des FeatureRecipe rendert (helm, helm-chart, compose usw.), zu den Bedingungen, die für das spec.capability eines Recipe gelten (siehe entities/recipe.md): Ein Versions-Pin wählt aus, welche Version dieses Plugins es rendert, und ist nicht Teil des Namens des FeatureRecipe — ein Manifest bildet ein FeatureRecipe, das capability: "compose:1.2.3" deklariert, als compose/<name>:<version> ab, und ein Mapping-Wert, der den Pin in den Namen schreibt, wird als fehlerhafte Rezeptreferenz (E0095) abgelehnt, bevor irgendetwas nachgeschlagen wird. Das Feld implements bindet das FeatureRecipe an seine Feature-Schnittstelle und unterstützt exakten, Major-kompatiblen Bereichs- oder versionslosen Abgleich — siehe vocabulary/inheritance-and-interface zur Semantik des Versionsabgleichs von implements.
Ausführungsbereich — spec.executionScope
Das optionale Enum spec.executionScope wählt das Dispatch-Modell für die Ressourcengenerierung. Zwei Werte werden akzeptiert; wird das Feld weggelassen, ist der Standardwert component.
component(Standard). Die Ressourcengenerierung des FeatureRecipe läuft einmal pro angebundener Komponenteninstanz. Jeder Aufruf erhält einen komponentenbezogenen Template-Kontext mit der Wurzel.context.*:.context.instance_id,.context.inject,.context.uses,.context.annotationsusw. SeinevaluesMapping:,workload:undartifacts:lesen außerdem.context.used_by, die Komponenten, derenuses-Einträge auf den Host zeigen — jede mit ihrer Identität, ihrem Socket, dem, was sie veröffentlicht, sowie dem Namespace und der Grenze, in die sie platziert ist —, was kein Template sehen kann, das der Host selbst rendert.boundary. Die Ressourcengenerierung läuft einmal pro angebundener Grenze, unabhängig davon, wie viele Komponenten im Teilbaum der Grenze die Funktion konsumieren. Jeder Aufruf erhält einen grenzbezogenen Template-Kontext mit der Wurzel.boundary.*statt.context.*.
Die oben beschriebene injectMapping-Interception ist unabhängig von executionScope immer konsumentenbezogen. Jede Komponente, die die Funktion verwendet, erhält weiterhin ihre eigene aufruferseitige Umschreibung von .context.inject. Nur der Schritt der Ressourcengenerierung (source/valuesMapping und das pipeline-Array) wird auf Grenzebene dedupliziert.
Die Templates eines grenzbezogenen FeatureRecipe laufen daher in zwei Bereichen. Sein injectMapping läuft einmal für jede Komponente, die die Anbindung erreicht, gegen den Kontext dieser Komponente — denselben, den das injectMapping eines komponentenbezogenen FeatureRecipe liest: .context.*, .attachment_name, .features sowie die eigenen .values, .infra und .locals der Anbindung. Sein .infra ist der infra:-Block der Grenzanbindung, und sein .locals ist der Block, der einmal für die Grenze ausgewertet wird. Jedes andere Template, das es schreibt — darunter seine locals:, provides:, source:, valuesMapping: und artifacts: sowie with: und when: seiner Pipeline-Schritte —, läuft einmal für die Grenze, gegen den unten beschriebenen grenzbezogenen Kontext. Jedes Template wird gegen den Bereich geprüft, in dem es läuft: Ein valuesMapping:, das .context.instance_id liest, hält den Build an, und ein injectMapping, das es liest, rendert die Identität dieser Komponente. .boundary ist im Kontext keiner Komponente gesetzt, daher hält ein injectMapping, das es liest, den Build unter Nennung der Referenz an, unabhängig vom executionScope des FeatureRecipe.
Grenzbezogener Template-Kontext
Bei executionScope: boundary werden die Templates des FeatureRecipe außer seinem injectMapping gegen eine .boundary.*-Sicht der Grenze ausgewertet, an die die Funktion angebunden ist. Die Sicht stellt bereit:
.boundary.path— der Pfad der Release-Grenze, an die die Funktion angebunden ist: die Grenznamen von außen nach innen, verbunden mit/(bridge,bridge/frontend). Er benennt die Grenze, nicht das Verzeichnis, in das ihre Ausgabe geschrieben wird; dieses legtdirectory:fest (ersetzt.context.instance_id)..boundary.assembly_path— das Verzeichnis, relativ zum Ausgabeverzeichnis des Builds, in das die eigene Ausgabe der Anbindung assembliert wird: die ausgewertetendirectory:undsubDirectory:der Grenze, also das Verzeichnis, an das der Build diese Ausgabe leitet (bridge/compose). Es entspricht demsource_assembly_pathodertarget_assembly_patheines Verbindungsendpunkts genau dann, wenn dieser Endpunkt in dieselbe assemblierte Datei gerendert wird; ein FeatureRecipe vergleicht sie daher, um eine Verbindung innerhalb der eigenen Datei von einer in einer anderen Datei zu unterscheiden..boundary.boundary_name— der im Release verfasste Name der Grenze..boundary.components— eine nach Instanz-ID geschlüsselte Map mit jeder Komponente im Teilbaum der Grenze (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges—uses:-Kanten, deren beide Endpunkte im Teilbaum dieser Grenze liegen (das compose-bridge-Muster zählt sie auf und behält die Kanten, deren beide Endpunkte in seine eigene Compose-Datei assembliert und in verschiedenen Netzwerken dieser Datei platziert sind, um seine kantenbezogene Proxy-Konfiguration abzuleiten). Jede Kante trägt die aufgelösten provides ihrer Endpunkte, die injizierten Umgebungsvariablen und die Platzierung jedes Endpunkts:source_namespaceundtarget_namespace, dieaggrega.ai/namespace-Annotation, die für diesen Endpunkt gilt — die Einstellung seines eigenen Release-Eintrags, sofern er eine hat, andernfalls die seiner Grenze;source_boundary_pathundtarget_boundary_path, der Pfad der Release-Grenze, die ihn enthält; sowiesource_assembly_pathundtarget_assembly_path, das Verzeichnis unterhalb des Ausgabeverzeichnisses des Builds, in das sein Provider ihn assembliert, zusammengesetzt aus den ausgewertetendirectory:undsubDirectory:seiner Grenze (bridge/compose). Zwei Endpunkte mit demselben Assembly-Pfad werden in eine einzige assemblierte Datei gerendert, und der Compose-Provider liest den Assembly-Pfad als Netzwerk des Endpunkts, wo kein Namespace gilt..boundary.outgoing_cross_boundary_uses_edges— Kanten, deren Quelle im Teilbaum und deren Ziel außerhalb liegt..boundary.incoming_cross_boundary_uses_edges— Kanten, deren Ziel im Teilbaum und deren Quelle außerhalb liegt (von Aggregatoren im Ingress-Stil verwendet)..boundary.cross_boundary_uses_edges— die Vereinigung der eingehenden und ausgehenden grenzüberschreitenden Kanten, wenn das FeatureRecipe die vollständige grenzüberschreitende Sicht benötigt..boundary.labels— die Vereinigung der Labels des Teilbaums unter Beibehaltung der Autorenreihenfolge..boundary.annotations— die eigenen Annotationen der Grenze zuzüglich der Kaskade..boundary.feature_attachments— jede an dieser Grenze angebundene Funktion (damit ein grenzbezogenes FR bei Bedarf seine Geschwister untersuchen kann).
Die Säule .infra eines grenzbezogenen FR wird zum infra:-Block der an die Grenze angebundenen Funktion aufgelöst (die Release-seitig verfasste physische Dimensionierung für diese Grenzanbindung). .values ist für grenzbezogene FRs immer leer: Die Regel zur Säulentrennung des Release-Schemas verbietet values: an Feature-Anbindungen auf Release-Ebene, sodass eine an eine Grenze angebundene Funktion keine Werte zum Projizieren trägt. Grenzbezogene FRs, die parameterartige Daten benötigen, sollten diese über .infra (die Authoring-Oberfläche des Operators für die Konfiguration von Grenzfunktionen) oder über .boundary.annotations (per Kaskade auflösbare String-Werte, die an der Grenze oder an einem beliebigen Vorfahren verfasst sind) konsumieren; .parameters ist nicht Teil der Sicht, und ein Template, das es liest, hält unter Nennung der Wurzeln an, die die Sicht definiert. .locals bleibt der eigene locals-Block des FR. .steps und .metadata bleiben unverändert.
Allowlist der Felder grenzbezogener Templates
Grenzbezogene FRs dürfen in jedem Template außer dem injectMapping nur auf Felder verweisen, die in der grenzbezogenen Sicht verfügbar sind. Wird ein solches Template so verfasst, dass es bei executionScope: boundary auf ein nur komponentenbezogenes Feld verweist (z. B. .context.instance_id, .context.inject, .context.uses), schlägt die Validierung des FeatureRecipe zur Parse-Zeit fehl, mit einem Fehler, der das FR, das betreffende Feld und die Felder nennt, die die grenzbezogene Sicht definiert. Die spiegelbildliche Regel gilt in der anderen Richtung: Ein komponentenbezogenes FR, das auf .boundary.*-Felder verweist, scheitert an demselben Validator. Das injectMapping wird in beiden Bereichen gegen den Kontext der Komponente geprüft, in dem es läuft; es darf daher .context.* lesen, und ein Verweis auf .boundary darin hält unter Nennung der Referenz und der Wurzeln an, die dieser Kontext definiert.
Der Validator führt denselben Durchlauf über den Template-AST aus, den auch die Allowlist für Variablen in Pfad-Templates verwendet, mit einer je Bereich unterschiedlichen Referenzmenge.
Deduplizierung und Ausgabe der Ressourcengenerierung
Bei executionScope: boundary dedupliziert der Compiler die Ressourcengenerierung anhand des Tupels (boundary_path, FR-instance). Zwei Komponenten im selben Grenzteilbaum, die beide dieselbe an die Grenze angebundene Funktion konsumieren, lösen einen einzigen FR-Aufruf aus, nicht zwei. Anbindungen derselben Funktion an verschiedenen Grenzen laufen unabhängig pro Grenze.
Ein grenzbezogenes FR erzeugt pro Tupel (boundary_path, FR-instance) eine Menge nicht intermediärer Dateien, und wo sie liegen, ergibt sich daraus, wie der Provider die Ausgabe seiner Grenze zusammenführt. Hier ist der Instanzname allein die Koordinate, während eine komponentenbezogene Anbindung zusätzlich ihre Komponente trägt: Eine grenzbezogene Funktion ist an die Grenze angebunden und nicht an eine Komponente, sodass das umschließende Grenzverzeichnis bereits alles aussagt, was ein Komponentensegment aussagen würde, und es keine Komponente zu benennen gibt.
Ein Provider, der jedes Dokument direkt in das Grenzverzeichnis schreibt, deklariert, dass sein Ziel nur die Dateien liest, die direkt in einem Verzeichnis liegen. Es gibt daher kein umschließendes Verzeichnis, in dem eine Anbindung liegen könnte, und der Instanzname wird stattdessen zu einem Dateinamenpräfix: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, neben den eigenen Dateien der Grenze. Der Instanzname wird kodiert, weil ein Dateiname kein Trennzeichen hat, auf das er zurückgreifen könnte, und er trifft an einer Zwei-Zeichen-Grenze, die keine kodierte Koordinate enthalten kann, auf den eigenen Namen der Datei — sodass zwei Anbindungen, die denselben Dateinamen erzeugen, dennoch zwei Dateien erreichen.
Ein Provider, der die Ausgabe seiner Grenze zu einer umschließenden Struktur zusammensetzt — ein Chart, das pro Beitragendem ein Chart enthält, eine Root-Konfiguration, die pro Beitragendem ein Modul enthält —, platziert jeden Beitragenden in einem eigenen Unterverzeichnis, und eine Grenzanbindung ist ein Beitragender wie jeder andere. Ihre Ausgabe liegt dann unter <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, wobei <contributors-directory> die Bezeichnung ist, die dieses Ziel dem Ort gibt, an dem seine untergeordneten Einheiten liegen. Das Unterverzeichnis trägt den Instanznamen der Anbindung, also den Namen, unter dem Sie sie im features:-Block der Grenze geschrieben haben, sodass Sie das Verzeichnis, das ein Build erzeugt, in dem wiederfinden, was Sie verfasst haben.
Intermediäre Ausgabe fließt zum Assembler der Grenze pro (Pfad, Provider), unter dem ausgewerteten Pfad des FR und unter der eigenen spec.capability des FR — das ist der Mechanismus, mit dem das Feature core/compose-bridge einen Bridge-Service neben den komponentenbezogenen Compose-Beiträgen unter demselben Assembly-Pfad zusammenführt. Solche Ausgabe wird nur als Teil der Datei geschrieben, die dort aus den Komponenten der Grenze assembliert wird; landet also keine von ihnen unter diesem Pfad — etwa weil jede Komponente durch ihr subDirectory: anderswohin geleitet wird —, hält der Build unter Nennung der Grenze, des Features, des Pfads, an den seine Ausgabe geleitet wurde, und des Providers an, statt die Ausgabe nirgendwohin zu schreiben (siehe „A boundary-level Feature’s output reaches no assembled file (Die Ausgabe eines Features auf Grenzebene erreicht keine assemblierte Datei)“ in fatal-halts.md).
Kaskadenbewusste Auflösung von provides:
Grenzbezogene FRs erzeugen pro Tupel (boundary_path, FR-instance) eine provides:-Menge, die einmal ausgewertet wird. Das provides:-Template des FR wird mit dem grenzbezogenen Template-Kontext ausgewertet (es kann also auf .boundary.components, .boundary.path, .infra verweisen, aber nicht auf konsumentenbezogene Felder und nicht auf .values). Die provides-Werte sind Konstanten in Bezug auf die Konsumenten — jeder Konsument im Teilbaum der Grenze sieht dieselben bereitgestellten Werte.
Die konsumentenseitige Auflösung der provides eines grenzbezogenen FR liest überall diese eine Auswertung. Jede Komponente, die die Anbindung erreicht, liest sie unter .features.<instance-name>.provides.<key> — in den Templates ihres eigenen Recipe und im eigenen injectMapping des FeatureRecipe, das im Kontext dieser Komponente läuft. Eine konsumierende Component, die über eine von der Anbindung getragene uses-Kante unter .context.uses.<feature-alias>.provides.<provided-name> liest, erhält dieselben Werte: Der Compiler löst sie zum provides: des grenzbezogenen FeatureRecipe für die Grenze auf, in der der Konsument liegt, indem er von der uses-Kante des Konsumenten — die die Identität der Funktionsinstanz pro Anbindung trägt — zum provides: des grenzbezogenen FR geht. Ein vorgelagerter Durchlauf wertet diese provides vor der Assemblierung der Konsumenten aus, sodass die Werte vorhanden sind, wenn die Pipe des Konsumenten aufgebaut wird.
Ein konsumentenbezogener Effekt ist eine Tabelle in provides:, die von injectMapping gelesen wird. Ein grenzbezogenes FeatureRecipe, das für jeden Konsumenten etwas ändern muss, berechnet einmal in seinem provides: aus den Verbindungen der Grenze eine nach Konsument geschlüsselte Tabelle, und sein injectMapping liest die Zeilen der aktuellen Komponente — (index .features .attachment_name).provides, geschlüsselt nach .context.instance_id — und liefert sie über die eigene Pipe des Konsumenten aus, nach der Regel, der jedes Mapping folgt (siehe Was ein Mapping umschreiben darf). Der Compiler leitet die Tabelle weiter, die das FeatureRecipe geschrieben hat, und liest nichts darin.
Das Compose-Bridge-Muster
Das compose-bridge-FeatureRecipe ist das kanonische Muster eines FR mit Boundary-Scope, und es ist Katalog-Inhalt, der mit den oben beschriebenen Mechanismen geschrieben ist: Weder der Compiler noch der Compose-Provider enthält irgendeine Logik der Bridge, sodass ein Katalog das Feature core/compose-bridge anders umsetzen kann. Ein core/compose-bridge-Feature wird an eine übergeordnete Boundary angebunden, die zwei Unter-Boundaries (z. B. services-net und data-net) mit gemeinsamem directory: enthält, die jeweils eine eigene aggrega.ai/namespace-Annotation tragen (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net), sodass jede in einem eigenen Netzwerk landet; ohne die Annotationen teilen sich beide das eine Netzwerk, das nach dem Pfad ihrer Compose-Datei benannt ist, und erreichen einander ohne Bridge. Sein executionScope: boundary führt das FR einmal pro Anbindung an die übergeordnete Boundary aus.
Sein provides: berechnet die Bridge-Tabelle, einmal. Aus .boundary.internal_uses_edges behält es die Kanten, deren beide Endpunkte in seine eigene Compose-Datei assembliert werden — source_assembly_path und target_assembly_path beide gleich .boundary.assembly_path — und in verschiedenen Netzwerken dieser Datei liegen, wobei das Netzwerk eines Endpunkts sein aggrega.ai/namespace ist, andernfalls sein Assembly-Pfad. Eine Kante zwischen zwei Compose-Dateien wird nicht überbrückt, und ihr Consumer behält den eigenen Namen des Ziels. Jede überbrückte Kante erhält einen Listen-Port — den eigenen Port des Ziels oder, wo eine frühere Kante bereits auf ihm lauscht, den ersten freien Port ab dem portBase der Anbindung (Standard 10000) — und einen Upstream, den veröffentlichten Host des Ziels (das provides-Feld, das das providesField der Anbindung benennt, Standard host) und seinen port; der Upstream wird aus der Kante abgeleitet, nie von Hand geschrieben. Aus derselben Tabelle berechnet es die Umschreibung jedes Consumers: Eine Variable, die die Kante aus dem Host-Feld liefert, wird zu aggrega-gw:<listen port>, oder zu aggrega-gw, wo dieselbe Kante auch eine Variable aus port liefert, die dann zum Listen-Port wird.
Sein injectMapping liefert die Zeilen jedes Consumers. Im Kontext jedes Consumers ausgeführt, liest es die Zeilen dieses Consumers aus der Tabelle unter .features.<attachment>.provides und liefert sie über die Werte hinweg, die die eigene Verbindung des Consumers geliefert hat (z. B. DB_HOST), was eine Interception ist; ein Consumer ohne Zeile erhält nichts. Wo ein anderes an den Consumer angebundenes Feature diesen Schlüssel geliefert hat — über seinen inject:-Block oder sein injectMapping —, hält der Build an und nennt beide Features, statt diese Lieferung zu ersetzen (siehe „Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Zwei angebundene Features liefern denselben Schlüssel, das spätere über das injectMapping seines FeatureRecipe)“ in fatal-halts.md). Das listen des Gateways und die Umschreibung des Consumers werden aus einer Tabelle gelesen, sodass sie konstruktionsbedingt pro Kante übereinstimmen, einschließlich der durch portBase neu zugewiesenen Kollisionen.
Sein valuesMapping schreibt das Gateway. Das eigene Compose-Fragment des FeatureRecipe deklariert den Service aggrega-gw. Wo etwas überbrückt wird, fügt sein valuesMapping pro überbrückter Kante einen nginx-stream-server-Block hinzu (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, unter einer resolver-Direktive, sodass jeder Upstream zum Verbindungszeitpunkt aufgelöst wird statt einmal beim Start; das $ in diesen Variablen wird als $$ geschrieben, sodass die $-Interpolation von Docker Compose ein literales $ für nginx übrig lässt), geliefert als eingehängte Compose-Konfiguration — ein configs:-Eintrag auf oberster Ebene mit Inline-content:, referenziert von aggrega-gw und eingehängt unter /etc/nginx/nginx.conf (sodass nginx sie ohne ein vom Autor geschriebenes command: lädt). Inline-configs.content erfordert Docker Compose ≥ 2.23.1. Es nennt außerdem jeden überbrückten Endpunkt unter dem x-aggrega-networks-of des Gateways, das der Compose-Provider in die Netzwerke auflöst, in denen diese Endpunkte platziert sind, sodass das Gateway jedem Netzwerk beitritt, das seine überbrückten Kanten umspannen (dem Netzwerk des Consumers und dem des Ziels) — zur Laufzeit kann der Consumer aggrega-gw:<port> erreichen und das Gateway per proxy_pass an das Ziel weiterleiten. Wo nichts überbrückt wird, wird das vom Fragment deklarierte Gateway trotzdem gerendert, im Leerlauf: keine Konfiguration, kein zusätzliches Netzwerk und keine Umschreibung.
Der Compose-Assembler pro (Pfad, Provider) führt das Gateway mit den komponentenweisen Beiträgern am selben ausgewerteten Pfad zusammen: eine docker-compose.yaml, die jede Komponente plus das Bridge-Gateway enthält. Wo keine der Komponenten der Boundary in die Datei des Gateways assembliert wird, hält der Build an, statt das Gateway nirgendwohin zu schreiben. Der Upstream ist ein deterministischer Compose-Service-Pointer zur Compile-Zeit; das Laufzeit-DNS von Compose löst ihn auf (keine Laufzeitauflösung zur Compile-Zeit).
Rendern nach den Aufrufern — spec.readsCallerRenderFacts
Das optionale spec.readsCallerRenderFacts (Boolean, Standard false) deklariert, dass die Templates dieses FeatureRecipe lesen, was die Komponenten gerendert haben, die sich mit seinem Host verbinden: die Render-Fakten, die der Provider jedes dieser Aufrufer über die von ihm ausgegebene Ausgabe meldet. Was ein Provider meldet und unter welchen Namen, ist der eigene Vertrag dieses Providers; Fakten darüber melden, was ein Guest ausgegeben hat beschreibt die Fakten, die ein Provider melden kann.
Wann eine solche Anbindung gerendert wird. Der Build rendert seine Komponenten nacheinander in einer festen Reihenfolge, und eine Anbindung wird normalerweise direkt nach der Komponente gerendert, an die sie angebunden ist. Eine Komponente, die sich mit dem Host verbindet und in dieser Reihenfolge später kommt, ist zu diesem Zeitpunkt noch nicht gerendert, sodass nichts, was sie ausgegeben hat, zum Lesen existiert. Eine Anbindung, deren FeatureRecipe readsCallerRenderFacts: true setzt, wird stattdessen gerendert, sobald jede Komponente im Build gerendert ist, zusammen mit jeder Anbindung, die weder diesen Schlüssel noch readsTargetRenderFacts setzt — sodass das Rendern jedes Aufrufers abgeschlossen ist, bevor die Anbindung ausgewertet wird. Ihre Ausgabe landet dort, wo sie gelandet wäre, und unter denselben Namen; der Schlüssel ändert, wann die Anbindung rendert, nicht was sie rendert. Aus dem späteren Rendern folgt eine Reihenfolge: Wo das FeatureRecipe eine pipeline trägt, die die Dokumente seiner Host-Komponente umschreibt, und der Provider des Hosts einzelne Dokumente schreibt, laufen diese Schritte nach den Pipelines der anderen Anbindungen des Hosts statt in deren Anbindungsreihenfolge.
Was es liest. Ist der Schlüssel gesetzt, trägt jeder Eintrag von .context.used_by .render_facts: die Render-Fakten des Aufrufers, nach Faktenname geschlüsselt. Jeder Render-Fakt ist eine Liste, sodass ein Template immer mit range darüber iteriert — auch wenn sie nur einen Eintrag enthält. Ihre Einträge können aus dem eigenen Rendern des Aufrufers und aus dem Rendern der an den Aufrufer angebundenen Features stammen: Die Listen, die ein Name von jedem erhält, werden zu einer zusammengeführt, zuerst die Aufrufe des eigenen Providers des Aufrufers, dann jedes seiner Features in der Reihenfolge, in der sie gerendert wurden. Ein Feature des Aufrufers, das selbst den Schlüssel setzt, wird ebenfalls nach jeder Komponente gerendert, sodass das, was es gemeldet hat, nicht darunter ist. Ein Aufrufer, dessen Provider nichts melden, trägt ein leeres .render_facts, sodass ein Name, den niemand gemeldet hat, als nichts gelesen wird:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Welche Faktennamen es gibt und was jeder Eintrag enthält, ist der dokumentierte Vertrag des Providers des Aufrufers — die des helm-Providers sind zum Beispiel seine Render-Fakten, die die Labels der von ihm gerenderten Pods benennen. Die Fakten der Aufrufer liegen auf den Verbindungen, die valuesMapping:, workload: und artifacts: des FeatureRecipe lesen; with: und when: eines pipeline:-Schritts sehen die Komponenten, die sich mit dem Host verbinden, überhaupt nicht, sodass ein Schritt nur die eigenen Fakten des Hosts liest. Jedes an eine Komponente angebundene FeatureRecipe — ob es den Schlüssel setzt oder nicht — liest die eigenen Fakten der Komponente unter .context.render_facts in derselben Form; der Template-Kontext beschreibt beides.
Deklarieren Sie ihn immer, wenn ein Template die Fakten liest. Ein inline in einem FeatureRecipe, das den Schlüssel nicht setzt, geschriebenes Template — sein valuesMapping:, sein workload: oder ein artifacts:-Eintrag —, das render_facts unterhalb von .context.used_by liest, hält den Build an, bevor irgendetwas gerendert wird, und nennt die Referenz und das Feld, in dem sie geschrieben wurde (siehe „A template reads its callers’ render facts without declaring it (Ein Template liest die Render-Fakten seiner Aufrufer, ohne dies zu deklarieren)“ in fatal-halts.md). Die Prüfung liest das Template so, wie es geschrieben ist, sieht also keine Referenz, die erst während der Ausführung des Templates gebildet wird, und keine, die in aus einer Datei oder Bibliothek importiertem Inhalt geschrieben ist — und ein Template, das ein Feld namens render_facts von einer anderen Liste neben .context.used_by liest oder die eigenen Fakten des Hosts als .render_facts innerhalb von {{ with .context }} daneben liest, wird so behandelt, als läse es die Fakten der Aufrufer; schreiben Sie die eigenen des Hosts vollständig als .context.render_facts. Der Schlüssel, nicht die Prüfung, entscheidet, wann die Anbindung rendert; setzen Sie ihn daher auf jedem FeatureRecipe, dessen Templates die Render-Fakten ihrer Aufrufer lesen, auf welchem Weg auch immer sie sie erreichen; ihn zu setzen kostet nichts außer dem späteren Rendern.
Ein Pipeline-Schritt liest nur die eigenen Fakten seines Hosts. Ein Schritt kann die eigenen Dokumente der Host-Komponente umschreiben, und die eigene Ausgabe einer Komponente bleibt gleich, wer auch immer sich mit ihr verbindet, sodass with: und when: eines Schritts nie die Komponenten sehen, die sich mit dem Host verbinden — ob das FeatureRecipe den Schlüssel setzt oder nicht, der entscheidet, wann die Anbindung rendert, und nichts darüber, was ein Schritt sieht. Ein inline geschriebenes with: oder when: eines Schritts, das render_facts unterhalb von .context.used_by liest, hält daher den Build an, bevor irgendetwas gerendert wird, mit dem Kurzcode E0326, und nennt die Referenz und das Feld des Schritts — statt einen leeren Wert zu rendern. Lesen Sie die eigenen Fakten des Hosts in einem Schritt unter .context.render_facts, vollständig ausgeschrieben, und die Fakten der Aufrufer in valuesMapping:, workload: oder artifacts: des FeatureRecipe. Diese Prüfung liest das Template so, wie es geschrieben ist, mit denselben Grenzen wie die obige.
Geltungsbereich. Der Schlüssel gilt für ein FeatureRecipe, das einmal pro Komponente rendert — executionScope: component, der Standard. Ein FeatureRecipe, das executionScope: boundary deklariert, rendert dort, wo es immer rendert, ob es den Schlüssel setzt oder nicht, und die Templates, die seine Ressourcen erzeugen, lesen .boundary statt .context.
Rendern nach den Zielen — spec.readsTargetRenderFacts
Das optionale spec.readsTargetRenderFacts (Boolean, Standard false) deklariert, dass die Templates dieses FeatureRecipe lesen, was die Komponenten gerendert haben, mit denen sein Host verdrahtet ist: die Render-Fakten, die der Provider jedes dieser Ziele über die von ihm ausgegebene Ausgabe meldet. Es liest das andere Ende einer Verbindung als readsCallerRenderFacts — die Komponenten, auf die die uses-Einträge des Hosts zeigen, statt der Komponenten, deren uses-Einträge auf den Host zeigen —, und alles, was die Fakten selbst betrifft, liest sich gleich.
Jeder der beiden Schlüssel lässt die Anbindung nach jeder Komponente rendern. Eine Anbindung, deren FeatureRecipe readsCallerRenderFacts: true, readsTargetRenderFacts: true oder beides setzt, rendert, sobald jede Komponente im Build gerendert ist, wie der Abschnitt oben beschreibt — es gibt ein einziges solches späteres Rendern, und was es dafür bedeutet, wo die Ausgabe der Anbindung landet und in welcher Reihenfolge ihre Pipeline-Schritte laufen, ist dasselbe, welcher Schlüssel die Anbindung auch dorthin verschoben hat. Die beiden Schlüssel unterscheiden sich nur darin, welche Verbindungen Fakten im Kontext der Anbindung tragen: Ein Ziel, das in der Reihenfolge des Builds nach dem Host kommt, ist bis dahin gerendert, sodass das, was es ausgegeben hat, zum Lesen bereitsteht.
Was es liest. Ist der Schlüssel gesetzt, trägt jeder Eintrag von .context.uses .render_facts: die Render-Fakten des Ziels, nach Faktenname geschlüsselt, in der Form, die der Eintrag eines Aufrufers trägt. Jeder Render-Fakt ist eine Liste, sodass ein Template immer mit range darüber iteriert. Ihre Einträge können aus dem eigenen Rendern des Ziels und aus dem Rendern der an das Ziel angebundenen Features stammen, zuerst die Aufrufe des eigenen Providers des Ziels, dann jedes seiner Features in der Reihenfolge, in der sie gerendert wurden; ein Feature des Ziels, das selbst nach jeder Komponente rendert, ist nicht darunter. Ein Ziel, dessen Provider nichts melden, trägt ein leeres .render_facts. Ein Template liest die Fakten einer Verbindung unter ihrem Alias, .context.uses.<alias>.render_facts.<name>, oder die jeder Verbindung der Reihe nach:
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Ein FeatureRecipe, das den Schlüssel nicht setzt, sieht auf keiner Verbindung ein .render_facts, was auch immer es sonst setzt. Welche Faktennamen es gibt, ist der dokumentierte Vertrag des Providers jedes Ziels — die des helm-Providers sind seine Render-Fakten, die die Labels, Controller-Selektoren und Container-Ports der von ihm gerenderten Pods benennen und damit das, was eine Egress-Policy braucht, um genau die Pods auszuwählen, die ihr Host erreichen darf.
Deklarieren Sie ihn immer, wenn ein Template die Fakten liest. Ein inline in einem FeatureRecipe, das den Schlüssel nicht setzt, geschriebenes Template — sein valuesMapping:, sein workload: oder ein artifacts:-Eintrag —, das render_facts unterhalb von .context.uses liest, hält den Build an, bevor irgendetwas gerendert wird, mit dem Kurzcode E0347, und nennt die Referenz und das Feld, in dem sie geschrieben wurde (siehe „A template reads its targets’ render facts without declaring it (Ein Template liest die Render-Fakten seiner Ziele, ohne dies zu deklarieren)“ in fatal-halts.md). Das Setzen von readsCallerRenderFacts hebt dies nicht auf. Die Prüfung liest das Template so, wie es geschrieben ist, mit den Grenzen der Prüfung für die Aufrufer: Sie sieht keine Referenz, die erst während der Ausführung des Templates gebildet wird, und keine, die in aus einer Datei oder Bibliothek importiertem Inhalt geschrieben ist — und ein Template, das .context.uses überhaupt liest und außerdem ein Feld namens render_facts von einem anderen Wert liest, einschließlich des Eintrags eines Aufrufers innerhalb von {{ range .context.used_by }}, wird so behandelt, als läse es die Fakten seiner Ziele. Ein Template, das die Fakten beider Enden liest, setzt beide Schlüssel.
Ein Pipeline-Schritt liest nur die eigenen Fakten seines Hosts. with: und when: eines Schritts lesen die Verbindungen, die der Host herstellt, so wie das eigene Recipe des Hosts sie liest, und nie die Render-Fakten ihrer Ziele — ob das FeatureRecipe den Schlüssel setzt oder nicht. Ein Schritt kann die eigenen Dokumente der Host-Komponente umschreiben, und das eigene Rendern des Hosts liest, was seine Ziele veröffentlichen, nie, was sie ausgegeben haben. Ein inline geschriebenes with: oder when: eines Schritts, das render_facts unterhalb von .context.uses liest, hält daher den Build an, bevor irgendetwas gerendert wird, mit dem Kurzcode E0348, und nennt die Referenz und das Feld des Schritts — statt einen leeren Wert zu rendern. Lesen Sie die Fakten der Ziele in valuesMapping:, workload: oder artifacts: des FeatureRecipe.
Geltungsbereich. Wie beim Schlüssel für die Aufrufer: Er gilt für ein FeatureRecipe, das einmal pro Komponente rendert. Ein FeatureRecipe, das executionScope: boundary deklariert, rendert dort, wo es immer rendert, ob es den Schlüssel setzt oder nicht, und die Verbindungen, die es unter .boundary liest, tragen keine Render-Fakten.
Der Block locals:
FeatureRecipe.spec.locals: ist eine optionale Map benannter Go-Template-Strings, deren gerenderte Ausgabe jedem anderen Template innerhalb desselben FeatureRecipe eine Map .locals.* bereitstellt. Sie ist das FeatureRecipe-private Gegenstück zu locals: eines Recipe — ein Ort, an dem abgeleitete Strings einmal berechnet und von injectMapping, valuesMapping, pipeline[].with und provides aus referenziert werden, ohne sie neu zu berechnen. Die assertions: des FeatureRecipe lesen sie nicht: Die .locals einer Assertion sind die des Recipe der Host-Komponente, wie assertions-block.md festhält. Die gerenderte Ausgabe jedes Eintrags wird ohne führenden und nachgestellten Leerraum gespeichert. Der Block ist eine Map, kein einzelner Template-Body; ein Skalar an dieser Stelle wird vom Schema abgelehnt.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* gilt pro Aufruf: Jeder FR-Aufruf löst seinen eigenen Block locals: auf, und das Ergebnis ist nur für die nachgelagerten Templates dieses Aufrufs sichtbar. Der Block wird aufgelöst, bevor die anderen Templates der Authoring-Oberfläche des FR ausgewertet werden, sodass jedes von ihnen aufgelöste Werte sieht.
Jeder Eintrag wird gegen einen in sich geschlossenen Kontext ausgewertet: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra und die bereits aufgelösten Einträge desselben Blocks. Das ist bewusst enger als der Kontext, den die anderen Templates des FR lesen — ein Eintrag in locals: kann .context.annotations, .context.inject, .context.uses oder .provides nicht erreichen, und ein Verweis auf eines davon bricht den Build ab und nennt den Verweis. Abgeleitete Werte, die diese Säulen benötigen, gehören in das Template, das sie liest, nicht in locals:.
Die Namen in diesem Kontext beantworten unterschiedliche Fragen, und ein Eintrag in locals: liest sie genau so, wie es die anderen Templates des FeatureRecipe tun:
.context.instance_idist die Host-Komponente, für die die Anbindung aufgelöst wird. Es bezeichnet die Host-Komponente auf jeder Template-Oberfläche, die der Compiler auswertet, sodass derselbe Verweis gleich gelesen wird, unabhängig davon, in welcher Entität Sie den Block schreiben..context.rendered_nameist der Name der Host-Komponente, wie ihr eigener Provider ihn meldet — unterhelmder Release-Name, also die Identität des Hosts, geschrieben in dem Alphabet, das ein Kubernetes-Name zulässt. Er ist nur vorhanden, wo der Provider des Hosts einen Namen meldet, und ihn auf einem Host zu lesen, dessen Provider keinen meldet, bricht den Build ab..attachment_nameist die Anbindungsinstanz, die aufgelöst wird — der Slot, den sie imfeaturesSchemader besitzenden Entität belegt, oder der freie Name, den Sie ihr gegeben haben.
Ein Eintrag in locals:, der einen Namen für eine emittierte Ressource ableitet, setzt also Host und Anbindung zusammen, genau wie es ein Template in artifacts: täte:
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetWo der Name einer sein muss, den die Plattform akzeptiert, und der Provider des Hosts einen meldet, setzen Sie ihn stattdessen aus .context.rendered_name zusammen: Für einen Host namens my_api unter helm und eine Anbindung scrape ergibt {{ .context.rendered_name }}-{{ .attachment_name }} den Wert my-zuapi-scrape, während die Identität my_api-scrape ergäbe, was ein Kubernetes-Name ablehnt. Siehe Benennung einer gerenderten Ressource.
.values und .infra in einem Eintrag in locals: sind die eigenen Säulen der Anbindung, verfasst in der Deklaration der Anbindung — nicht die der Host-Komponente.
Die Reihenfolge der Einträge ist maßgeblich
Einträge werden in der Reihenfolge aufgelöst, in der sie geschrieben sind, und ein Eintrag darf einen darüber definierten Geschwistereintrag lesen und erhält dessen aufgelösten Wert:
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveDie Verkettung verläuft nur nach unten. Wo ein Eintrag einen anderen liest, entscheidet die Reihenfolge der Einträge, ob der Build gelingt: Verschieben Sie region_prefix unter bucket, und der Build bricht ab. Der Compiler ordnet den Block nie um, damit ein Verweis aufgelöst werden kann; das Umordnen eines Blocks locals: ist daher eine Verhaltensänderung, keine kosmetische.
Ein Verweis auf einen Eintrag, den der Block später definiert, bricht den Build ab und nennt den Reihenfolgefehler (verschieben Sie die Definition über ihren Leser); ein Verweis auf einen Schlüssel, den der Block überhaupt nicht deklariert, bricht ab und nennt den Schlüssel (korrigieren Sie die Schreibweise). Die Prüfung folgt einem Alias des Blocks: Ein Schlüssel, der über den Punkt erreicht wird, den ein Body with .locals neu bindet, oder über eine an .locals gebundene Variable, bricht unter genau denselben Bedingungen ab wie die direkte Schreibweise, und ebenso ein Schlüssel, der in Klammern vom Block gelesen wird — {{ (.locals).nope }} oder {{ ($.locals).nope }}. Eine Schreibweise entgeht ihr: ein Schlüssel, der über einen Aufruf erreicht wird, dessen Ergebnis der Template-Text nicht benennen kann — {{ index .locals "nope" }} oder {{ (default dict .locals).nope }}. Ein Feld, das vom Ergebnis eines solchen Aufrufs gelesen wird, bricht nicht ab und rendert den literalen Text <no value>; das Lesen über index bricht ab und nennt den Schlüssel, weil index auf jeder Template-Oberfläche abbricht, wenn die gelesene Map den Schlüssel nicht enthält — siehe errors/fatal-halts.md „A template indexes a map with a key the map does not hold (Ein Template indiziert eine Map mit einem Schlüssel, den die Map nicht enthält)“. provides: liest den vollständig aufgelösten Block, weil die locals dieses FeatureRecipe vor seinen provides aufgelöst werden; ein Template in provides:, das einen nicht deklarierten Schlüssel nennt, bricht ab. Dies sind dieselben Regeln, denen der Block locals: eines Recipe folgt — siehe entities/recipe.md „Der Block locals:“.
Verhalten je Geltungsbereich. Für executionScope: component (Standard) wird locals: pro angebundener Komponenteninstanz gegen den oben beschriebenen in sich geschlossenen Kontext ausgewertet. Für executionScope: boundary wird locals: pro Grenz-Anbindung gegen die Grenz-Ansicht mit Wurzel .boundary.* ausgewertet; die komponentenbezogenen Felder (.context.instance_id, .context.inject, .context.uses) und .attachment_name sind nicht verfügbar, weil das FeatureRecipe einmal für die Grenze statt einmal pro Komponente läuft. Die Allowlist der Template-Felder im Grenz-Geltungsbereich gilt für locals: auf dieselbe Weise wie für die anderen Templates der Authoring-Oberfläche des FR. Das injectMapping, das für jede Komponente läuft, die die Anbindung erreicht, liest diese eine Grenz-Auswertung als sein .locals. Der Auswertungsvertrag — Autorenreihenfolge, Geschwisterzugriffe nur nach unten, die beiden Abbrüche — ist in beiden Geltungsbereichen identisch; nur die Form des umgebenden Kontexts unterscheidet sich.
Abgrenzung zu Overlays von injectMapping und Mappings von pipeline[].with. locals: erzeugt eine im Kontext sichtbare Map für nachgelagerte Templates; es trägt keine Ausgabe bei. injectMapping schreibt in die Pipe .context.inject des Konsumenten (aufruferseitige Mutation). pipeline[].with liefert die Nutzlast args des Wasm-Plugins. Die drei Oberflächen sind orthogonal — ein FeatureRecipe verwendet routinemäßig alle drei zusammen, wobei locals: die gemeinsamen abgeleiteten Strings trägt, auf die die anderen beiden verweisen.
Der Block assertions:
FeatureRecipe.spec.assertions: ist eine optionale Map benannter Regeln, die Implementierungsinvarianten des FeatureRecipe ausdrücken — feldübergreifende Regeln, die angesichts der konkreten Wasm-Plugin-Pipeline, des Charts oder des Mechanismus gelten, auf dem das FeatureRecipe aufbaut. Jeder Schlüssel ist ein Regelbezeichner, der in der Fehlermeldung erscheint; jeder Wert ist ein Go-Template-Body. Wie Recipe-Assertions sind FeatureRecipe-Assertions Eigenschaften der konkreten Implementierung; die Vertragsregeln auf Feature-Ebene gelten unabhängig davon in einer früheren Pipeline-Phase.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}Die obige Regel ist spezifisch für das Plugin aws-secrets-manager 1.x; sie gilt nicht, wenn ein anderes FeatureRecipe core/referenced-secret gebunden wird. Die Vertragsregeln auf Feature-Ebene aus der Feature-Definition gelten weiterhin daneben.
FeatureRecipe-Assertions werden nach der FeatureRecipe-Bindung und vor der Ressourcengenerierung ausgewertet. Der Template-Kontext für FRs im Komponenten-Geltungsbereich entspricht dem Kontext der Recipe-Assertions (Felder der Entitätsinstanz plus .provides, .locals, .recipe.metadata, .recipe.source); für FRs im Grenz-Geltungsbereich (executionScope: boundary) werden Assertions gegen die Grenz-Ansicht ausgewertet (Felder .boundary.* verfügbar; komponentenbezogene Felder nicht). Die vollständige Authoring-Grammatik und ausgearbeitete Beispiele finden Sie unter templates/assertions-block.md.
Das Feld omits: — gerenderte Dokumente aus einer Quelle auslassen
Die meisten FeatureRecipes benötigen dies nie. Es ist für ein FeatureRecipe gedacht, dessen source: ein Chart ist, das Sie unverändert übernehmen — meist eines, das aus einer Registry abgerufen wird —, und das ein Dokument rendert, das die Anbindung nicht emittieren darf: ein Secret, das das Chart bei jedem Rendern neu erzeugt, oder ein Objekt, das die Host-Komponente oder der Betreiber bereits bereitstellt. omits: lässt ein solches Dokument aus dem aus, was das FeatureRecipe erzeugt — oder, bei einer Compose-Datei, die das FeatureRecipe als Quelle nutzt, einen Service, ein Volume oder eine Config, die die Anbindung nicht beitragen darf, und bei einem CloudFormation-Template, das es als Quelle nutzt, eine Ressource.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsDer Schlüssel wird auf einem Recipe identisch verfasst, und Recipe → Das Feld omits: ist seine vollständige Referenz: was jedes Eintragsfeld auswählt, dass when: zuerst ausgewertet wird und ein falsches den Eintrag verwirft, dass jeder zutreffende Eintrag etwas auslassen muss, sonst bricht der Build ab und nennt ihn, dass die Quelle weiterhin vollständig gerendert und nur ihre Ausgabe gefiltert wird, und welche Provider den Schlüssel beachten. Bei einem FeatureRecipe unterscheidet sich nur, wo die Templates ausgewertet werden:
- Die Templates jedes Eintrags werden gegen den Kontext ausgewertet, gegen den das
valuesMapping:dieses FeatureRecipe ausgewertet wird, in dem Geltungsbereich, den seinexecutionScopeauswählt. Die Einträge eines FeatureRecipe im Komponenten-Geltungsbereich werden einmal pro Anbindung ausgewertet, gegen.valuesund.infradieser Anbindung; die eines FeatureRecipe im Grenz-Geltungsbereich einmal pro Grenze, gegen die Grenz-Ansicht und das.infrader Grenz-Anbindung. Die Regeln dazu, was die Templates einer Anbindung lesen dürfen, gelten für die Einträge so, wie sie für ihrvaluesMapping:gelten. - Gefiltert wird nur, was die eigene
source:dieses FeatureRecipe rendert. Seinworkload:und seineartifacts:nicht, und auch nicht die Ausgabe der Host-Komponente: Die Einträge einer Anbindung erreichen ihr eigenes Chart, ihre eigene Compose-Datei oder ihr eigenes CloudFormation-Template und nichts anderes — ein Compose-Service, den der Host unter demselben Schlüssel in derdocker-compose.yamldeklariert, in die beide zusammengeführt werden, bleibt unberührt, ebenso eine Ressource, die der Host unter derselben logischen ID in dem Stack deklariert, in den beide zusammengeführt werden. Um ein Dokument zu ändern, das der Host rendert, deklariert das Recipe des Hosts den Eintrag, oder ein Schritt inpipeline:patcht es.
Ein Abbruch bei einem Eintrag nennt den Knoten, den Provider, dieses FeatureRecipe und die Position des Eintrags in seiner Liste omits:; bei einem FeatureRecipe im Grenz-Geltungsbereich nennt die Zeile über der Meldung die Anbindung und ihre Grenze.
Ein ausgearbeitetes Beispiel für den Schlüssel, verfasst auf einem Recipe — das generierte Secret eines abgerufenen Charts ausgelassen, sowie die Abbrüche ohne den Eintrag und bei einem Eintrag, der nichts trifft —, finden Sie unter ai-gateway-own-webhook-certificate.