Namenskonventionen
Dieses Kapitel behandelt die Regeln zur Benennung und zur Groß- und Kleinschreibung, die für verfasste Aggrega-Inhalte gelten: das Muster für vom Benutzer verfasste Instanznamen, die Schreibweisendisziplin für Feldnamen in der DSL, die Schreibweise, die die Plattform für die Bezeichner verwendet, die sie statt Ihnen definiert, und die Kommentarsyntax an der YAML-Oberfläche zum Verfassen.
Instanznamen
Vom Benutzer verfasste Instanznamen — die Schlüssel, die der Entwickler für Komponenten, Features, Aggregate, Subsysteme, Grenzen sowie uses-Sockets und Aliasse schreibt — folgen alle einem einzigen Muster: ^[a-zA-Z0-9_-]+$. Sowohl kebab-case (pii-filter, my-agent) als auch snake_case (openai_key, db_credentials) sind gültig; Teams können die Konvention übernehmen, die sie bevorzugen.
Zulässige Zeichen: alphanumerische Zeichen (a-z, A-Z, 0-9), Bindestriche (-) und Unterstriche (_). Andere Zeichen sind nicht zulässig.
Beispiele:
components: web-server: # kebab-case finance_worker: # snake_case
features: pii-filter: # kebab-case audit_logger: # snake_case openai_key: # snake_case — natural for a credential attachment db-password: # kebab-case — also valid| Muster | Geltungsbereich | Beispiele |
|---|---|---|
^[a-zA-Z0-9_-]+$ | Alle vom Benutzer verfassten Instanznamen | web-server, openai_key, pii-filter |
Das Muster wird bei der Auflösung über JSON Schema patternProperties durchgesetzt.
Was ein Komponentenname kostet und warum Großbuchstaben unter manchen Zielen mehr kosten
Das obige Muster sagt, was Sie schreiben dürfen. Was ein Name kostet, ist eine separate Frage, und die Antwort hängt vom Ziel ab, auf das eine Komponente bereitgestellt wird — es lohnt sich also, dies zu wissen, bevor Sie einen Namen wählen, und nicht erst dann, wenn ein Build einen ablehnt.
Der Name einer Komponente wird zu der Identität, mit der jede von ihr ausgegebene Ressource gekennzeichnet wird, und jedes Ziel leitet seine eigenen Namen aus dieser Identität ab: Ein Chart-Installer leitet einen Release-Namen ab, ein Container-Orchestrator leitet Service-Namen ab. Ein Ziel, dessen Alphabet enger ist als das Muster, kann ein Zeichen, das es nicht zulässt, nicht übernehmen, und Aggrega bildet ein solches Zeichen nicht stillschweigend auf ein ähnliches ab — zwei Namen, die ein Autor unterscheiden kann, dürfen in einem Cluster nicht zu einem Namen werden. Daher wird ein Zeichen, das das Ziel nicht zulässt, stattdessen als Escape-Sequenz ausgeschrieben, und eine Escape-Sequenz ist länger als das Zeichen, das sie ersetzt.
Die praktische Folge: Ein Großbuchstabe ist unter manchen Zielen kostenlos und unter anderen teuer.
- Unter einem Ziel, dessen Namen Großbuchstaben zulassen — etwa einer Compose-Datei für die Container-Orchestrierung — wird
PaymentsAPIgenau so übernommen, wie Sie es geschrieben haben, und kostet elf Zeichen. - Unter einem Ziel, dessen Namen nur Kleinbuchstaben enthalten dürfen — dem Release-Namen eines Chart-Installers — wird jeder Großbuchstabe escaped, und schon ein Name aus sechs Großbuchstaben allein überschreitet, was dieses Ziel akzeptiert.
Es gibt einen zweiten Effekt, und er ist der gravierendere: Eine Escape-Sequenz beginnt mit einem Bindestrich. Ein Ziel, das verlangt, dass ein Name mit einem Kleinbuchstaben oder einer Ziffer beginnt, lehnt daher einen Namen ab, dessen erstes Zeichen eines ist, das es nicht zulässt, wie kurz der Rest auch sein mag — keine Kürzung ändert daran etwas.
Die Empfehlung folgt aus den beiden Effekten. Bevorzugen Sie Kleinbuchstaben und Ziffern, mit Bindestrichen zwischen Wörtern, und beginnen Sie einen Namen mit einem Kleinbuchstaben. payments-api wird von jedem Ziel, für das Aggrega einen Provider mitliefert, unverändert übernommen. payments_api wird von einer Compose-Datei übernommen, nicht aber vom helm-Ziel, dessen Ressourcennamen keinen Unterstrich zulassen: Die Services, Workloads und das Release, die es nach der Komponente benennt, werden payments-zuapi geschrieben. PaymentsAPI kostet dort noch mehr. Eine Recipe, die die Adresse einer solchen Ressource veröffentlicht, liest die eigene Schreibweise des Ziels, statt sie vorherzusagen — siehe templates/rendered-resource-names.md.
Eine führende Ziffer darf geschrieben werden und kostet unter einer Compose-Datei nichts, aber das helm-Ziel lehnt sie ab. Ein Kubernetes-Service-Name muss mit einem Buchstaben beginnen, und die Services, die ein Chart oder eine synthetisierte Workload ausgibt, werden nach der Komponente benannt, sodass eine Komponente namens 1cache einen helm-Build abbricht — die Ablehnung nennt die Komponente und besagt, dass ein Service-Name mit einem Buchstaben beginnen muss —, statt Services zu rendern, die der Cluster ablehnen würde.
Nichts davon ist eine Regel, die der Compiler aus eigenem Antrieb anwendet — er kennt die Benennungsregeln keines Ziels und erfindet keine Grenze. Der Provider jedes Ziels ist für seine eigenen Namen zuständig, sodass ein Name nur dann abgelehnt wird, wenn das Ziel, auf das eine Komponente tatsächlich bereitgestellt wird, erklärt, ihn nicht verwenden zu können; die Ablehnung enthält die eigene Begründung dieses Ziels und verweist auf den von Ihnen geschriebenen spec.components-Schlüssel. Ein Name, der unter einem Ziel in Ordnung ist und unter einem anderen abgelehnt wird, ist das erwartete Verhalten und keine Inkonsistenz.
Namen, die Aggrega selbst zusammensetzt — etwa die Identität eines an einer Grenze angehängten Features —, werden umgekehrt behandelt: Sie werden gekürzt, um zum Ziel zu passen, statt abgelehnt zu werden, weil sie aus Teilen zusammengesetzt sind, die an mehreren Stellen geschrieben wurden, und kein einzelner Autor die Länge überblicken kann, die sie erreichen. Abgelehnt wird nur ein Name, den Sie geschrieben haben.
Der Punkt als reserviertes Pfadtrennzeichen
Das Punktzeichen (.) ist für alle vom Benutzer verfassten Instanznamen ausgeschlossen. Der Punkt erfüllt den strukturellen Zweck eines vom Compiler erzeugten Pfadtrennzeichens für aggregatübergreifende Komponentenreferenzen.
Wenn ein Wurzel-Aggregate ein Unteraggregat namens data-layer importiert, das eine Komponente namens main-db enthält, bildet der Compiler die abgeflachte absolute ID data-layer.main-db, indem er den Instanznamen des Aggregats und den Instanznamen der Komponente mit einem Punkt verbindet. Dieser gepunktete Pfad erscheint in:
uses-Ziele des Entwicklers:target: data-layer.public_db— Verweis auf eine exportierte Komponente aus einem verschachtelten Aggregat.- Den eigenen Diagnosen des Builds: Ein Abbruch oder eine Warnung zu dieser Komponente nennt sie mit ihrem gepunkteten Pfad, sodass der Name, den Sie lesen, derjenige ist, nach dem Sie in Ihren Dokumenten suchen können.
Das Trennzeichen erreicht keinen Namen
Ein gepunkteter Pfad ist eine Adresse innerhalb Ihrer Dokumente und kein Name, den ein Bereitstellungsziel akzeptiert. Ein Kubernetes-Service-Name lässt überhaupt keinen Punkt zu; schlimmer noch, ein Punkt innerhalb einer Cluster-Adresse trennt einen Service von dem Namespace, in dem er sich befindet, sodass ein gepunkteter Name, der einem Consumer als Host übergeben wird, zu einem anderen Service aufgelöst würde, statt fehlzuschlagen.
Deshalb wird das Trennzeichen in jedem Namen und Label, das der Build aus der Identität einer Komponente ableitet, ausgeschrieben, und zwar ausgeschrieben statt ersetzt: data-layer.main-db wird zu data-layer-zdmain-db. Würde es durch ein Zeichen ersetzt, das ein Ziel akzeptiert, könnten zwei verschiedene Komponenten zu einem Namen gelangen — data-layer.main-db und eine Komponente, die jemand als data-layer-main-db geschrieben hat —, und ein Name, zu dem zwei Komponenten gelangen, identifiziert keine von beiden.
Was das erreicht und was nicht:
- Es erreicht die aus der Identität abgeleiteten Namen und Labels —
metadata.namean einer Ressource, die Aggrega synthetisiert, die Labelsaggrega.ai/component-idundapp.kubernetes.io/name, die Selektoren, die auf sie passen, die ausgegebenen Dateinamen,{{ .context.instance_id }}und den Namen, den ein Provider für sich selbst ableitet, etwa einen helm-Release-Namen. Sie ändern sich gemeinsam, sodass eine Adresse, die eine Recipe aus dem Schlüssel zusammensetzt, der eine Ressource benennt —.context.instance_id, wo das Ziel sie nach der Identität benennt,.context.rendered_name, wo das Ziel einen eigenen Namen meldet —, weiterhin die Ressource benennt, die der Build ausgibt. - Es erreicht keinen Namen, den Sie geschrieben haben. Ein Komponentenname ohne Trennzeichen kommt Byte für Byte unverändert zurück, sodass nur eine Komponente, die ein importiertes Aggregate beisteuert, in der Ausgabe anders geschrieben wird als im Dokument.
- Es erreicht nicht die Namen innerhalb eines Charts oder Fragments, das ein Autor bereitgestellt hat. Diese gehören demjenigen, der sie geschrieben hat, und ein Name, der aus einem Drittanbieter-Chart übernommen wird — ein Custom-Resource-Name der Form
<plural>.<group>, in dem ein Punkt zulässig ist —, wird genau so ausgegeben, wie dieses Chart ihn geschrieben hat.
🔴 Dieser letzte Punkt hat eine Folge dafür, was eine Recipe veröffentlichen sollte, und er ist auf dieser Seite am leichtesten falsch zu machen. Die eigenen Templates eines bereitgestellten Charts benennen ihre Ressourcen nach der Identität, die die Plattform ihnen übergibt — einem Release-Namen, geschrieben im eigenen Alphabet dieser Plattform statt im oben beschriebenen —, und das helm-Ziel benennt die Workloads, die es synthetisiert, nach demselben Release-Namen. Für Ausgabe, die aus von Ihnen bereitgestellter Quelle gerendert wird, und für eine unter einem solchen Ziel synthetisierte Workload ist {{ .context.instance_id }} daher nicht der Name, den diese Ressourcen tragen, und eine daraus veröffentlichte Adresse benennt nichts, sobald sich die beiden Alphabete unterscheiden. Der Schlüssel, der den Namen der Plattform trägt, und welche Provider einen melden, sind in templates/rendered-resource-names.md beschrieben.
Das Ausschreiben des Trennzeichens kostet Zeichen, und einem längenbegrenzten Namen können sie ausgehen. Das Trennzeichen wird durch eine kurze Escape-Sequenz statt durch ein einzelnes Zeichen ersetzt, sodass eine qualifizierte Identität ausgeschrieben etwas länger ist, als sie in Ihren Dokumenten erscheint. Das spielt nur dort eine Rolle, wo der daraus entstehende Name begrenzt ist: Das Ziel, das eine Komponente rendert, gibt an, wie lang ein Label-Wert sein darf, den es akzeptiert, und wo die ausgeschriebene Identität dies überschreiten würde, bricht der Build ab, statt einen Wert auszugeben, den das Ziel ablehnen würde. Der Abbruch nennt die Länge, in die die Identität selbst passen muss — die Länge vor dem Ausschreiben, sodass ein innerhalb dieser Länge gewählter Name beim ersten Mal funktioniert —, und die Abhilfe besteht darin, die verfassten Teile zu kürzen: den Namen, den das importierende Dokument dem Unteraggregat gibt, oder den eigenen Namen der Komponente darin.
Das Trennzeichen ist der übliche Grund, warum ein Name länger ausgeschrieben wird, als er sich liest, aber nicht der einzige. Zwei Formen, die ein verfasster Name zulässigerweise annehmen darf, können ebenfalls nicht unverändert übernommen werden, weil sie eine Escape-Sequenz mehrdeutig machen würden: ein Name, der auf einen Bindestrich endet, und ein Name, in dem auf einen Bindestrich unmittelbar z folgt. Beide werden auf dieselbe Weise und zu denselben Kosten ausgeschrieben. Jeder andere verfasste Name kommt Byte für Byte unverändert zurück, sodass ein Name aus Buchstaben, Ziffern, Unterstrichen und Bindestrichen zwischen Wörtern von alledem nicht betroffen ist.
Ein Socket-Name im eigenen uses-Block einer Komponente entspricht entweder einem Schlüssel im usesSchema der Katalogentität — einem deklarierten Socket — oder benennt einen Ad-hoc-Socket des Entwicklers selbst, der sich auch für eine Entität bauen lässt, die überhaupt kein usesSchema deklariert; ein Name, der nur eine Bearbeitung von einem deklarierten Socket entfernt ist, erzeugt eine Warnung, die beide Schreibweisen nennt. Das kantenbezogene uses eines Release und das eines Feature-Anhangs dürfen nur einen Socket nennen, den die Entität deklariert, und jeder andere Name schlägt mit einem Validierungsfehler unknown-uses-socket fehl.
Schreibweise von Feldnamen
Die DSL trennt entwicklerseitiges YAML (von Menschen verfasst) von internen Compiler-Verträgen (von Templates und Werkzeugen konsumiert):
- Entwicklerseitiges YAML (camelCase): Mehrwortige Feldnamen in den Schemas von Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest und Plugin verwenden camelCase. Beispiele:
exportedComponents,syncWave,subDirectory,featuresSchema,usesSchema,valuesMapping,injectMapping,executionScope,appliesTo,appliesToAnyOf,conflictsWith. Folgt den Konventionen der Kubernetes-API. - Interne Verträge (snake_case): Mehrwortige Feldnamen im Schema des IR Graph und im Schema des Template Context verwenden snake_case. Benutzerseitige Beispiele, denen Recipe-Autoren begegnen:
instance_id(in.context.instance_id— die Identität der Recipe),inject_raw(in.inject_raw, eine Säule der obersten Ebene neben.injectstatt eines Schlüssels unter.context— der unveränderte Injektionsvertrag),attachment_name(im Kontext eines Anhang-FeatureRecipe — gibt den Slot an, den der Anhang füllt, oder den Namen, unter dem er angehängt wurde). Folgt den Konventionen von JSON API und richtet sich an der Generierung von JSON-Struct-Tags in Go aus. - Einwortige Felder: Unabhängig vom Kontext kleingeschrieben. Beispiele:
values,infra,inject,provides,locals,features,labels,annotations,boundaries,components,subsystems,pipeline,source.
Entwickler begegnen in ihrem verfassten YAML keinem snake_case, und Template-Autoren begegnen in ihren Go-Templates keinem camelCase. Schema-Erweiterungen folgen diesen Konventionen.
Drei Schreibweisen, die sich in einer Anweisung kreuzen
Beim Verfassen von Recipes kreuzen sich routinemäßig alle drei Schreibkonventionen in einer einzigen Anweisung: Das vom Schema definierte DSL-Feld verwendet camelCase, der vom Benutzer verfasste Instanzname verwendet kebab-case oder snake_case, und die Referenz auf den Template-Kontext verwendet snake_case. Autoren, die die Kreuzungen als getrennte Konventionen wahrnehmen, lesen das resultierende YAML mühelos; Autoren, die versuchen, die Schreibweisen als eine einzige Konvention zu erklären, tun sich mit den Grenzen schwer.
Das kanonische Beispiel: das valuesMapping:-Template einer Recipe, das über den Template-Kontext auf die gerenderte Component-Instanz verweist.
# Recipe authored against a Component the developer instantiated as "web-server"# (kebab-case instance name) in their Aggregate.spec: valuesMapping: | # camelCase — schema-defined DSL field name: "{{ .context.instance_id }}" # snake_case — template context # internal contract image: "{{ .values.image }}" # snake_case — template context # internal contractDrei Schreibweisen, eine Anweisung:
valuesMapping— camelCase. Der Name des DSL-Felds, den das Schema für das Mapping-Template der Recipe definiert. Camel, weil das entwicklerseitige YAML der Sprache den Konventionen der Kubernetes-API folgt.web-server(indirekt über die gerenderte Komponente referenziert) — kebab-case. Der vom Benutzer verfasste Instanzname im Aggregate; der Entwickler hat die Form mit Bindestrich gewählt. Könnte ebensoweb_server(snake_case) lauten; beide sind nach dem Instanznamen-Muster gültig.instance_id,image— snake_case. Feldnamen innerhalb des Template-Kontexts (.context.instance_id,.values.image). Snake, weil der IR Graph und der Template-Kontext den JSON-API-Konventionen folgen und sich an der Generierung von JSON-Struct-Tags in Go ausrichten.
Die drei Schreibweisen sind nicht austauschbar. Ein Recipe-Autor, der {{ .context.instanceId }} (camelCase) schreibt, bricht den Build ab: .context deklariert seine Schlüssel, und instanceId gehört nicht dazu, sodass die Referenz abgelehnt wird, bevor etwas gerendert wird, und die Diagnose die Schlüssel auflistet, die .context definiert — siehe errors/fatal-halts.md „Template references a root the render context does not define (Template verweist auf eine Wurzel, die der Render-Kontext nicht definiert)“. Ein Entwickler, der web.server (mit Punkt) schreibt, stößt auf die Ablehnung durch das Instanznamen-Muster, weil der Punkt als Pfadtrennzeichen reserviert ist. Das Ziel der Disziplin: Behalten Sie die drei Konventionen beim Lesen oder Verfassen im Kopf; verlassen Sie sich auf die Grenzen (wo Sie sich im YAML oder Template befinden), um zu wissen, welche Schreibweise gilt.
Von der Plattform definierte Bezeichner
Alles Obige regelt Namen auf der Authoring-Oberfläche — einen Instanznamen, den Sie wählen, ein Schemafeld, das die Sprache für Sie zum Ausfüllen definiert, einen Template-Kontext-Schlüssel, den Sie lesen. Zwei weitere Register regeln die Bezeichner, die die Plattform selbst definiert und die Sie nur zurücklesen oder eintippen. Sie sind getrennt, weil sie unterschiedliche Aufgaben erfüllen, und die Aufgabe bestimmt die Form.
Das beschreibende Register: durchgängig kebab-case. Ein Bezeichner hier sagt in Worten, was er benennt, sodass Sie ihn lesen und danach handeln können, ohne etwas nachzuschlagen. Ein CLI-Flag, die ID einer Publishing-Lint-Regel, ein Diagnoseklassen-Code und der Code, unter dem eine Abbruchbedingung registriert ist, gehören alle dazu.
--no-unsupported-field-warnings # a CLI flag you typecategory-matches-directory # a lint rule id, printed in `aggrega lint` outputunsupported-field # a diagnostic class codeartifact-provenance-skipped # anotherparameter-contract-violation # the code a halting condition is registered underWo eine Diagnoseklasse ein Unterdrückungs-Flag hat, bestehen Code und Flag aus denselben Wörtern in derselben Reihenfolge — unsupported-field wird durch --no-unsupported-field-warnings stummgeschaltet —, sodass die Klasse, auf die Sie gestoßen sind, Ihnen das passende Flag nennt, ohne dass etwas zu übersetzen wäre. Ein Klassen-Code ist der stabile Name, auf den Werkzeuge abgleichen, um einen Befund zu erkennen, ohne seinen Meldungstext zu parsen; die Formulierung der Meldung kann sich verbessern, der Code bleibt.
Das Kurzcode-Register: der Buchstabe E und vier Ziffern. Eine Abbruchbedingung trägt außerdem einen Kurzcode — E0007 —, und er ist der einzige von der Plattform definierte Bezeichner, der nicht kebab-case ist. Der Grund ist seine Position: Er eröffnet jede Abbruchdiagnose, neben der Kategorie, vor der Datei und Zeile, die Sie gleich lesen werden.
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edgeEin beschreibender Code kann dort nicht stehen. Der längste davon würde allein ein schmales Terminal füllen, noch vor der Position, die Ihnen sagt, wo Sie nachsehen müssen. Daher erhält der Anfang einen nach Breite gewählten Bezeichner, und der Kompromiss ist bewusst: Vier Ziffern sagen nichts über eine Bedingung aus, weshalb jeder Kurzcode neben der Bedingung, die er benennt, und dem Text, mit dem diese Bedingung ausgegeben wird, in der Referenz der Fehler-Sentinels veröffentlicht ist. Zitieren Sie einen Kurzcode in einem Bericht, tippen Sie ihn in eine Suche ein und schlagen Sie ihn dort nach.
Beide Register benennen dieselben Bedingungen aus zwei Richtungen, und keines ersetzt das andere. Gleichen Sie auf den beschreibenden Code ab, wenn Sie ein Werkzeug schreiben, das auf eine Bedingung reagiert; zitieren Sie den Kurzcode, wenn Sie mit einer Person über eine Bedingung sprechen.
Dass kebab-case hier und in Instanznamen vorkommt, ist keine Kollision. Beim Instanznamen-Muster geht es darum, was Sie schreiben dürfen — dort sind kebab-case und snake_case beide gültig, und Teams wählen eines davon. Bei diesem Register geht es darum, was die Plattform selbst schreibt, wo es nichts zu wählen gibt: Sie wählen nie die Schreibweise einer Lint-Regel-ID, und die Plattform wählt nie die Schreibweise Ihres Komponentennamens.
Die Schreibweisen der Felder bleiben davon unberührt. Verfasste Schemafelder bleiben camelCase, und Template-Kontext-Schlüssel bleiben snake_case. Keiner der Bezeichner in diesem Register ist ein Feld auf einer der beiden Oberflächen — es sind kurze, stabile Namen für ein Flag, eine Regel oder eine Klasse von Befunden —, sodass ein kebab-case-Diagnosecode nichts darüber aussagt, wie ein Schemafeld geschrieben wird.
Suffix-Disziplin bei der Benennung von Dokumentpfaden
Eine Teilmenge der Felder in der Sprache enthält Dokumentpfad-Werte — Zeichenketten, die auf eine Position in einem anderen Dokument zeigen (den volumes-Abschnitt einer gerenderten Workload, den featuresSchema-Eintrag einer Component, die mappings-Ebene eines Manifest). Die Werte folgen der Syntax von RFC 6901 JSON Pointer — durch Schrägstriche getrennte Tokens, die den Pfad durch das Zieldokument bezeichnen.
RFC 6901 ist die Pfadgrammatik-Grundlage für jede Dokumentpfad-Oberfläche in Aggrega. Der Wasm-Plugin-Vertrag konsumiert JSON-Patch-Dokumente nach RFC 6902, deren Pfade RFC-6901-Pointer sind (gemäß der JSONPatch-Ausgabe der Rolle label-transform in plugins/plugin-contract.md); das Formatstring-Inventar der URI-Grammatik nennt RFC 6901 neben der Go-Template-Syntax und den Sprig-Helfern (gemäß vocabulary/uri-grammar.md „Format-string inventory“); die .locals-Exporte jeder Recipe verwenden RFC 6901, um auf Positionen der synthetisierten Workload zu zeigen, die Wasm-Injector-Plugins in der Plugin-Pipeline über die with-Nutzlast ihres Schritts erhalten. Eine Grammatik, mehrere konsumierende Oberflächen.
Die Suffix-Disziplin bei der Benennung unterscheidet die beiden Authoring-Seiten dieser Pfadwerte durch eine bewusste Aufteilung der Suffixe, die sich am umfassenderen Abschnitt zur Schreibweise von Feldnamen oben orientiert:
- Schemafelder, die RFC-6901-JSON-Pointer enthalten, verwenden das Suffix camelCase
*Path. Die Felder gehören zum entwicklerseitigen YAML-Schema und folgen daher der camelCase-Konvention. Kein Entitätsschema deklariert ein solches Feld; die Dokumentpfade, die ein Autor schreibt, sind die unten aufgeführten.locals-Exportschlüssel. .locals-Exportschlüssel, die RFC-6901-JSON-Pointer enthalten, verwenden das Suffix snake_case*_path. Die Schlüssel gehören zur internen Exportoberfläche der Recipe — gelesen von den nachfolgenden eigenen Templates der Recipe und von einer Wasm-Plugin-Pipeline über diepipeline[].with-Nutzlast, die.localsreferenziert —, daher folgen sie der snake_case-Konvention. Beispiele:volumes_path—.locals.volumes_path: "/spec/template/spec/volumes"stellt die Position des volumes-Arrays der synthetisierten Workload bereit.containers_path—.locals.containers_path: "/spec/template/spec/containers"stellt die Position des containers-Arrays bereit.resource_path—.locals.resource_path: "/resource/aws_s3_bucket/main"stellt einen Terraform-nativen Ressourcenpfad bereit.root_path—.locals.root_path: "/data"stellt den Wurzelpfad bereit, den die Pipe des Renderers konsumiert.
Die beiden Suffix-Konventionen spiegeln die zweistufige Konvention des Abschnitts zur Schreibweise von Feldnamen wider: Vom Schema definierte Felder verwenden camelCase; vom Benutzer verfasste oder Recipe-private Bezeichner verwenden snake_case (oder kebab-case). Die Suffix-Disziplin *Path / *_path macht die Pfadgrammatik-Natur des Werts auf Bezeichnerebene sichtbar — wer eines der beiden Suffixe sieht, weiß, dass der Wert der Syntax von RFC 6901 folgt, ohne den Wert selbst prüfen zu müssen.
Ausgearbeitetes Beispiel: ein Wasm Injector, der die *_path-Exporte einer Recipe konsumiert.
# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumesspec: locals: primary_compute: "worker-container" containers_path: "/spec/template/spec/containers" volumes_path: "/spec/template/spec/volumes"# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe# above realizes. Its templates read `.locals`: an attachment sees the host# Recipe's resolved locals merged with the attachment's own block.spec: pipeline: - id: workload_injector plugin: pipeline-step/k8s-workload-injector:2.0.0 function: inject_secret with: | target_container: "{{ .locals.primary_compute }}" containers_path: "{{ .locals.containers_path }}" volumes_path: "{{ .locals.volumes_path }}"Die *_path-Schlüssel sind Recipe-private Exporte; die Werte containers_path / volumes_path sind RFC-6901-JSON-Pointer-Zeichenketten. Das Injector-Plugin konsumiert die Zeichenketten, um seine JSONPatch-Ausgabe gegenüber dem AST der gerenderten Workload zu positionieren. Die Anbindung erreicht sie über ihre eigene .locals-Säule — es gibt kein Feld .context.uses[].locals, sodass ein Consumer die locals seines Ziels nicht über eine uses-Kante lesen kann; was eine Kante überquert, ist das provides des Ziels.
Für das umfassendere Formatstring-Inventar (Go-Template-Syntax, Sprig-Funktionen, JSON Pointer neben SemVer-Regex und Label-Selektor-Grammatik) siehe vocabulary/uri-grammar.md „Format-string inventory“. Für die Oberfläche des Wasm-Plugin-Vertrags, die RFC-6902-Patches konsumiert, die über RFC-6901-Pointer adressiert werden, siehe plugins/plugin-contract.md.
Kommentarsyntax
Kommentarzeichen hängen von der umgebenden Sprache ab:
- YAML-Kontext (die Standard-Authoring-Oberfläche für jede Aggrega-Entität): Verwenden Sie
# - Go-Template-Kontext (innerhalb von
valuesMapping:-Blockskalaren einer Recipe,injectMapping:-Blockskalaren eines FeatureRecipe, Mapping-Einträgen einer MappingLibrary,assertions:-Rümpfen von Assertion-Blöcken): Verwenden Sie{{/* ... */}}für Template-Kommentare, die die Template-Engine erkennt und beim Rendern entfernt, oder#für Kommentare auf YAML-Ebene außerhalb des Template-Rumpfs.
Schemas in Kompaktform unter schema:, usesSchema:, featuresSchema: und parameters: sind durchgehend YAML; die feldbezogene Annotation description: ist die dokumentierte Oberfläche für Inline-Felddokumentation (port: { type: integer, description: "TCP listen port" }).