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

Vertrag des Template-Kontexts

Diese Seite dokumentiert die Laufzeitsicht, die der Compiler in die Go-Templates von Recipe und FeatureRecipe injiziert: die Form des Template-Kontexts, die Verfügbarkeit pro Feld entlang der Kompilierungs-Pipeline und den kanonischen Vertrag, den fortgeschrittene Autoren beim Schreiben von Templates benötigen, die komponentenübergreifenden Zustand konsumieren. Die Verfügbarkeit pro Template-Stelle (welche Felder an welcher Auswertungsstelle vorhanden sind) steht in expansion-matrix.md; diese Seite dokumentiert die Formen der Felder und ihre Semantik.

Übersicht

Der Compiler stellt während des Renderings pro Knoten einen Template-Kontext zusammen und injiziert ihn in jedes Go-Template, das der Renderer für diesen Knoten auswertet. Der Kontext existiert nur im Speicher — er wird nie auf die Festplatte geschrieben und überquert die Wasm-ABI nie als einzelne Nutzlast. Jede Template-Stelle erhält eine Sicht auf dasselbe Kontextobjekt; einige Felder werden spät befüllt (.workload kommt bei der Workload-Synthese an; .source bei der Quellauflösung; .steps wird durch die Ausführung von pipeline: befüllt, sobald jeder Schritt abgeschlossen ist, siehe Status der Sprache → Phasen der Kompilierungs-Pipeline).

Das Schema für die Laufzeitform ist template-context-v1beta1.schema.json (wird mit der Schema-Distribution von Aggrega ausgeliefert).

Felder oberster Ebene

Die Felder oberster Ebene liegen an der Wurzel des Template-Kontexts — der Zugriff erfolgt innerhalb eines Templates als .field.

  • .values (Map). Vom Entwickler verfasste kognitive Nutzlast aus dem Aggregate. Werte pro Komponente fließen in diesem Feld bis zum gerenderten Recipe durch. Validiert durch das schema: des Katalogs (die JSON-Schema-2020-12-Deklaration der Component oder des Feature) bei der Auflösung. Wenn die geschriebene Null / Leere / Falschheit eines Feldes semantisch vom Fehlen des Feldes verschieden ist, verwenden Sie optional (siehe sprig-functions.md) statt default.
  • .infra (Map). Von Ops verfasste physische Dimensionierung aus dem Release. Validiert durch das schema: des Katalogs (die JSON-Schema-2020-12-Deklaration der Component oder des Feature) bei der Auflösung. Es gilt derselbe Hinweis zu optional-vs-default wie für .values — bevorzugen Sie optional, wenn eine geschriebene Null oder ein geschriebenes Falsch eine legitime Absicht ist (Scale-to-Zero, keine Wiederholungen, ausgeschaltetes Feature-Flag).
  • .locals (Map mit Zeichenkettenwerten). Recipe-privater Zustand — Namen, die im Block locals: des Recipe deklariert, in der Locals-Präambel aufgelöst und bei der Quellauflösung auf diese Säule veröffentlicht werden. Einträge werden in Autorenreihenfolge aufgelöst, und ein Eintrag darf einen darüber definierten Geschwistereintrag lesen, daher ist die Reihenfolge überall tragend, wo ein Eintrag einen anderen liest. Nur innerhalb der eigenen Templates des Recipe zugänglich; nie für Aufrufer sichtbar.
  • .provides (Map mit Zeichenkettenwerten). Die öffentlichen Ausgabezeichenketten des Recipe — der Vertrag, gegen den die Blöcke inject: der Aufrufer ihre Referenzen from: auflösen. Befüllt bei der Auswertung von provides.
  • .features (Map von Anbindungen). Iteriert die an diese Component angebundenen Features (Aggregate-Ebene + Subsystem-Ebene + Release-Ebene + durch Manifest-Annotationen gesteuert, gemäß dem 5-stufigen Zwiebelmodell), mit dem Instanznamen als Schlüssel, den der Autor der Anbindung gegeben hat. Jeder Eintrag trägt dieselben Felder — siehe die Form der Anbindung unten. Eine Anbindung, die auf einer der Verbindungen der Component geschrieben ist, gehört nicht dazu: Sie wird unter dieser Verbindung gelesen, unter .context.uses.<alias>.features.<slot>, sodass ein Template, das über .features iteriert, nur die eigenen Anbindungen der Component antrifft.
  • .metadata (Struct). Release-Identität für deterministische Benennung: release_name, release_version, environment, aggregate_name. Bei jedem Rendering befüllt; die Werte stammen aus dem Block metadata: des Release.
  • .source. Das source: des Recipe, aufgelöst durch die Template-Auswertung der Quellauflösung. nil für Recipes ohne Quelle; nil, bevor die Quellauflösung läuft. In den Templates eines FeatureRecipe ist es das eigene source: dieses FeatureRecipe, nie das der Host-Komponente — siehe Oberfläche des FeatureRecipe einer Anbindung.
  • .workload. Das geparste Workload-Objekt, befüllt, sobald das gerenderte Dokument workload: dekodiert wurde und die Validierung bestanden hat, die es absichert: das Workload-Schema, das featuresSchema der Component für jede Anbindung, die ihre Container deklarieren, und die Auflösbarkeit dessen, worauf jede Anbindung verweist. nil für nicht synthetisierte Recipes; nil, bevor die Workload-Synthese läuft.
  • .steps (Map der Schrittausgaben). Befüllt durch die Ausführung von pipeline:, während Wasm-Plugins laufen, und stellt die zurückgegebenen Ausgaben eines abgeschlossenen Schritts nachfolgenden Schritten über .steps.<id>.outputs bereit. Ein Schritt liest die Ausgaben eines vorangehenden Schritts aus seinem eigenen Template with; die outputs eines Schritts werden nur für Schritte sichtbar, die nach ihm deklariert sind. Leer, wenn der Knoten keine Pipeline deklariert, und bevor der erste Schritt des Knotens abgeschlossen ist.

Ein Feld oberster Ebene, das für diesen Knoten nichts enthält — .workload bei einem Recipe, das keines synthetisiert, .source bei einem Recipe ohne Quelle, .features bei einer Component ohne Anbindungen —, wird in einem Value-Template als leer gelesen, genau wie ein nicht gesetzter Schlüssel unter .values: {{ .workload }} rendert nichts, ein default darüber liefert seinen Fallback, und ein if oder with darüber nimmt seinen False-Zweig. Ein range darüber iteriert nichts. Ein Lesezugriff darunter — {{ .workload.containers }} — bricht trotzdem ab, weil es nichts gibt, in das abgestiegen werden kann. Und ein Template, das ein solches Feld sowohl dort ausgibt, wo es immer läuft — außerhalb jedes if, with und range —, als auch darüber iteriert, bricht ab und nennt das Feld, wie bei jedem Pfad, der nichts enthält und auf beide Weisen gelesen wird, weil kein einzelner Wert als nichts ausgegeben wird und als nichts iteriert: siehe A template reads and iterates a path that holds nothing (Ein Template liest und iteriert einen Pfad, der nichts enthält).

Die Form der Anbindung

.features.<name> und .features.<slot> haben dieselbe Form — eine Anbindung, auf eine einzige Weise gelesen:

  • .type (Zeichenkette). Die Katalog-URI für das angebundene Feature.
  • .resolved_version (Zeichenkette). Die Version, in der das angebundene Feature nach der Manifest-Auflösung vorliegt — die Version, die für diesen Build tatsächlich gebunden ist, statt eines auf der konsumierenden Seite wiederholten Pins. Spiegelt .context.uses.<alias>.resolved_version. Leer, wenn der type der Anbindung zu keiner Katalog-Entität aufgelöst wird.
  • .labels (Map mit Zeichenkettenwerten). Die Katalog-Labels für das angebundene Feature, unverändert übernommen in der Reihenfolge, in der das Feature sie deklariert — nichts wird gefiltert, umbenannt oder um ein Präfix gekürzt, sodass ein Template genau das liest, was der Feature-Autor geschrieben hat. Spiegelt .context.uses.<alias>.labels. Fehlt, wenn das Feature keine Labels deklariert, und wenn der type der Anbindung zu keiner Katalog-Entität aufgelöst wird.
  • .values (Map). Die eigene Säule der Entwicklerabsicht der Anbindung, verfasst in der Anbindungsdeklaration im Aggregate. Unterschieden vom .values oberster Ebene der Host-Komponente.
  • .infra (Map). Die eigene Säule der betrieblichen Dimensionierung der Anbindung, verfasst in der Anbindungsdeklaration im Release. Unterschieden vom .infra oberster Ebene der Host-Komponente.
  • .provides (Map mit Zeichenkettenwerten). Der aufgelöste öffentliche Vertrag des an diese Anbindung gebundenen FeatureRecipe — der Name der emittierten Ressource, ihr Datenschlüssel, eine Cloud-Identität und alle zusätzlichen Schlüssel, die das FeatureRecipe veröffentlicht. Gelesen als .features.<name>.provides.<key>, analog zu .context.uses.<alias>.provides: Der Konsument liest, was der Produzent veröffentlicht hat, statt es neu abzuleiten. Eine Anbindung, deren gebundenes FeatureRecipe nichts veröffentlicht, trägt gar keinen provides-Schlüssel statt einer leeren Map; prüfen Sie daher, bevor Sie einen einzelnen Schlüssel ansprechen.

.provides ist das, was eine Anbindung konsumierbar statt bloß vorhanden macht. Bei einem Feature, das einen schema.provides-Vertrag deklariert, wird dieser Vertrag gegenüber dem FeatureRecipe durchgesetzt, das es realisiert — das FeatureRecipe muss jeden deklarierten Schlüssel veröffentlichen —, und der Konsument liest das Ergebnis hier. So ermöglicht ein Identitäts-Feature, das einen ServiceAccount emittiert und dessen Namen veröffentlicht, dem konsumierenden Recipe, sich daran zu binden:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Der emittierte Name wird einmal, vom Produzenten, angegeben und konsumiert — nie auf der konsumierenden Seite wiederholt, wo die beiden voneinander abweichen könnten. Das Beispiel workload-identity-binding rendert dies durchgängig.

.labels ist das, was es einem Template ermöglicht, sich daran anzupassen, was eine Anbindung ist, ohne auf ihren Namen abzugleichen oder ihre URI zu parsen. Der Compiler liest keines davon — er überträgt die Zeichenketten, und der Template-Autor entscheidet, was sie bedeuten.

Ein Feature, das keine Labels deklariert, trägt gar kein .labels statt einer leeren Map; prüfen Sie daher, bevor Sie ein einzelnes Label ansprechen — der Zugriff über einen Schlüssel, der nicht vorhanden ist, bricht den Build ab. Lesen Sie ein Label, das das Feature möglicherweise nicht deklariert, über optional, denn index bricht unter Nennung des Schlüssels ab, wenn die Map ihn nicht enthält:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Da die Labels wortgetreu ankommen, erreicht der eigene Namespace eines Katalogautors das Template unverändert, und ein Recipe liest denselben Schlüssel, den das Feature deklariert.

Der .context-Block

.context ist der vom Compiler zusammengestellte Ausführungskontext für einen einzelnen Knoten — die Identitäts-, Topologie- und Zustellungs-Pipe-Daten, die der Renderer durch jede Template-Stelle führt. Seine Felder:

  • .context.instance_id (Zeichenkette). Die Identität des Knotens als Name — der Wert, den der Build selbst verwendet, um zu benennen und mit Labels zu versehen, was er emittiert, sodass ein Template, das daraus einen Ressourcennamen oder eine clusterinterne Adresse zusammensetzt, den Namen vorhersagt, den der Build tatsächlich erzeugt. Es ist der Name, den Sie für einen Knoten geschrieben haben, den Ihr eigenes Aggregate deklariert. Für einen Knoten, den ein importiertes Aggregate beisteuert, ist es die abgeflachte Identität mit ausgeschriebenem Modul-Trennzeichen (data-layer.main-db wird zu data-layer-zdmain-db), denn ein Punkt ist kein Zeichen, das ein Ressourcenname enthalten kann, und innerhalb einer Cluster-Adresse trennt er einen Service von seinem Namespace. Die Form mit Punkt ist die, mit der Ihre Dokumente und die Diagnosemeldungen des Builds diesen Knoten adressieren; siehe Namenskonventionen.
  • .context.rendered_name (Zeichenkette). Der Name, den der Provider des Knotens den Ressourcen gibt, die er für den Knoten rendert — aus von Ihnen gelieferter Quelle, etwa dem Release-Namen, den ein Chart liest, und aus einer Workload, die er synthetisiert, wenn er die Ressourcen dieser Workload nach einem eigenen Namen benennt, wie es helm mit demselben Release-Namen tut. Nur vorhanden, wo dieser Provider einen ableitet. In den Templates einer Feature-Anbindung ist es der Name der Host-Komponente, so wie .context.instance_id dort die Identität des Hosts ist; siehe Benennung einer gerenderten Ressource.
  • .context.labels (Map mit Zeichenkettenwerten). Im Katalog verfasste Labels plus etwaige label-transform-Ergänzungen, die beim Topologieaufbau vorgenommen werden.
  • .context.annotations (drei Buckets, siehe unten). Kaskadierte Annotationen, nach Herkunft gruppiert.
  • .context.inject (Map von Mechanismen, siehe unten). Die vorab hydratisierte, abgefangene Zustellungs-Pipe — die Standardoberfläche, die Recipe-Templates für komponentenübergreifende Werte lesen.
  • .context.uses (Map von Verbindungen, siehe unten). Die JOIN-Projektion über ausgehende topologische Kanten.
  • .context.self_inject (Map von Mechanismen, siehe unten). Für jeden Namen, den der Entwickler im eigenen inject:-Block der Komponente geschrieben hat, der eigene provides-Schlüssel, den dieser Eintrag zustellt, oder der eine eigene Wert, den sein Template liest.
  • .context.used_by (Liste, siehe unten). Die Komponenten, deren uses-Einträge auf diese zeigen. Gelesen von einem an die Komponente angebundenen FeatureRecipe, in den Templates, die die eigenen Ressourcen der Anbindung erzeugen; überall sonst leer.
  • .context.render_facts (Map von Listen, siehe unten). Was der Provider der Komponente über die von ihm gerenderte Ausgabe gemeldet hat, nach Faktname geschlüsselt. Gelesen von einem an die Komponente angebundenen FeatureRecipe, in jedem seiner Templates, das läuft, nachdem die Komponente gerendert wurde; überall sonst fehlend.

.context.annotations — drei Buckets

Annotationen kaskadieren in drei nach Herkunft geschlüsselte Buckets:

  • .context.annotations.release — Release-Boundary-Annotationen (Domäne 4). Werden verwendet, um physische Gegebenheiten zu steuern; Renderer leiten sie, wo angebracht, in infra:-Felder. Die bekannten aggrega.ai/*-Annotationen befinden sich in diesem Bucket.
  • .context.annotations.catalog — Component-Metadaten-Annotationen aus Domäne 2. Unveränderliche intrinsische Merkmale, verfasst vom Architect; hauptsächlich von Wasm-Policy-Plugins konsumiert.
  • .context.annotations.aggregate — Aggregate-Subsystem-Annotationen aus Domäne 1. Kognitive Metadaten; Renderer leiten sie, wo angebracht, in values:-Payloads.

Jeder Bucket ist eine flache Map von Zeichenkette zu Zeichenkette. Gemäß den Trennungsregeln der Architektur sind die Buckets für unterschiedliche Verwendungen gedacht; die Engine erzwingt die Trennung nicht, daher hält die Authoring-Disziplin die Buckets an ihrer vorgesehenen Semantik ausgerichtet. Siehe Kapitel 6 §2 Fluss 5 für das Design der kaskadierenden Annotationen.

.context.inject — die Zustellungs-Pipe

Die Pipe ist die vorab aufgelöste Zustellungs-Map des Compilers. Wenn ein Recipe-Template beim Basis-Rendering läuft, ist jede Inject-Quelle (vom Entwickler verfasste Self-Inject-Literale, gegen die eigenen provides aufgelöste Self-Inject-from:-Referenzen, gegen die provides des Ziels aufgelöste komponentenübergreifende uses[].inject-Referenzen, FeatureRecipe-injectMapping-Abfangungen) bereits zu einem endgültigen Zeichenkettenwert aufgelöst und in diese Map zusammengeführt worden.

Felder:

  • .context.inject.env — Map mit Zeichenkettenwerten von Umgebungsvariablenname → aufgelöster Wert.
  • .context.inject.file — Map mit Zeichenkettenwerten von Dateipfad → aufgelöster Wert.
  • .context.inject.arg — Map mit Zeichenkettenwerten von Argument-Flag → aufgelöster Wert.
  • .context.inject.all — Map mit Zeichenkettenwerten, die die Mechanismen env/file/arg/benutzerdefiniert in einem flachen Dictionary zusammenfasst; nützlich für die Serialisierung der gesamten Pipe ({{ toJson .context.inject.all }}).

Ein Mechanismus ist nur dann in der Pipe, wenn etwas über ihn zustellt. Ein Template, das einen liest, über den nichts zustellt — .context.inject.file ohne Dateizustellung —, liest ihn als leer, so wie ein Value-Template jeden fehlenden Schlüssel liest, und ein range darüber rendert nichts; dieser Lesezugriff liefert den leeren Wert für das gesamte Template, sodass ein {{ toJson .context.inject }} im selben Template "file": "" zeigt. hasKey .context.inject "file" gibt an, ob etwas über ihn zustellt.

  • Benutzerdefinierte Mechanismen (z. B. ssm_param) — lesbar unter ihrem eigenen Feldnamen, .context.inject.<mechanism>.<key>, genau wie die drei Kernmechanismen. Die Werte eines benutzerdefinierten Mechanismus erreichen die Pipe über Self-Inject auf Komponentenebene, über eine uses[].inject-Kante, über das inject:-Mapping einer Feature-Anbindung und über die injectMapping-Ausgabe eines FeatureRecipe. Für Self-Inject auf Komponentenebene muss die spec.inject-Allowlist der Component den Mechanismus nennen, und ein Mechanismus, den die Allowlist nicht nennt, bricht den Build ab. Die Einträge eines benutzerdefinierten Mechanismus erscheinen auch in .context.inject.all neben den drei Kernmechanismen. Ein benutzerdefinierter Mechanismus darf jeden Namen außer all tragen: Dieser Name ist die zusammengeführte Ansicht selbst, sodass ein Mechanismus dieses Namens nie für sich allein gelesen werden könnte. Ein inject-Block, der einen Mechanismus all nennt, und eine Allowlist einer Component oder eines Feature (spec.inject, das inject eines Sockets), die ihn aufführt, brechen den Build beim Laden des Dokuments ab, und die Ablehnung erklärt, dass der Name zu dieser zusammengeführten Ansicht gehört. Bei Namen wird zwischen Groß- und Kleinschreibung unterschieden, daher ist ALL ein gewöhnlicher benutzerdefinierter Mechanismus.

Die Pipe ist der Zustand nach dem Abfangen — die FeatureRecipe-injectMapping-Blöcke haben ihre Überschreibungen während des Inject-Mappings bereits tief in diese Pipe eingemischt, wenn Recipe-Templates sie lesen. Ein Mapping kann einen Schlüssel ersetzen, den der eigene inject:-Block der Komponente, einer der inject:-Blöcke ihrer Verbindungen oder der inject:-Block ihrer eigenen Anbindung zugestellt hat; ein Schlüssel, den zwei angebundene Features beide zustellen, über ihre inject:-Blöcke oder ihre Mappings, bricht den Build ab, statt diese Pipe mit einem der beiden Werte zu erreichen. Ein an eine Release-Boundary angebundenes Feature erreicht die Komponente auf dieselbe Weise, über das injectMapping seines FeatureRecipe, das im eigenen Kontext der Komponente läuft, unabhängig vom executionScope des FeatureRecipe — die Umschreibung der Host-Variable eines Konsumenten durch die Compose-Bridge ist ein solches Mapping, das derselben Regel unterliegt.

.context.self_inject — welchen eigenen Wert jeder der Namen des Entwicklers zustellt

Wo eine Component spec.inject deklariert, kann der Entwickler einen inject:-Block auf der Komponente selbst schreiben und die Namen wählen, unter denen die eigenen Werte und provides der Komponente zugestellt werden. .context.inject enthält, wozu diese Einträge aufgelöst wurden, und .inject_raw enthält sie so, wie sie geschrieben wurden; .context.self_inject gibt für jeden Eintrag an, welchen eigenen provides-Schlüssel der Komponente er zustellt oder welchen einen eigenen Wert sein Template liest. Es hat die Form, die das .context.uses.<alias>.inject einer Verbindung hat — Mechanismus, dann der Name des Entwicklers, dann ein Schlüssel —, wobei der Schlüssel einen der eigenen provides oder Werte der Komponente benennt:

  • provides.<key> — ein mit from: <key> geschriebener Eintrag, der einen der eigenen provides der Komponente zustellt.
  • values.<key> — ein Eintrag, dessen value:-Template genau einen der eigenen Werte der Komponente liest und sonst nichts, wobei <key> der Schlüssel der obersten Ebene dieses Werts ist. Text oder Funktionen um den Lesezugriff herum spielen keine Rolle, ebenso wenig, wie tief das Template in den Wert hineinliest: '{{ .values.role }}', 'role={{ .values.role | upper }}' und '{{ with .values.role }}{{ . }}{{ end }}' werden alle auf values.role abgebildet, und '{{ .values.config.port }}', '{{ index .values.config "port" }}' und '{{ (default dict .values.config).port }}' werden alle auf values.config abgebildet.
  • eine leere Zeichenkette — jeder andere Eintrag: ein Literal, ein Template, das zwei Werte liest, ein Template, das etwas anderes als die Werte liest (.infra, .metadata, .context), und ein Template, dessen Lesezugriff auf die Werte der Text keinem einzelnen Schlüssel der obersten Ebene zuordnet — die Werte, die über ihre Wurzel an eine Funktion übergeben werden (index .values "role"), die als Ganzes gelesenen Werte (toJson .values oder ein Feld, das innerhalb von {{ with .values }} oder über eine an .values gebundene Variable gelesen wird) oder der als Ganzes weitergegebene Kontext (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

Im Aggregate beginnt jedes value:-Template mit {{"{{"}} statt mit {{, weil der gesamte Text des Aggregate einmal als Template gelesen wird, für die Parameterinterpolation, bevor die eigenen Templates des Blocks ausgewertet werden; die in der obigen Liste zitierten Templates sind so gezeigt, wie sie nach diesem Escaping lauten. Siehe Text mit eigenen doppelten geschweiften Klammern.

Dadurch kann ein Recipe, das das eigene Image des Entwicklers ausführt, seine eigenen Variablennamen für die eigenen Werte der Komponente als Standardwerte behandeln — die Konvention des Katalogs der Standardbibliothek, die ein Unternehmenskatalog anders wählen kann. Bevor ein solches Recipe einen eigenen Wert unter einem eigenen Namen zustellt, prüft es, ob der Block des Entwicklers diesen Wert bereits zustellt, und überspringt seinen Standardwert, wenn das der Fall ist — so behält ein Entwickler, der einen Wert umbenennt, jeden anderen Standardwert:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject ist bei jedem Rendering vorhanden und leer, wo der Entwickler keinen Block geschrieben hat. Ein Mechanismus erscheint nur, wenn der Block ihn benennt; sichern Sie daher den Lesezugriff auf einen Mechanismus ab, den der Block möglicherweise nicht benennt, wie es das with oben tut. Ein Template sieht die Namen sortiert, wie auch immer es sie liest, so wie es jede Map sieht. Die Map wird aus dem Text gelesen, den der Entwickler geschrieben hat; nichts darin ist ein aufgelöster Wert, und der Compiler misst weder den Namen noch den Schlüsseln eine Bedeutung bei.

.context.uses — JOIN-Projektion

.context.uses ist die angereicherte Sicht des Compilers auf jede ausgehende topologische Kante des aktuellen Knotens. Jeder Map-Eintrag ist nach dem lokalen Socket-Alias geschlüsselt (z. B. wird databases.primary zu .context.uses.primary, wenn das Aggregate uses: { databases: { primary: { target: ... } } } verfasst hat) und trägt eine JOIN-Projektion des aufgelösten Zustands des Ziels plus den Zustellungsvertrag der Aufruferseite:

  • .target (Zeichenkette) — Instanz-ID des Zielknotens.
  • .socket (Zeichenkette) — Socket-Name auf Aufruferseite (der usesSchema-Schlüssel).
  • .provides (Map mit Zeichenkettenwerten) — die aufgelösten provides:-Schlüssel des Ziels (die öffentlichen Ausgabezeichenketten, die das Ziel-Recipe bei der Provides-Auswertung exportiert hat).
  • .inject (Map von Mechanismus → Map von Schlüssel → Wert) — Inject-Direktiven der Aufruferseite für diese Kante (der inject:-Block in der uses[].inject-Deklaration). Mechanismus-Schlüssel sind env/file/arg/benutzerdefiniert; die Map-Einträge pro Mechanismus sind Referenzen lokaler Schlüssel → Provides-Schlüssel des Ziels.
  • .labels (Map mit Zeichenkettenwerten) — die Labels des Ziels, nie die der konsumierenden Komponente: die Menge, die das eigene .context.labels des Ziels trägt, seine im Katalog verfassten Labels plus etwaige label-transform-Ergänzungen, die beim Topologieaufbau vorgenommen werden.
  • .annotations (drei Buckets) — die Annotations-Buckets release/catalog/aggregate des Ziels.
  • .component (Zeichenkette) — Component-Typ-URI des Ziels.
  • .resolved_version (Zeichenkette) — Component-Version des Ziels nach der Manifest-Auflösung.
  • .boundary_path (Zeichenkette) — Release-Boundary-Pfad des Ziels, gesetzt, ob das Ziel in der Boundary des Aufrufers liegt oder in einer anderen.
  • .origin_feature (Zeichenkette) — gesetzt, wenn die Kante durch eine Feature-Anbindung synthetisiert wurde (z. B. ein Sidecar-Feature, das eine uses-Kante zu einem Credential-Feature beiträgt).
  • .values (Map) — aufgelöste Entwicklerkonfiguration pro Kante für diese Verbindung, verfasst im uses-Eintrag des Aggregate. Nur vorhanden, wenn die Kante Werte pro Kante trägt.
  • .infra (Map) — aufgelöste Operator-Konfiguration pro Kante für diese Verbindung, verfasst im uses-Eintrag des Release. Nur vorhanden, wenn die Kante Infra pro Kante trägt.
  • .origin_release (Boolean) — true, wenn das Release diese Verbindung verdrahtet hat, statt dass das Aggregate sie deklariert; fehlt bei einer Verbindung, die das Aggregate deklariert.
  • .features (Map von Anbindungen) — die auf dieser Verbindung geschriebenen Anbindungen, nach dem Slot-Namen geschlüsselt, den der Socket deklariert; siehe unten. Nur vorhanden, wenn die Verbindung eine trägt.
  • .render_facts (Map von Listen) — was die Renderings des Ziels über die von ihnen emittierte Ausgabe gemeldet haben, nach Faktname geschlüsselt, in derselben Form wie das .render_facts eines Aufrufers in .context.used_by: jeder Fakt eine Liste, zuerst die Aufrufe des eigenen Providers des Ziels und dann jedes seiner Features in der Reihenfolge, in der sie gerendert haben, wobei die Listen, die ein Name von jedem erhält, zu einer zusammengeführt werden. Nur vorhanden für ein FeatureRecipe, das readsTargetRenderFacts: true setzt — seine Anbindungen rendern, sobald jede Komponente gerendert hat, sodass das Rendering jedes Ziels vollständig ist — und dann auf jeder Verbindung, leer für ein Ziel, dessen Provider nichts melden. Nur in valuesMapping:, workload: und artifacts: dieses FeatureRecipe gelesen; fehlt in den eigenen Recipe-Templates der Komponente, in einem injectMapping:, in with: und when: eines pipeline:-Schritts und in jedem FeatureRecipe, das den Schlüssel nicht setzt — ein Template eines solchen, das es liest, bricht den Build ab, bevor etwas gerendert wird.

Beide Konfigurations-Maps pro Kante sind konsumentenbezogen: Sie gelangen nur in den Render-Kontext des konsumierenden Knotens, nie in den des Ziels.

Ein bereitgestellter Wert wird unter .provides.<name> gelesen — die bereitgestellten Namen sind unter .provides verschachtelt, statt direkt auf der Kante zu liegen, sodass .context.uses.<alias>.<name> kein Feld adressiert und nichts liefert.

Auf einer Verbindung, deren beide Enden in unterschiedliche Ausgaben rendern, enthält .provides Stellvertreter statt der Werte. Wo der Provider eine solche Verbindung mit einer eigenen Referenz verdrahtet, sobald beide Ausgaben zusammengestellt sind — etwa ein CloudFormation-Stack, der den Wert eines anderen Stacks liest —, ist jeder Wert, den .context.uses.<alias>.provides trägt, ein Platzhalter, den der Provider später ersetzt, durch eine stackübergreifende Referenz oder durch den Wert selbst, wie seine eigene Seite beschreibt. Ein solcher Wert ist zu kopieren, nicht zu vergleichen — dieselbe Regel, der der Wert folgt, den eine solche Verbindung über die Inject-Pipe zustellt, der ein Platzhalter derselben Art ist. Schreiben Sie ihn vollständig, innerhalb einer größeren Zeichenkette oder über eine Funktion, die ihn unverändert lässt, etwa quote. Ein Template, das einen von .provides gelesenen Wert vergleicht, auf ihm verzweigt, ihn misst oder ihn verändert, würde anhand des Platzhalters entscheiden, daher bricht der Build stattdessen ab und nennt das Template und jeden gelesenen Wert; verzweigen Sie auf einem eigenen Wert der konsumierenden Komponente. Der Abbruch erfasst jedes Template, das die .provides der Verbindung liest, einschließlich des injectMapping: eines angebundenen FeatureRecipe, und ein FeatureRecipe mit Boundary-Geltungsbereich, das dieselben Verbindungen unter .boundary liest. Eine Verbindung, deren beide Enden in eine einzige Ausgabe rendern, trägt ihre Werte so, wie sie sind.

Ein Alias benennt eine Verbindung, daher enthält die Map einen Eintrag für jede Verbindung, die die Komponente herstellt. Die Map ist allein nach Alias geschlüsselt, unabhängig davon, in welchen Socket eine Verbindung verdrahtet ist, und keine zwei Verbindungen einer Komponente teilen sich einen Alias — weder auf einem Socket noch auf zweien, gleich welches Dokument oder welche Anbindung sie jeweils gezogen hat. Der Build weist ein solches Paar zurück, nennt beide Verbindungen und wo jede geschrieben wurde, bevor etwas gerendert wird. Eine Liste, die ein Ziel zweimal nennt, ist ein solches Paar, da der Alias eines Listeneintrags sein Ziel ist; ebenso eine local-Verbindung auf einem models-Socket neben einer local-Verbindung auf einem databases-Socket.

Recipe-Templates konsumieren diese Projektion, um zielseitigen Zustand nachzuschlagen, ohne den IR-Graphen zu durchlaufen. FeatureRecipe-injectMapping-Templates verwenden sie, um für boundary-übergreifende Routing-Entscheidungen auf Annotationen des Ziels zuzugreifen (das in entities/featurerecipe.md dokumentierte K8s-DNS-Resolver-Muster ist das kanonische ausgearbeitete Beispiel).

Ein Template, das über .context.uses iteriert, sieht die Verbindungen in Schlüsselreihenfolge — nach Alias sortiert —, nicht in der Reihenfolge, in der das Aggregate sie geschrieben hat. Jede Map, über die ein Template iteriert, wird so durchlaufen, .features und die .features einer Verbindung eingeschlossen, sodass ein Template die verfasste Reihenfolge nie durch Iterieren über eine Map zurückgewinnt; wo die Reihenfolge Bedeutung trägt, modelliert die Authoring-Oberfläche sie als Liste. So oder so ist die gerenderte Ausgabe über Builds derselben Eingabe hinweg byte-identisch.

Die Anbindungen einer Verbindung — .context.uses.<alias>.features

Eine auf einer Verbindung geschriebene Anbindung — unter features: im uses-Eintrag einer Komponente im Aggregate oder im Eintrag des Release für diese Verbindung — füllt einen Slot, den der Socket deklariert. Sie ist eine Anbindung der konsumierenden Komponente für alles, was der Build mit ihr tut: Das Manifest bindet ihre Realisierung, ihr FeatureRecipe rendert auf der Seite des Konsumenten, ihr Provides-Vertrag wird durchgesetzt. Ein Template liest sie unter der Verbindung, auf der sie geschrieben wurde:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Nach Slot geschlüsselt. .context.uses.<alias>.features.<slot> benennt den Slot, den der Socket der Verbindung deklariert — oben credential —, sodass ein Konsument, der mehrere Ziele erreicht, das eigene Credential jedes Ziels unter dem Alias dieses Ziels liest. Eine Verbindung, die keine Anbindung trägt, hat kein .features, weshalb der Lesezugriff abgesichert ist.
  • Die Form der Anbindung. Jeder Eintrag trägt genau das, was .features.<name> für eine der eigenen Anbindungen der Komponente trägt — .type, .resolved_version, .labels, .values, .infra und die aufgelösten .provides des an sie gebundenen FeatureRecipe —; siehe die Form der Anbindung. Die hier gelesenen Provides sind diejenigen, gegen die das eigene FeatureRecipe der Anbindung rendert, sodass der Name, auf den ein Konsument verweist, und der Name der Ressource, die dieses FeatureRecipe emittiert, ein einziger ausgewerteter Wert sind.
  • Nie in .features. Die eigenen .features der Komponente enthalten nur die Anbindungen, die in ihrem eigenen Block geschrieben sind. Ein Recipe, das über .features iteriert und Anbindungen nach Typ herausgreift — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}… —, trifft daher nie auf das Credential einer Verbindung, auch nicht auf eines desselben Feature: Ein Template erreicht die Anbindung einer Verbindung über ihre Verbindung, nie über .features. Dasselbe gilt auf jeder Oberfläche, die die Anbindungen einer Komponente zeigt, den assertions-Kontext eingeschlossen.

Die Komponenten, die diese verwenden — .context.used_by

.context.uses blickt nach außen, auf die Verbindungen, die eine Komponente herstellt. .context.used_by blickt nach innen, auf die Komponenten, deren uses-Einträge auf diese zeigen. Ein an die Komponente angebundenes FeatureRecipe liest es, und dort gehört eine Ressource hin, die diese Verbindungen beschreibt oder einschränkt — etwa eine Network Policy, die nur die Komponenten zulässt, die als Aufrufer dieser Komponente deklariert sind:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Jeder Eintrag trägt:

  • .component_id (Zeichenkette) — die Instanz-ID der verbindenden Komponente in ihrer abgeflachten Form (frontend, data-layer.etl), der Wert, den ein subDirectory:-Pfad-Template als .component_id liest.
  • .socket (Zeichenkette) — der Socket, den die Verbindung auf der verbindenden Komponente füllt (ihr usesSchema-Schlüssel).
  • .provides (Map mit Zeichenkettenwerten) — was die verbindende Komponente veröffentlicht, eingeschränkt auf die Schlüssel, die ihre Component deklariert: dieselben Werte, die ein Konsument dieser Komponente unter .context.uses.<alias>.provides liest. Ein Schlüssel, den das Recipe der Komponente veröffentlicht, ohne dass ihre Component ihn deklariert, gehört nicht dazu.
  • .source_namespace (Zeichenkette) — der Namespace, in dem die verbindende Komponente platziert ist: die für sie geltende aggrega.ai/namespace-Annotation, entlang ihrer Boundaries nach unten kaskadiert, wobei ihr eigener Eintrag im Release Vorrang hat. Eine Komponente, deren Release-Eintrag den Namespace setzt oder ihn mit null löscht, trägt ihre eigene Einstellung statt der ihrer Boundary, sodass der Wert den Namespace benennt, in den die eigenen Ressourcen der Komponente rendern. Fehlt, wenn für die Komponente kein Namespace gilt; lesen Sie ihn über with oder if, wie das Beispiel es tut, statt ihn unverarbeitet auszugeben.
  • .source_boundary_path (Zeichenkette) — der Pfad der Release-Boundary, die die verbindende Komponente enthält, wobei verschachtelte Boundaries durch / verbunden sind (edge, edge/inner).
  • .render_facts (Map von Listen) — was die Renderings der verbindenden Komponente über die von ihnen emittierte Ausgabe gemeldet haben, nach Faktname geschlüsselt, in derselben Form wie .context.render_facts. Jeder Fakt ist eine Liste, daher iteriert ein Template immer darüber, auch wenn sie einen einzigen Eintrag enthält. Ihre Einträge können aus dem eigenen Rendering der verbindenden Komponente und aus den Renderings der an sie angebundenen Features stammen: Die Listen, die ein Name von jedem erhält, werden zu einer zusammengeführt, zuerst die Aufrufe des eigenen Providers der Komponente, dann jedes ihrer Features in der Reihenfolge, in der sie gerendert haben. Nur vorhanden für ein FeatureRecipe, das readsCallerRenderFacts: true setzt — seine Anbindungen rendern, sobald jede Komponente gerendert hat, sodass das Rendering jedes Aufrufers vollständig ist — und dann auf jedem Eintrag, leer für einen Aufrufer, dessen Provider nichts melden. Ein FeatureRecipe, das den Schlüssel nicht setzt, sieht auf keinem Eintrag .render_facts, und ein Template davon, das sie liest, bricht den Build ab, bevor etwas gerendert wird.

Die beiden Platzierungswerte sind diejenigen, die ein FeatureRecipe mit Boundary-Geltungsbereich als source_namespace und source_boundary_path im Eintrag derselben Verbindung in seinen .boundary-Kantenlisten liest: Beide Sichten lesen auf dieselbe Weise, wo eine Komponente platziert ist, sodass sie darüber nie uneins sind. Eine Kante in diesen Listen trägt außerdem den Zusammenstellungspfad jedes Endpunkts — source_assembly_path und target_assembly_path, das Verzeichnis unter dem Ausgabeverzeichnis des Builds, in das der Provider des Endpunkts ihn zusammenstellt —, den ein .context.used_by-Eintrag nicht trägt.

Ein FeatureRecipe, das readsCallerRenderFacts: true setzt, liest die Fakten jedes Aufrufers auf dieselbe Weise, wie es die des Hosts liest. Für einen Provider, der einen Fakt namens ports dokumentiert, dessen Einträge jeweils einen port tragen:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Ein Aufrufer, dessen Provider keine ports meldet, rendert ein leeres ports:, statt fehlzuschlagen, denn ein Name, den niemand gemeldet hat, liest sich als nichts.

Wie sich die Liste verhält:

  • In der geschriebenen Reihenfolge. Die Einträge folgen der Reihenfolge, in der die verbindenden Komponenten geschrieben sind, dann der Reihenfolge der eigenen uses-Einträge jeder einzelnen. Eine Komponente, die sich zweimal verbindet, erscheint zweimal, einmal pro Verbindung. Da es eine Liste und keine Map ist, trifft ein range die Aufrufer in dieser Reihenfolge an — nichts wird sortiert.
  • Nur dort, wo die Anbindung ihre eigenen Ressourcen rendert. valuesMapping:, workload: und artifacts: des FeatureRecipe lesen sie. Sie ist leer in den eigenen Recipe-Templates der Komponente, in einem injectMapping: und in with: und when: eines pipeline:-Schritts, weil das, was jedes davon erzeugt, in der eigenen gerenderten Ausgabe der Komponente landen kann: Ein injectMapping: schreibt die Zustellungs-Pipe der Komponente, und ein Pipeline-Schritt kann die Dokumente der Komponente umschreiben. Das hält die eigene Ausgabe einer Komponente gleich, wer auch immer sie verwendet — einen weiteren Aufrufer mit einer Komponente zu verdrahten ändert die Ausgabe eines an sie angebundenen Feature, das ihre Aufrufer liest, und nichts von dem, was die Komponente selbst rendert.
  • Nichts über die Verbindung selbst. Ein Eintrag trägt keine values oder infra pro Verbindung und keine der Anbindungen der Verbindung; diese bleiben bei der konsumierenden Komponente, unter ihrem .context.uses.<alias>.
  • Leer, wenn nichts die Komponente verwendet. Ein range darüber rendert dann nichts.
  • Durchgereicht, nie interpretiert. Die Identität, der Socket, die veröffentlichten Werte und die Platzierung sind Zeichenketten, die der Compiler durchreicht, und die Render-Fakten sind das, was die Provider jedes Aufrufers gemeldet haben, nach Name geschlüsselt. Er leitet nichts aus einem Namen ab, ruft nichts ab und entscheidet nichts darüber, welche Aufrufer eine Ressource zulassen soll; das Template entscheidet.

Was ein Provider über ein Rendering gemeldet hat — .context.render_facts

Der Provider einer Komponente kann Fakten über die von ihm gerenderte Ausgabe melden — Eigenschaften der von ihm geschriebenen Dokumente, die nur seine eigene Kenntnis seines Formats erkennen kann. Welche Fakten ein Provider meldet, unter welchen Namen und mit welchem Inhalt in jedem Eintrag, ist der eigene dokumentierte Vertrag dieses Providers; siehe Fakten darüber melden, was ein Guest ausgegeben hat für die Seite des Providers. Der helm-Provider etwa meldet die Labels der von ihm emittierten Pod-Templates, die Selektoren seiner Controller und Services und die Ports seiner Container — siehe seine Render-Fakten. Ein an die Komponente angebundenes FeatureRecipe liest, was der Provider der Komponente gemeldet hat, unter .context.render_facts, nach Faktname geschlüsselt. Für einen Provider, der einen Fakt namens ports dokumentiert, dessen Einträge jeweils einen name und einen port tragen:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Jeder Fakt ist eine Liste. Ein Provider meldet jeden Fakt als Liste, auch wenn sie einen einzigen Eintrag enthält, daher iteriert ein Template immer darüber — es gibt keinen einzelnen Wert, der für sich allein zu lesen wäre.
  • Eine Liste pro Name, über das Rendering der Komponente zusammengeführt. Das Rendern einer Komponente kann mehr als einen Aufruf ihres Providers erfordern — etwa ein Chart-Rendering und eine Artifacts-Platzierung —, und jeder Aufruf meldet für sich. Die Listen, die ein Name aus diesen Aufrufen erhält, werden zu einer zusammengeführt, in der Reihenfolge, in der die Aufrufe liefen. Was die an die Komponente angebundenen Features gerendert haben, gehört hier nicht dazu: Ein Feature liest unter .context.render_facts nur das eigene Rendering der Komponente, gleich was die anderen Features der Komponente emittiert haben.
  • Auf jedem Template eines angebundenen FeatureRecipe. Seine valuesMapping:, workload: und artifacts: lesen es, ebenso with: und when: seiner pipeline:-Schritte — die Fakten stammen aus dem eigenen Rendering der Komponente, sodass ihr Lesen nichts davon abhängig macht, wer sich mit der Komponente verbindet. Es fehlt in den eigenen Recipe-Templates der Komponente und in einem injectMapping:, die laufen, bevor die Komponente gerendert hat.
  • Leer statt fehlend. Wo der Provider der Komponente nichts meldet, ist .context.render_facts eine leere Map, und ein Name, den niemand gemeldet hat, liest sich als nichts, sodass ein range darüber nichts rendert, statt fehlzuschlagen.
  • Reihenfolge. Eine Liste behält ihre Einträge in der Reihenfolge, in der der Provider sie gemeldet hat. Ein Objekteintrag ist eine geschlüsselte Map wie jede andere im Kontext, sodass ein Template, das über einen iteriert, seine Schlüssel in Schlüsselreihenfolge antrifft.
  • Durchgereicht, nie interpretiert. Der Compiler prüft nur, dass der Wert jedes Fakts eine Liste ist. Er liest nichts darüber, was ein Name oder ein Eintrag bedeutet; das Template entscheidet, was damit geschieht.

Das .uses einer Assertion — nach Socket, dann nach Alias geschlüsselt

Ein assertions:-Template liest dieselben Verbindungen über eine eigene, engere Sicht: .uses an der Wurzel statt unter .context, und ohne etwas, das das Ziel einer Verbindung veröffentlicht hat, weil beide Assertion-Phasen vor dem Rendering ausgewertet werden. Es spiegelt die Authoring-Form uses: <socket>: <alias>: { target: … } — nach Socket geschlüsselt und unter jedem Socket nach dem Alias jeder Verbindung darauf, wobei eine als Listeneintrag geschriebene Verbindung ihr Ziel als Alias nimmt. Der Eintrag jeder Verbindung trägt target, alias und, für eine Verbindung, die eine Feature-Anbindung gezogen hat, origin_feature, sowie drei der Fakten, die .context.uses trägt, unter denselben Namen und mit denselben Werten: .labels, die Labels des Ziels; .values, die auf der Verbindung geschriebenen Werte; und .features, die auf ihr geschriebenen Anbindungen, nach Slot geschlüsselt. Jeder der drei ist auf jedem Eintrag vorhanden, leer, wo die Verbindung keine trägt. Eine Anbindung unter .features trägt nur ihren type, ihre resolved_version und ihre values — die Form, in der eine Assertion jede Anbindung liest, die eigenen einer Komponente eingeschlossen, da das FeatureRecipe einer Anbindung seine provides noch nicht aufgelöst hat, wenn eine Assertion läuft.

Ein Socket mit einer Verbindung und ein Socket mit mehreren haben dieselbe Form, sodass eine Assertion beide auf dieselbe Weise liest. Für eine Komponente, deren Aggregate-Eintrag uses: { models: { local: { target: llama }, fast: { target: turbo } } } schreibt:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" fragt, ob der Socket verdrahtet ist, len zählt seine Verbindungen, ein range darüber besucht jede in alphabetischer Reihenfolge ihrer Aliasse, und .uses.models.local.target liest eine Verbindung. .uses.models.target adressiert keine Verbindung und bricht unter dem missingkey=error der Assertions-Oberfläche ab. Jede Verbindung hat einen eigenen Eintrag, aus demselben Grund wie bei der Map des Render-Kontexts: Zwei Verbindungen einer Komponente teilen sich nie einen Alias, weil der Build das zurückweist, bevor irgendeine Assertion läuft. Der vollständige Assertion-Kontext ist unter assertions-block.md dokumentiert.

Der Template-Kontext trägt diese Inject-förmigen Felder, jedes mit seiner eigenen Semantik. Recipe- und FeatureRecipe-Autoren sollten wissen, welche Oberfläche sie lesen.

OberflächeTypBefüllt, wennVerwendung
.context.injectMap von Mechanismen (immer vorhanden)Jedes RenderingDie standardmäßige, vorab hydratisierte Zustellungs-Pipe — lesen Sie diese in valuesMapping:/workload:/artifacts:-Templates und an jeder Template-Stelle eines FeatureRecipe.
.inject (oberste Ebene)Map von Mechanismen (nullbar)Beim Rendern des FeatureRecipe einer Anbindung, wenn die Anbindung einen inject:-Block verfasstDie eigenen inject:-Einträge der Anbindung, unter jedem Mechanismus, den ihr Block nennt — env, file, arg oder ein benutzerdefinierter wie vault_ref —, wobei jeder lokale Name dem Schlüssel zugeordnet ist, den sein from: nennt. Dieser Schlüssel ist entweder einer, den das FeatureRecipe in seinen provides: veröffentlicht und den der Compiler auch in .context.inject der Komponente liefert, oder ein Schlüssel, den ein FeatureRecipe, das .inject liest, selbst verbraucht: Ein Eintrag, der einen Schlüssel nennt, den das FeatureRecipe nicht veröffentlicht, bricht den Build ab, es sei denn, ein Template, das das FeatureRecipe gegen diesen Kontext auswertet — sein valuesMapping:, workload:, artifacts:, omits: oder das with: oder when: eines Pipeline-Schritts —, liest .inject über einen Pfad, den das Template nennt: .inject, .inject.env, {{ with .inject }} und Ähnliches, nicht über eine Übergabe des gesamten Kontexts wie toJson .. Sein injectMapping: zählt nicht, weil es gegen den Kontext der Komponente ausgewertet wird, in dem .inject fehlt. Der Block einer Anbindung enthält kein Literal: Ein value:-Eintrag dort bricht den Build ab, und ein Literal, das die Komponente braucht, wird in den eigenen inject:-Block der Komponente geschrieben. Ein benutzerdefinierter Mechanismus wird unter .inject.<mechanism> genau so gelesen wie .inject.env, und seine Einträge erscheinen in .inject.all neben den drei Kernmechanismen. Ein punktierter Lesezugriff auf einen Mechanismus, den die Anbindung nicht verfasst, bricht als unbekannter Schlüssel ab, selbst innerhalb eines if oder eines with, wo .context.inject.<mechanism> als leer gelesen wird; lesen Sie einen Mechanismus, den die Anbindung womöglich nicht verfasst, über {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, was sich bauen lässt, ob die Anbindung den Mechanismus oder überhaupt einen inject:-Block verfasst oder nicht. Fehlt in den Templates eines Basis-Recipe und bei einer Anbindung, die keinen inject:-Block verfasst.
.inject_raw (oberste Ebene)Map von Mechanismen (nullbar)Gesetzt, wenn der Entwickler einen inject:-Block auf der übergeordneten Komponente verfasst hatDie unveränderte Entwicklerabsicht vor jedem Abfangen durch Inject-Mapping. Jeder Mechanismus, den der Block nennt — env, file, arg oder ein benutzerdefinierter wie ssm_param —, steht unter seinem eigenen Namen und enthält die Einträge genau so, wie sie geschrieben sind (in mit from oder value), in der geschriebenen Reihenfolge: .inject_raw.ssm_param liest einen benutzerdefinierten Mechanismus so, wie .inject_raw.env den Kernmechanismus liest. Verwenden Sie dies für Logikprüfungen der Art „Hat der Entwickler diesen Zustellungsschlüssel ursprünglich angefordert?“; immun gegen das Umschreiben durch das injectMapping eines FeatureRecipe. nil, wenn der Entwickler den inject:-Block weggelassen hat.
.context.self_injectMap von Mechanismen (immer vorhanden)Jedes Rendering; leer, wo der Entwickler keinen inject:-Block auf der Komponente geschrieben hatJeder Name im eigenen inject:-Block der Komponente, abgebildet auf den eigenen Schlüssel, den sein Eintrag zustellt — provides.<key>, values.<key> oder leer. Dient dazu, einen Standardnamen für einen eigenen Wert zu überspringen, den der Entwickler bereits zustellt; siehe oben.

Autoren, die die aufgelöste Zustellung nach dem Abfangen benötigen, sollten .context.inject lesen. Autoren, die die unveränderliche ursprüngliche Absicht benötigen (z. B. um ein Abfangen zu erkennen oder um ein Fallback-Verhalten auszugeben, wenn der Entwickler einen Inject-Block weggelassen hat), sollten .inject_raw lesen. Autoren, die wissen müssen, welche der eigenen Werte der Komponente der Entwickler bereits benannt hat, sollten .context.self_inject lesen.

Oberfläche des FeatureRecipe einer Anbindung

Wenn der Renderer die Templates des FeatureRecipe einer Anbindung auswertet, wird ein zusätzliches Feld oberster Ebene gesetzt:

  • .attachment_name (Zeichenkette) — der Instanzname der Anbindung: der Slot, den sie im featuresSchema der besitzenden Entität füllt, oder der freie Name, den der Autor ihr gegeben hat. locals:, provides:, injectMapping:, valuesMapping: und artifacts: eines FeatureRecipe lesen ihn, um einen deterministischen Ressourcenbezeichner abzuleiten — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, wo der Provider des Hosts einen gerenderten Namen meldet, wie es helm tut, und {{ .context.instance_id }}-{{ .attachment_name }}, wo er keinen meldet —, und um die gerade verarbeitete Anbindung zu benennen.

Die eigenen Templates eines Basis-Recipe lösen keine Anbindung auf, daher ist das Feld nicht Teil ihres Kontexts: Ein provides:-, locals:- oder source:-Template eines Recipe, das darauf verweist, bricht unter Nennung des Verweises ab, statt einen leeren Wert zu rendern. Ein FeatureRecipe mit executionScope: boundary rendert einmal für die Boundary statt einmal pro Komponente, daher ist das Feld auch den Templates, die für die Boundary laufen, nicht verfügbar; sein injectMapping: läuft für jede Komponente, die die Anbindung erreicht, und liest es dort.

Auf den Templates, die die eigenen Ressourcen der Anbindung erzeugen — ihren valuesMapping:, workload: und artifacts: —, listet der Kontext der Anbindung außerdem die Komponenten auf, die ihren Host verwenden, unter .context.used_by, und trägt, wo ihr FeatureRecipe readsTargetRenderFacts: true setzt, das, was jede Komponente gerendert hat, mit der ihr Host verdrahtet ist, unter .context.uses.<alias>.render_facts. Diese Templates und ihre pipeline:-Schritte lesen außerdem, was der Provider ihres Hosts über das Rendering des Hosts gemeldet hat, unter .context.render_facts. Ein FeatureRecipe mit Boundary-Geltungsbereich rendert seine Ressourcen für keine Host-Komponente und ohne .context; es liest stattdessen jede Verbindung in seine Boundary unter .boundary.internal_uses_edges und .boundary.incoming_cross_boundary_uses_edges. Sein injectMapping: ist das einzige von ihm geschriebene Template, das im Kontext einer Komponente läuft — dem jeder Komponente, die die Anbindung erreicht, .context.* eingeschlossen —, und ein Verweis auf .boundary dort bricht den Build ab.

Das Feld ist der einzige Weg zum Instanznamen der Anbindung. .context.instance_id ist die Host-Komponente, für die die Anbindung aufgelöst wird — es bezeichnet den Host auf jeder Template-Oberfläche, die der Compiler auswertet, einschließlich der eigenen locals: eines FeatureRecipe —, daher sind die beiden Namen nicht austauschbar, und keiner steht für den anderen.

.source gehört der Anbindung selbst. Das source:-Template eines FeatureRecipe wird vor seinem valuesMapping: ausgewertet, so wie das eines Recipe vor dessen eigenem, und was es erzeugt hat, ist das, was .source in den Templates enthält, die die Ressourcen der Anbindung erzeugen — seinem valuesMapping:, omits:, workload: und artifacts: — sowie in seinen pipeline:-Schritten. Es ist nie die Quelle der Host-Komponente: Ein FeatureRecipe, das kein source: deklariert oder dessen Template nichts erzeugt, liest dort nichts, selbst auf einem Host, dessen Recipe eine deklariert. Ein FeatureRecipe mit Boundary-Geltungsbereich liest seine eigene Quelle in denselben Templates. Die einzige Ausnahme ist das injectMapping:, das läuft, bevor die Quelle der Anbindung ausgewertet wird, und .source so liest wie das eigene Recipe der Host-Komponente.

Auch .context.rendered_name gehört zur Host-Komponente: Auf jedem Template einer Anbindung pro Komponente trägt es den Namen, den der eigene Provider des Hosts für den Host meldet — den Wert, den das eigene Recipe des Hosts liest —, sodass eine Anbindung eine Ressource mit {{ .context.rendered_name }}-{{ .attachment_name }} nach ihrem Host benennt und einen Namen erhält, den die Plattform akzeptiert, auch wo die Identität des Hosts einen Unterstrich oder einen Großbuchstaben enthält. Es ist überall vorhanden, wo der Provider des Hosts einen Namen meldet, und fehlt, wo er keinen meldet, und es auf einem solchen Host zu lesen bricht den Build aus jedem Template ab, das das FeatureRecipe inline schreibt, außer seinem injectMapping:; siehe Benennung einer gerenderten Ressource.

Verfügbarkeit pro Template-Stelle

Die Verfügbarkeit der Felder variiert je nach Template-Stelle. provides:-Templates eines Recipe laufen bei der Provides-Auswertung mit in sich geschlossenem Kontext (kein .context.inject/.context.uses); valuesMapping: eines Recipe läuft beim Basis-Rendering mit dem vollständigen Template-Kontext; injectMapping: eines FeatureRecipe läuft beim Inject-Mapping mit dem vollständigen Template-Kontext einschließlich der abgefangenen Inject-Pipe. Die vollständige Verfügbarkeitstabelle Stelle für Stelle befindet sich unter expansion-matrix.md; diese Seite dokumentiert die Feldformen, auf die die Spalte „verfügbare Referenzen“ der Matrix verweist.

Querverweise