Recipe
Die konzeptionelle Rolle der Recipe-Entität (die von Ops verfasste Übersetzungsvorlage, die den Developer Intent in das physische Format abbildet) ist in architecture/04-entity-taxonomy.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche des Recipe — den Zeiger (source), den Mapper (valuesMapping:), die native IaC-Unterstützung und ausgearbeitete Beispiele.
Die Recipe-Architektur: Zeiger und Mapper
Ein Recipe erfüllt genau zwei Funktionen:
- Der Zeiger (
source): Teilt dem Compiler genau mit, wo der Infrastrukturcode liegt. - Der Mapper (
valuesMapping): Injiziert den abstrakten Kontext von Aggrega in die spezifischen Variablen, die der zugrunde liegende Code erwartet. Das Feld ist eine einzige Go-Template-Oberfläche mit drei Authoring-Modi — Inline-Block-Scalar, Datei-$import:oder Bibliotheks-$import:—, die anhand der Form des Inhalts ausgewählt werden. Siehe Das FeldvaluesMapping— drei Authoring-Modi weiter unten.
Da ein Recipe strikt 1:1 einer Render-Fähigkeit entspricht, wird diese Fähigkeit (spec.capability) explizit auf oberster Ebene deklariert, sodass der Go-Compiler genau weiß, welches nachgelagerte Wasm-Rendering-Plugin er aufrufen muss.
spec.implements deklariert, welchen Komponententyp des Katalogs das Recipe implementieren kann. Der Compiler verwendet es, um Manifest-Zuordnungen zu überprüfen (das implements eines zugeordneten Recipe muss dem zugeordneten Typ entsprechen) und um Kandidaten vorzuschlagen — die Recipes, die in einer Diagnose zu einer fehlenden Zuordnung aufgeführt und in der Editor-Vervollständigung zuerst gereiht werden. Es löst nie einen Build auf: Die Manifest-Zuordnung ist die explizite Deployment-Entscheidung des Benutzers, festgeschrieben in der Lockfile. Ein Recipe, dessen implements unversioniert, exakt oder ein Major-kompatibler Bereich ist, kann sich dennoch nur für einen Typ anbieten; der Benutzer legt die Wahl fest. FeatureRecipe.spec.implements erfüllt dieselbe Rolle für Feature-Typen.
A. Wasm-gesteuerte Quellschemas
Um Implementierungsvorlieben aus dem Compiler herauszuhalten, ist der source-Block kein fester Satz von Infrastrukturfeldern. Das Feld source unterstützt zwei Formate:
- Der universelle String (schnell und sauber): Am besten für lokale Pfade, OCI-Artefakte und Git-Repositories. Der Compiler leitet die Abrufmethode aus Präfix und Suffix des Strings ab (
./src,https://github.com/example/module.git,oci://...): Eine URL, die auf.gitendet oder mitgit://oderssh://geschrieben ist, ist ein Git-Repository, das an seinem Standard-Branch abgerufen wird, und einehttps://-URL, die weder ein Repository noch ein.tgz-Chart oder.yaml-Fragment bezeichnet, wird als mehrdeutig abgelehnt. - Das offene strukturierte Objekt: Ein offenes Dictionary (
additionalProperties: true), dessen Schlüssel providerdefiniert sind und den Templates des Recipe als.source.*bereitgestellt werden (zum Beispiel.source.chart). Die Designabsicht ist, dass der WebAssembly-Socket jedes Providers seine eigene Quellform definiert und validiert (z. B.registry/chart/appVersionfür Helm).
Was der Kern auflöst. Kein Provider validiert eigene Quellschlüssel. Eine abgerufene Quelle wird durch eine integrierte Identität aufgelöst, deren kind einen Resolver auswählt — helm-oci-chart, helm-https-chart, compose-https-fragment und git-repository. Eine zum Abruf bestimmte Quelle muss kind und url enthalten; welche weitere Koordinate den Inhalt auswählt, hängt vom Kind ab. Die Chart- und Fragment-Kinds nehmen version an und pinnen sie wie geschrieben. git-repository nimmt ref an — ein Tag, einen Branch oder einen Commit — und optional module_subdir, das das Verzeichnis innerhalb des Repositorys benennt, das das Artefakt ist; da nur ein Commit Inhalte benennt, die nicht umgelenkt werden können, wird die Referenz zur Lock-Zeit aufgelöst, und die Lockfile hält sowohl die verfasste Referenz als auch den Commit fest, zu dem sie aufgelöst wurde. Ein module_subdir, das wie geschrieben über das Repository hinaus aufsteigt — ein Backslash zählt als Trennzeichen —, wird abgelehnt, bevor irgendetwas abgerufen wird. Das Repository wird aus seinem eigenen Checkout archiviert: Ein symbolischer Link, den es committet, wird als die Datei oder das Verzeichnis archiviert, auf das er zeigt, sofern dieses innerhalb des Repositorys liegt, und einer, der aus ihm herausführt, bricht den Pull ab und nennt den Link anhand seiner Stelle im Repository. Eine strukturierte Quelle, deren url: einen Dateisystempfad benennt, wird nicht abgerufen: Sie wird unter denselben Bedingungen wie ein einfacher Pfad-String von der Festplatte gelesen, wobei eine relative url: an dem Verzeichnis verankert ist, das die deklarierende Entitätsdatei enthält. Eine strukturierte Quelle, die kind/url auslässt, wird ebenfalls nicht abgerufen, und falls ein Abruf beabsichtigt war, bricht der Build beim Abstieg in die Quellen zur Lock-Zeit deutlich ab, statt stillschweigend ins Leere aufgelöst zu werden. Der Inhalt wird immer vorab gepinnt; der Compiler ruft niemals Live-Laufzeitzustand ab.
Was neben dem Recipe gepinnt wird. Für eine abgerufene Quelle, deren kind, url, chart, module_subdir, version und ref alle ausgeschrieben statt per Template gefüllt sind, hält aggrega pin den Digest dessen, was es abgerufen hat, in entity.lock fest, einer Datei im Recipe-Verzeichnis, die Sie daneben committen. Das Pinnen ist ein Schritt des Recipe-Autors und benötigt kein Release; ein Pull über ein Recipe, dessen Lock den Pin nicht festhält, bricht ab und nennt ihn, es sei denn, der Pull wird aufgefordert, denselben Schritt auszuführen. Ein Build vergleicht diesen Digest mit dem, den die Lockfile des Release für dieselbe Quelle festhält, und bricht ab, wo die beiden voneinander abweichen — außer bei einer Quelle, die mit einem git-ref: geschrieben ist, deren Zeile beim Commit festgehalten wird, zu dem die Ref aufgelöst wurde, und die nicht verglichen wird. Eine abgerufene Quelle, deren Koordinaten aus einem Template gefüllt werden, wird stattdessen pro Release gepinnt, in der Lockfile jedes Release. Eine Quelle, die ein Verzeichnis oder eine Datei neben dem Recipe benennt, wird nicht abgerufen: aggrega pin hält einen Digest pro Datei fest, die sie zu dem beiträgt, was eine Veröffentlichung des Recipe enthält — jede Datei im Recipe-Verzeichnis, bei einer als Template geschriebenen Quelle —, und sobald der Lock sie festhält, vergleicht ein Build die Quelle mit ihnen, bevor der Provider sie liest, und bricht bei einer seit dem Pin hinzugefügten, geänderten oder entfernten Datei ab — mit E0305 oder zuerst mit E0130, wo die vor der Änderung geschriebene Lockfile des Release das Recipe anhand dessen festhält, was es enthält. Ein Lock, der für eine solche Quelle keinen Pin festhält, lässt einem Build nichts zum Vergleichen, und ein Pull oder eine Veröffentlichung, die nicht pinnt, lehnt sie ab. Die Recipe-Datei selbst wird nie beschrieben. aggrega pull beschreibt die Datei und wie auf jeden Abbruch zu reagieren ist.
spec.capability kann einen Versions-Pin in den Formen tragen, die implements annimmt — exakt (helm:<version>) oder ein Caret-Bereich (helm:^<version>) —, und wählt damit aus, welche Version des Provider-Plugins das Recipe rendert; ein Pin, den keine verfügbare Version erfüllt, bricht den Build ab. Ohne Pin (spec.capability: "helm") rendert es die höchste verfügbare Version. Die verfügbaren Versionen sind die, die aggrega plugin list anzeigt: Die in aggrega integrierten Provider tragen die eigene Version des Compilers. Der Pin ist nicht Teil des Recipe-Namens: Ein Manifest ordnet ein Recipe, das capability: "compose:1.2.3" deklariert, als compose/<name>:<version> zu, genau wie ein ungepinntes, und eine Änderung des Pins benennt es nie um; ein Zuordnungswert, der den Pin in den Namen schreibt (compose:1.2.3/<name>:<version>), wird als fehlerhafte Recipe-Referenz (E0095) abgelehnt, bevor irgendetwas nachgeschlagen wird.
Denkmodell: spec.capability benennt das gewünschte Ausgabeformat (z. B. helm, terraform, compose); der Compiler löst es zu dem Wasm-Plugin auf, das dieses Format rendert (z. B. provider/helm). Sie deklarieren das Format; Aggrega bindet das Werkzeug.
B. Kontextinjektion: Die semantische Mapping-Schicht
Um zu verhindern, dass der Compiler gefährliche, nicht deterministische Deep-Merges über mehrere Umgebungen hinweg durchführt, erlaubt ein Recipe für seine Mapping-Schicht nur eine einzige Quelle der Wahrheit.
Ops-Engineers verfassen den Mapping-Inhalt, um abstrakten Kontext zu übersetzen, bevor das Wasm-Rendering-Plugin ausgeführt wird. Die Mapping-Sprache ist Go-Template (text/template + Sprig); die Sprig-Bibliothek ist vorregistriert; die Standardaktionen define und template werden unterstützt, und include ist nicht registriert.
| Feldname | Geltungsbereich und Ausführungsphase | Bester Anwendungsfall |
|---|---|---|
injectMapping (nur FeatureRecipe) | Abfangen vor dem Rendern. Wird im Go-Speicher vor dem Basis-Recipe ausgewertet. Führt sein Ausgabe-Dictionary nativ per Deep-Merge strikt über die .context.inject-Pipe des Aufrufers. Absichtlich nicht im Basisschema Recipe enthalten — siehe entities/featurerecipe für die architektonische Begründung. | Gezieltes Umschreiben injizierter env-Variablen oder Formatieren von FQDNs für einen Aufrufer, ohne Wasm-JSONPatch zu benötigen. |
valuesMapping | Basis-Rendering (Go-Template). Wird ausgewertet, um Variablen in das zugrunde liegende source-Infrastruktur-Chart/-Modul abzubilden. Ein einziges Feld, drei Authoring-Modi (inline, Datei-$import:, Bibliotheks-$import:). Den Auswahlmechanismus beschreibt der Unterabschnitt weiter unten. | Abbilden von Standardvariablen (etwa Replicas oder Image-Tags) in ein Helm-Chart direkt im Recipe-YAML oder Referenzieren eines gemeinsamen Templates über $import: zur Recipe-übergreifenden Wiederverwendung. |
Hinweis: injectMapping ist ausschließlich FeatureRecipes vorbehalten und trennt das Abfangen von Variablen von valuesMapping. Das valuesMapping des Basis-Recipe verbraucht unwissentlich die umgeschriebenen .context.inject-Strings, die von injectMapping-Blöcken des FeatureRecipe erzeugt werden, sodass beide entkoppelt bleiben.
Ein Schlüssel, den valuesMapping als null schreibt, erreicht den Provider als null, und was er dort bewirkt, bestimmt der Provider; daher gibt jede Provider-Seite es an: helm entfernt den Standardwert des Charts für diesen Schlüssel, helm-chart schreibt ihn in die Values des Umbrella-Charts, compose schreibt ihn in die Compose-Datei, terraform schreibt ihn als null-Modulargument, und cloudformation lehnt ihn ab.
Das Feld valuesMapping — drei Authoring-Modi
Das valuesMapping: eines Recipe ist eine einzige Go-Template-Oberfläche, die drei Auswahlmodi akzeptiert. Der Compiler wählt anhand der Inhaltsform des Feldes aus; eine $mode:-Annotation ist nicht nötig.
Modus 1: Inline-Go-Template (YAML-Block-Scalar). Der Wert des Feldes ist ein String in der YAML-Block-Scalar-Form |:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}Der Inline-Modus ist die typische Authoring-Form für Recipes, deren Mapping-Inhalt klein bis mittelgroß ist (unter ~50 Zeilen). Der Template-Körper steht inline mit dem Rest der Recipe-Hülle; der Inhalt des Recipe ist in sich abgeschlossen.
Modus 2: Datei-$import:. Der Wert des Feldes ist eine Map, die nur $import: mit einem lokalen Dateipfad enthält:
spec: valuesMapping: $import: ./mappings/api-server.tmplDer Compiler lädt den Inhalt der Datei (ein Go-Template), rendert ihn gegen den Standard-Template-Kontext des Recipe und behandelt das Ergebnis als Mapping-Ausgabe. Die Pfadauflösung erfolgt relativ zum Recipe-Verzeichnis — ein relativer Pfad ist an dem Verzeichnis verankert, das die deklarierende recipe.yaml enthält, nicht an dem Verzeichnis, aus dem der Build aufgerufen wird —, und der Pfad muss innerhalb dieses Verzeichnisses bleiben, wie Inhaltspfade bleiben im eigenen Verzeichnis des Recipe erklärt. Der Dateimodus eignet sich für mittelgroßen bis großen Mapping-Inhalt (~50+ Zeilen) und für Review-Abläufe, in denen Mapping-Änderungen als eigenständige Datei-Diffs erscheinen.
Modus 3: Bibliotheks-$import:. Der Wert des Feldes ist eine Map, die nur $import: mit einer Identitätsreferenz per bloßem Namen auf einen MappingLibrary-Eintrag enthält:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreDer Compiler löst die Referenz gegen die aufgelöste MappingLibrary-Menge auf (den lokalen Katalog plus alle in der Lockfile gepinnten Bibliotheken), lädt den Inhalt des Eintrags und behandelt ihn als Mapping-Ausgabe; ein Eintrag, dessen Körper selbst ein $import: an der Feldwurzel ist, wird rekursiv aufgelöst. Die Referenz enthält keinen Registry-Host — der Bibliotheksname wird über die Identität aufgelöst, und die Version stammt aus der Lockfile pro Release, mit einer optionalen Mindestversion :<version> (<Library>:<version>#/mappings/<entry>). Bibliotheksinhalt teilt den Standard-Template-Kontext des Recipe. Der Bibliotheksmodus eignet sich für Recipe-übergreifende Wiederverwendung — Mapping-Muster, die in vielen Recipes wiederkehren (mehrere Datastore-Recipes, die Datastore-Hilfslogik teilen; mehrere Helm-Provider-Recipes, die Pod-Template-Muster teilen). Die MappingLibrary-Entität bietet Versionierung, Lockfile-Pinning und Darstellung in der Hub-Oberfläche.
Auswahlregeln. Der Compiler durchläuft den YAML-Knoten und wählt anhand der Inhaltsform aus:
- Ist der Knoten ein String-Skalar, wird der Inline-Modus (Modus 1) gewählt.
- Andernfalls ist der Knoten eine Map; es wird auf den Schlüssel
$import:geprüft. - Ist der Wert von
$import:eine Bibliotheksreferenz per bloßem Namen (<Library>#/mappings/<Entry>, optional mit einer Untergrenze:<version>), wird der Bibliotheksmodus (Modus 3) gewählt. - Andernfalls (ein lokaler Dateipfad) wird der Dateimodus (Modus 2) gewählt.
- Jede andere Form (eine Map ohne
$import:, eine Map mit zusätzlichen Schlüsseln neben$import:usw.) erzeugt einen Fehler zur Build-Zeit.
Nur $import: mit einer einzigen Quelle. $import: akzeptiert eine einzige Quelle. Das Zusammenführen mehrerer Quellen wird bei valuesMapping: nicht unterstützt. Ein Recipe, das mehrere Mapping-Fragmente zusammensetzen muss, verwendet einen MappingLibrary-Eintrag mit interner Go-Template-Komposition über define / template, eine lokale Datei mit Go-Template-Direktiven template, die benachbarte Dateien aufrufen, oder Inline-Komposition für kurze Inhalte. Siehe entities/mappinglibrary für die Bibliotheksentität und vocabulary/cross-document-ref für die allgemeinere Unterscheidung $ref: / $import:.
Herkunft. Fehlermeldungen aus fehlgeschlagenem Template-Rendering nennen je nach Modus die passende Herkunft: Inline-Templates nennen Datei:Zeile des Recipe, an der der Block-Scalar beginnt; Datei-Importe nennen den Inhalt der importierten Datei; Bibliotheksimporte nennen die Quellposition des MappingLibrary-Eintrags, mit der hostlosen Bibliotheksidentität (<Library>#/mappings/<entry>) als kanonischem Verweis für stabile Referenzen — ein Registry-Host in einer Referenz wird abgelehnt, sodass der physische Speicherort nie in den Verweis gelangt.
C. Native IaC-Unterstützung
Ein Ops-Team, das seinen eigenen Infrastructure-as-Code mitbringt, hält ihn im eigenen Verzeichnis des Recipe — ein Modul- oder Template-Verzeichnis wie ./src, benannt durch source: — oder ruft ihn mit einer strukturierten source: ab (ein Terraform-Modul aus seinem Git-Repository, mit kind: git-repository) oder schreibt ihn als Template-Körper unter artifacts:. Die Mapping-Schicht (valuesMapping: — inline, Datei-Import oder Bibliotheks-Import) liefert diesem Code den abstrakten Kontext, und der Provider gibt das Ergebnis im eigenen Format des Ziels aus; keine Konfigurationssprache wird in eine andere umgewandelt:
- Terraform: Ein Modul wird Datei für Datei übernommen, und ein verfasster Körper wird genau so ausgegeben, wie er geschrieben ist, natives HCL (
main.tf) ebenso wie Terraform JSON (.tf.json) — dieterraform-CLI liest beides. Die Root-Konfiguration der Boundary,aggrega.modules.tf, ruft das Verzeichnis jeder Komponente alsmodule-Block auf, und dievaluesMapping:-Ausgabe eines Moduls mit Quelle wird zu den Argumenten dieses Blocks. Siehe den terraform-Provider. - CloudFormation: Ein Template mit Quelle, YAML oder JSON, und die Ressourcenfragmente, die ein Recipe verfasst, werden zu Langform-JSON normalisiert und pro Boundary zu einem Stack-Template zusammengeführt, wobei die
valuesMapping:-Ausgabe die Parameter füllt, die ein Template mit Quelle deklariert. Siehe den cloudformation-Provider.
Ein Wert, der erst existiert, sobald die Infrastruktur angewendet wurde, bleibt ein Zeiger, den das Ziel auflöst — eine Terraform-Interpolation ${ ... }, ein Ref oder Fn::GetAtt von CloudFormation — und wird nie zur Build-Zeit ausgewertet.
Beispiel A: Das entfernte Helm-Chart (Inline-Mapping und Locals-Vertrag)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Beispiel B: Das lokale Terraform-Modul (Datei-Mapping)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Beispiel C: Konkretes Component-Recipe (bindet Infrastruktur) Ops bildet die generische Schnittstelle auf die physische Realität ab. (Hier werden die L4-Netzwerkdetails gebunden — entweder fest codiert oder, wie beim Proxy-Port unten, aus dem infra-Block übernommen, den das Release ausfüllt.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Disziplin bei der Benennung von Cloud-Ressourcen.
Recipes, die Namen von Cloud-Ressourcen ausgeben — S3-Bucket-Namen, RDS-Datenbankkennungen, IAM-Rollennamen, CloudFormation-Stack-Namen und jedes andere Feld, dessen Wert beim Cloud-Anbieter einen globalen Namensraum belegt —, müssen {{ .metadata.release_name }} und/oder {{ .context.instance_id }} in den gerenderten Namen einfügen, um Kollisionen zu vermeiden, wenn dasselbe Recipe über mehrere Releases oder Komponenteninstanzen hinweg läuft. bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" aus Beispiel B ist das kanonische Muster.
Die Disziplin gilt überall dort, wo ein einziger globaler Namensraum den Namen einschränkt. AWS-S3-Bucket-Namen teilen sich einen globalen Namensraum über alle Konten einer Region hinweg; zwei Releases desselben Aggregate (prod-billing und staging-billing) können nicht beide Buckets namens customer-data bereitstellen — das zweite Deployment schlägt zur Laufzeit mit einer Ablehnung auf AWS-Seite fehl. Das Einfügen von release_name unterscheidet das Release; das Einfügen von context.instance_id unterscheidet pro Komponenteninstanz; das Einfügen beider unterscheidet pro Komponente und pro Release.
Was der Compiler prüft und was nicht. Der Compiler untersucht die Ausgaben von valuesMapping: nicht auf Felder mit Cloud-Ressourcennamen ohne diese Interpolationen. Die Disziplin wird von Recipe-Autoren getragen (die wissen, welche Felder global eindeutige Ressourcen für den Ziel-Provider benennen) und von Reviewern (die Muster unbenannter Ressourcen beim PR-Review erkennen). Ein Linter-Plugin könnte Recipes markieren, deren valuesMapping:-Ausgaben auf Felder mit Cloud-Ressourcennamen ohne release_name- / instance_id-Interpolation verweisen; der Linter-Socket wird ausgeliefert und läuft über aggrega lint (siehe plugins/plugin-contract.md „Platzierungskriterium: der Linter-Socket gegenüber den Verdict-Rollen der Governance“), und keine der Regeln des veröffentlichenden Linters prüft dies.
Diese Disziplin ist einer von mehreren Gesellschaftsverträgen, die per Konvention getragen werden — eine Authoring-Disziplin, die Autoren aus der Dokumentation lernen statt durch Durchsetzung des Compilers. Siehe vocabulary/social-contracts.md für die vollständige Liste der Konventionen und die architektonische Begründung für die Einstufung jedes Gesellschaftsvertrags.
Templating des Feldes source. Das Feld source eines Recipe ist selbst eine Templating-Oberfläche. Beide Formen von source akzeptieren Go-Templates: die universelle String-Form
source: "{{ optional .infra `module_path` \"./src\" }}"und die strukturierte Objektform (jedes Unterfeld mit String-Wert wird als Template ausgewertet; Unterfelder ohne String-Wert werden unverändert durchgereicht). Was ein Source-Template lesen darf, hängt davon ab, ob die Source ein entferntes Artefakt benennt. Die Koordinate einer entfernten Source — version, chart, ref und module_subdir eines strukturierten Blocks, der eine Registry, ein Chart-Repository oder ein Git-Repository benennt — wird ausgewertet, wenn aggrega pull das Artefakt auflöst, um es zu pinnen, und zwar ausschließlich gegen .values, .infra und .locals, mit den eigenen Helfern von Aggrega (optional, capitalizedWords und index) und keiner der Funktionen von Sprig. .context ist auf dieser Oberfläche nicht vorhanden, sodass die Frage, welches Artefakt für eine Komponente gepinnt wird, von den values und infra entschieden wird, die sie erhält, und nie von ihrem Instanznamen. Die dort ausgewerteten locals:-Einträge sind diejenigen, die diese Felder lesen, und diejenigen, die ein solcher Eintrag seinerseits liest: Ein Eintrag, den kein Source-Feld liest, wird beim Auflösen der Source nicht ausgewertet, sodass ein Local, das nur der Render benötigt — eines, das eine Sprig-Funktion aufruft oder .context.instance_id liest —, das Pinning nicht beeinflusst und ausgewertet wird, wenn der Knoten gerendert wird. Ein Feld, das .locals auf eine Weise liest, die keinen einzelnen Eintrag benennt, etwa {{ index .locals "version" }}, lässt jeden Eintrag auswerten. Eine Source, die einen Pfad im Workspace benennt, wie die obige, wird nicht für das Pinning aufgelöst: Ihr Template wird ausgewertet, wenn der Knoten gerendert wird, gegen denselben in sich geschlossenen Kontext wie die locals eines Recipe — .context.instance_id, .values, .infra und .locals, den gesamten aufgelösten Block des Knotens —, sodass sie dieselben Referenzwurzeln zulässt und ablehnt wie ein locals:-Eintrag, mit einem Unterschied zu ihren Gunsten: Sie darf jeden Eintrag lesen, den der Block deklariert, nicht nur die Einträge darüber. Eine entfernte Koordinate darf ebenso jeden Eintrag lesen, den der Block deklariert. .provides ist in keinem der beiden Kontexte vorhanden, und ein Source-Template, das auf die provides seines eigenen Knotens zugreifen will, bricht den Build ab und benennt die betreffende Referenz. Das ist eine feste Eigenschaft der Oberfläche und keine Lücke, die auf spätere Arbeit wartet — die locals eines Knotens werden vor seinen provides aufgelöst, damit provides: .locals lesen kann, und ein Source-Template liest dieselben aufgelösten locals, statt auf provides vorzugreifen. Referenzen auf .context.inject und .context.uses sind aus denselben Gründen der Abgeschlossenheit verboten; der Source-URI muss aufgelöst sein, bevor die Topologie-Pipe befüllt wird und bevor irgendetwas nachgelagert das Chart, das Modul oder den Artefakt-Body lädt, auf den der URI zeigt. Die vollständigen Verfügbarkeitsregeln und die Begründung der verbotenen Referenzen stehen in Zeile #5 der Template-Expansionsmatrix. Der kanonische Anwendungsfall ist ein von der Component bereitgestellter infra.source_version-Override, der in das Versionsfeld der Source durchgereicht wird — siehe entities/component „Die Säule infra“ —, sodass ein Katalog ein Recipe nicht bei jedem kompatiblen Upstream-Versionssprung neu veröffentlichen muss.
Übersicht der Schemata des Feldes source. Das Feld source: akzeptiert im Schema mehrere Formvarianten. Die Laufzeitunterstützung jeder Variante unterscheidet sich je nach Provider; die folgende Tabelle dokumentiert, was jede Form bewirkt.
| Form | Beispiel | Status |
|---|---|---|
| Einfacher relativer Dateisystempfad | source: "./charts/postgres" | available — jeder ausgelieferte Provider (helm, helm-chart, compose, terraform, cloudformation) akzeptiert einen einfachen Dateisystempfad als String. |
| Einfacher absoluter Dateisystempfad | source: "/abs/path/to/chart" | accepted but blocked — das Schema akzeptiert ihn, und jeder Befehl, der das Recipe liest, lehnt ihn ab: Ein absoluter Pfad benennt einen Ort auf dem Rechner, auf dem er geschrieben wurde, statt Inhalt im eigenen Verzeichnis des Recipe, daher würde er nicht mit dem Recipe mitreisen. Verschieben Sie das Chart in das Verzeichnis des Recipe und benennen Sie es relativ dazu; siehe Inhaltspfade bleiben im eigenen Verzeichnis des Recipe. |
| Leerer String | source: "" | accepted but blocked — das Schema akzeptiert den leeren String, und jeder Befehl, der das Recipe lädt, lehnt ihn beim Lesen des Recipe ab, weil ein leerer String keinen der beiden Modi benennt. Die Ablehnung benennt die Mehrdeutigkeit zusammen mit den zwei Möglichkeiten, sie aufzulösen: das Feld für den Modus ohne Source weglassen oder ihm für den Modus mit Source einen echten Pfad oder URI geben. aggrega validate <recipe-file> meldet ihn für das Recipe, und aggrega pull, aggrega build und aggrega validate --release melden ihn für ein Release, das das Recipe erreicht. Siehe errors/fatal-halts.md „Recipe source: is an empty string (Das Feld source des Recipe ist ein leerer String)“. |
Strukturiertes Objekt, dessen url: ein Transportschema trägt | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — der eingebaute Source-Resolver liest die Form {kind, url, version, chart, ref, module_subdir} (das Schema von url: wählt die Art — oci:// → OCI-Chart, https://….tgz → Chart-Archiv, https://-Repository-Wurzel zusammen mit chart: → Repository-Chart — oder man benennt sie mit kind:), holt und pinnt das Artefakt bei aggrega pull, und der Build extrahiert es aus dem Cache. Ein Chart lokal zu vendoren wird als Alternative unterstützt und ist nicht erforderlich. Das Schema akzeptiert ein offenes strukturiertes Objekt. Siehe providers/helm.md „source:-Schlüsselsatz“. |
Strukturiertes Objekt, dessen url: einen Dateisystempfad benennt | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — ein url: ohne Transportschema benennt einen Pfad, daher wird nichts geholt und nichts gepinnt; der Build liest den Inhalt von der Festplatte. Ein relativer url: wird an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, und einer, der dieses Verzeichnis verlässt — ein absoluter eingeschlossen —, wird abgelehnt: dieselbe Lesart, die die beiden Zeilen mit einfachem Pfad oben erhalten, und die Form, in der Sie ihn geschrieben haben, ändert daran nichts. Nur url: entscheidet, von wo der Inhalt gelesen wird; die anderen Felder wählen aus, was geholt würde, und erreichen die Templates des Recipe weiterhin als .source.*. |
OCI-URI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — Designziel für die Verteilung von Katalogen. Der heutige dreistufige Resolver (die Dateien, die ein Release per Pfad benennt, Workspace-Kataloge, entfernte OCI-Registry) ist unter architecture/13-catalog-and-registry.md dokumentiert; der Resolver auf Entitätsebene verarbeitet OCI-URIs über diese Kaskade, doch die OCI-Form des Feldes source: pro Recipe ist in den Providern heute nicht angebunden. |
Andere URL-Schemata (https://, git+https:// usw.) | (zur Veranschaulichung) | planned — als Designabsicht in der Roadmap der Architektur für austauschbare Sources dokumentiert; heute keine Unterstützung durch einen Provider. |
Wie ein source:-Pfad verankert wird. Die Verankerung gilt für Dateisystempfade und für nichts anderes, und sie gilt unabhängig davon, welche der beiden Formen den Pfad trägt. Ein relativer Pfad wird an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, und ein Pfad, der dieses Verzeichnis verlässt — ein absoluter Pfad eingeschlossen —, wird abgelehnt, wie Inhaltspfade bleiben im eigenen Verzeichnis des Recipe erklärt. Eine Referenz mit einem Transportschema — oci://, https://, http://, git://, ssh://, git+ssh:// oder jede Referenz, die auf .git endet — benennt etwas, das geholt werden soll, statt eines Pfades, daher wird sie genau so durchgereicht, wie Sie sie geschrieben haben, und nie mit einem Verzeichnis verbunden.
In der strukturierten Form ist der Pfad das Feld url:, und er wird auf dieselbe Weise gelesen: Ein relativer url: wird an dem Verzeichnis verankert, das die recipe.yaml enthält, einer, der dieses Verzeichnis verlässt, wird abgelehnt, und einer mit einem Transportschema wird geholt. Jedes andere Feld einer strukturierten source: wird unverändert durchgereicht, die vom Provider definierten eingeschlossen.
Eine als Template geschriebene source: wird gegen den Wert verankert, den das Template erzeugt, nicht gegen den eigenen Text des Templates. Ein Template benennt nichts, bevor es ausgewertet wurde, daher wird die obige Lesart auf sein Ergebnis angewendet: Ein Ergebnis, das ein relativer Pfad ist, wird an dem Verzeichnis verankert, das die recipe.yaml enthält, eines, das dieses Verzeichnis verlässt — ein absoluter Pfad eingeschlossen —, bricht den Build ab, und eines mit einem Transportschema wird durchgereicht und geholt. Ein Template kann daher jede der Formen aus der obigen Übersicht erzeugen, und jede wird genau so behandelt, wie es derselbe wörtlich geschriebene Wert würde; der Unterschied liegt nur darin, wann der Pfad beurteilt werden kann, was bei einem Template der Zeitpunkt ist, zu dem der Build es auswertet, und nicht der, zu dem das Recipe gelesen wird.
Ein Template, das nichts erzeugt — ein leeres Ergebnis —, lässt das Recipe ohne Source, was dem Modus ohne Source entspricht. Das ist etwas anderes, als selbst source: "" zu schreiben, was keinen der beiden Modi benennt und abgelehnt wird; siehe die Zeile der Übersicht oben.
Die Übersicht ist die kanonische Referenz dafür, was Autoren in source: angeben können; ihre Bezeichnungen sind die, die 10-status.md definiert.
Inhaltspfade bleiben im eigenen Verzeichnis des Recipe
Der Inhalt eines Recipe liegt im eigenen Verzeichnis des Recipe, weil jede Datei, die eine Veröffentlichung davon mitführt, von dort genommen wird. Jeder Pfad, den ein Recipe für Inhalt schreibt, den es mitführt — seine source:, ob als einfacher Pfad oder als url: der strukturierten Form, und jede Datei, die seine Einträge in valuesMapping:, workload: und artifacts: mit $import: importieren —, wird gegen das Verzeichnis gelesen, das die recipe.yaml enthält, und muss darin bleiben. Diese Pfade sind auch das, was eine Veröffentlichung mitführt: Die Dateien, die sie benennen, reisen mit dem Recipe, und sonst nichts aus seinem Verzeichnis (siehe aggrega push). Ein Pfad, der das Verzeichnis verlässt, zeigt auf eine Datei, die nicht mit dem Recipe reisen würde, sodass die Datei für den, der es verwendet, nicht vorhanden ist, und ein darüber erfasster Pin würde für Bytes bürgen, die dieser nicht beschaffen kann.
Zwei Formen verlassen das Verzeichnis, und beide werden abgelehnt:
- ein Pfad, der darüber hinaus aufsteigt, etwa
../shared/charts/app; - ein absoluter Pfad, etwa
/opt/charts/app, der einen Ort auf dem Rechner benennt, auf dem er geschrieben wurde.
Ein Pfad, der aufsteigt und wieder hineinführt, ist ein gewöhnlicher Pfad innerhalb des Verzeichnisses: ./charts/../values.tmpl benennt die values.tmpl neben dem Recipe. Beurteilt wird, wo der Pfad landet, gemessen vom Verzeichnis des Recipe aus, ohne es zu verlassen — daher wird auch ein Aufstieg nach außen, der auf dem Rückweg das Verzeichnis erneut benennt, etwa ../1.0.0/values.tmpl in einem Verzeichnis namens 1.0.0, abgelehnt. Der eigene Name des Verzeichnisses reist nicht mit: Ein veröffentlichtes Recipe wird aus einem Verzeichnis gelesen, das der Cache des Verbrauchers benennt, wo dieser Name nichts findet.
Wo er abgelehnt wird. Jeder Befehl, der das Recipe liest, lehnt einen solchen Pfad beim Lesen ab, bevor irgendetwas geholt, gerendert oder veröffentlicht wird: aggrega validate, über den Katalog oder über die eigene Datei des Recipe, aggrega pull, aggrega build, aggrega pin und aggrega push. Eine als Template geschriebene source: benennt nichts, bevor der Build sie auswertet, daher wird ein Template, das einen Pfad außerhalb des Verzeichnisses erzeugt, vom Build abgelehnt, in dem Moment, in dem der Wert existiert. Der Abbruch ist A path names content outside the entity’s own directory (Ein Pfad benennt Inhalte außerhalb des eigenen Verzeichnisses der Entität), und er benennt den Pfad, den Sie geschrieben haben.
Was stattdessen zu tun ist. Legen Sie die Datei in das Verzeichnis des Recipe oder in ein Verzeichnis darunter, und benennen Sie sie relativ zum Recipe: ./charts/app, ./extras/netpol.yaml. Ein Chart, das mehrere Recipes verwenden, wird in das Verzeichnis jedes Recipe kopiert, da jedes Recipe für sich veröffentlicht wird; ein Mapping-, Workload- oder Artefakt-Body, den mehrere Recipes teilen, gehört in eine MappingLibrary, WorkloadLibrary oder ArtifactLibrary, auf die jedes Recipe per Identität verweist.
Warum ein Release anders ist. Ein Release verweist auf andere Entitäten — sein Aggregate, sein Manifest, das Release, das es erweitert — und wird nie veröffentlicht, daher reist nichts, was es liest, irgendwohin. Diese Referenzen und die Datei, die sein parameters: importiert, werden so gelesen, wie sie geschrieben sind, und genau das ermöglicht es, dass ein Aggregate von Release-Varianten in Unterverzeichnissen gemeinsam genutzt wird. Siehe entities/release.md.
Dieselbe Grenze gilt für ein FeatureRecipe und für jedes Schema, das eine Component oder ein Feature importiert.
Das Feld workload: — synthetisierte Eingabeart
Recipe.spec.workload: deklariert den Workload-Body, den der Compiler zu Provider-nativen Ressourcen synthetisiert. Es ist eine der drei Eingabearten, die ein Recipe neben source: (Rendering aus einer Source) und artifacts: (Hilfsmanifeste) deklarieren kann. Mindestens eine der drei muss bei jedem Provider vorhanden sein; ein Dienst, den der Build nicht bereitstellt, deklariert einen workload: mit form: reference.
Das Feld akzeptiert drei Authoring-Modi — Inline-Block-Scalar, Datei-$import: oder Bibliotheks-$import:. Der Compiler verzweigt anhand der Inhaltsform des Feldes; eine $mode:-Annotation ist nicht nötig.
Modus 1: Inline (Go-Template als String-Scalar). Der Wert ist ein YAML-Block-Scalar, dessen Ausgabe als aggrega.ai/v1beta1 Workload geparst wird:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Die Felder eines Workload stehen an der Wurzel des Dokuments — es gibt keinen spec:-Wrapper —, und containers: sowie die ports: jedes Containers sind nach Namen geschlüsselte Maps statt Sequenzen, wobei die Reihenfolge des Autors erhalten bleibt. Der Provider übersetzt diese Form in seine eigene native Form, sodass ein Eintrag der Container-Map in der gerenderten Ausgabe von helm als ein nach seinem Schlüssel benanntes containers[]-Element erscheint; die verfasste Form ist die Map, nicht die gerenderte Liste.
Modus 2: Datei-$import:. Der Wert ist eine Map mit einem einzigen $import:-Schlüssel, der auf eine lokale Go-Template-Datei zeigt:
spec: workload: $import: ./workload/web-server.yaml.tmplDie Pfadauflösung entspricht der von valuesMapping:: Ein relativer Pfad wird an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, nicht an dem Verzeichnis, aus dem der Build aufgerufen wird, und er muss innerhalb dieses Verzeichnisses bleiben. Der importierte Body ist ein Go-Template, das im Render-Kontext des Recipe ausgewertet wird, genau wie ein Inline-Body.
Modus 3: Bibliotheks-$import:. Der Wert ist eine Map mit einem einzigen $import:-Schlüssel, der eine Identitätsreferenz per einfachem Namen auf einen Eintrag einer WorkloadLibrary trägt:
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceDas Fragment #/workloads/ ist es, das einen Workload-Eintrag auswählt, und es ist das Fragment, das diese Referenz von der Form #/mappings/ unterscheidet, die valuesMapping: verwendet — jene adressiert einen Eintrag einer MappingLibrary und benennt keinen Workload-Body. Die Referenz trägt keinen Registry-Host, die aufgelöste Version stammt aus dem Lockfile pro Release, eine optionale Mindestversion :<version> kann als <Library>:<version>#/workloads/<Entry> angegeben werden, und ein Eintrag, dessen Body selbst ein $import: an der Feldwurzel ist, wird rekursiv aufgelöst. Der importierte Body ist ein Go-Template, das im Render-Kontext des konsumierenden Recipe ausgewertet wird, sodass .values, .infra und .features genau so hineinfließen wie in einen Inline-Body. Siehe entities/workloadlibrary für die Bibliotheksentität und die vollständige Referenzgrammatik.
Der Ziel-Provider muss Synthese unterstützen (der Katalog der Standardbibliothek deklariert workloadSchema per Konvention bei solchen Providern); das Ansteuern eines Providers, der nicht synthetisieren kann, wird beim Rendern des Knotens abgelehnt, mit der Diagnose zur Provider-Fähigkeit — gestützt auf die Fähigkeit des Providers, nicht auf das Vorhandensein von workloadSchema. Für die vollständige Workload-Grammatik, die Pass-through-Felder in K8s-Form und das Übersetzungsverhalten pro Provider siehe entities/workload.md. Für das umfassendere Modell der drei Eingabearten und den Assembler, der die Synthese mit aus der Source gerenderter Ausgabe und Artefakten zusammenführt, siehe architecture/16-recipe-input-composition.md.
Die eigenen Werte einer Komponente an das eigene Image des Entwicklers liefern. Von einem Recipe, das ein vom Entwickler gebautes Image ausführt, wird gemäß der Konvention des Standardbibliothek-Katalogs erwartet, dass es alles liefert, was die inject:-Blöcke des Entwicklers aufgelöst haben, aus .context.inject, und es kann zusätzlich die eigenen Werte der Komponente unter selbst gewählten Namen liefern. Wo die Component spec.inject deklariert, wählt der eigene Block des Entwicklers die Namen, und .context.self_inject teilt dem Recipe den einen eigenen Wert mit, den das Template jedes Eintrags liest — values.<key> für einen Eintrag, der genau einen eigenen Wert und sonst nichts liest. Die Konvention des Standardbibliothek-Katalogs besteht darin, die Namen, die ein Recipe diesen Werten gibt, als Vorgaben zu behandeln statt als einen Vertrag, den der Code des Entwicklers lesen muss, und einen Wert unter seinem Standardnamen nur dann zu liefern, wenn kein Eintrag auf ihn abbildet; ein Unternehmenskatalog kann anders entscheiden. Der Vertrag des Template-Kontexts nennt die genauen Regeln der Map und ein ausgearbeitetes Template.
Das Feld artifacts: — Hilfsmanifeste
Recipe.spec.artifacts: ist eine Map von Eintragsname → Definition eines Artefakt-Körpers, deren Einträge zusätzliche Manifest-Dateien neben der aus einer Quelle gerenderten oder synthetisierten primären Ausgabe des Recipe ausgeben. Es ist eine der drei Input-Arten (aus Quelle / synthetisiert / Artefakte) — ein Recipe kann artifacts: allein deklarieren oder zusammen mit workload: und/oder source:.
Der Wert jedes Eintrags trägt einen von drei Modi, die nach der Form des Inhalts ausgewählt werden und denen von workload: entsprechen — Inline-Inhalt, ein Datei-$import: oder ein Bibliotheks-$import:. Der Compiler wählt den Modus anhand der Form des Inhalts des Werts; eine $mode:-Annotation ist nicht nötig. Der Map-Schlüssel benennt in allen drei Modi, was der Eintrag ausgibt: Bei den beiden Einzeldatei-Modi ist er der Name der Ausgabedatei, beim Bundle-Modus das Verzeichnis, unter dem die Dateien des Bundles verschachtelt werden. Da der Schlüssel die Ausgabe benennt, ist er auf das beschränkt, was ein einzelner Dateiname sein kann: ein Buchstabe oder eine Ziffer am Anfang, dann Buchstaben, Ziffern, Punkte, Bindestriche und Unterstriche. Die Punkte erhalten die Endung, die ein Schlüssel per Konvention trägt — main.tf, template.yaml, serviceaccount.yaml —, während das Alphabet kein / zulässt, das aus einem Schlüssel den Namen eines Pfads statt einer Datei machen würde, und keinen führenden ., sodass ein Schlüssel nie das Segment des übergeordneten Verzeichnisses sein kann. Ein Schlüssel außerhalb dieses Alphabets besteht die Envelope-Validierung nicht, beim Laden des Workspace, bei aggrega validate und in den Diagnosen des Editors.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportModus 1: Inline (Go-Template-String-Skalar). Der Wert ist ein Block-Skalar, und der Map-Schlüssel ist der Name der Ausgabedatei, so verwendet, wie er geschrieben ist — der erste Eintrag oben gibt extra-configmap.yaml aus.
Modus 2: Datei-$import:. Der Wert ist eine Map mit einem einzigen $import:-Schlüssel, der auf eine lokale Go-Template-Datei zeigt, und der Map-Schlüssel ist der Name der Ausgabedatei, genau wie in Modus 1. Die importierte Datei liefert den Inhalt; sie liefert nicht den Namen. Der zweite Eintrag oben hat den Schlüssel network-policy.yaml und gibt network-policy.yaml aus, obwohl die Datei, die er importiert, network-policy.tmpl heißt. Ein Autor, der einen bestimmten Namen für die Ausgabedatei will, schreibt ihn also als Schlüssel, und zwei Einträge, die verschiedene Dateien mit zufällig gleichem Namen importieren — ./extras/shared.yaml und ./overrides/shared.yaml —, sind zwei verschiedene Ausgaben. Die Pfadauflösung entspricht der von valuesMapping: und workload:: Ein relativer Pfad wird an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, nicht an dem Verzeichnis, aus dem der Build aufgerufen wird, und er muss innerhalb dieses Verzeichnisses bleiben.
Modus 3: Bibliotheks-$import:. Der Wert ist eine Map mit einem einzigen $import:-Schlüssel, der eine Identitätsreferenz in Form eines bloßen Namens auf ein Bundle einer ArtifactLibrary trägt, <Library>#/artifacts/<name>. Ein Bundle ist eine Menge von Dateien, die als eine Einheit importiert werden, daher wird ein Eintrag zu einer Ausgabe pro Datei im Bundle erweitert, jede unter dem Map-Schlüssel als <key>/<filename> verschachtelt — der Schlüssel benennt die Stelle der Verwendung und ist das Verzeichnis, in dem diese Dateien landen, nicht der Name einer von ihnen. Der dritte Eintrag oben hat den Schlüssel operator-support; wenn PlatformArtifacts#/artifacts/OperatorSupport crd.yaml und rbac.yaml deklariert, gibt dieser eine Eintrag operator-support/crd.yaml und operator-support/rbac.yaml aus. Die Referenz trägt keinen Registry-Host — eine Form oci://… mit Host wird abgelehnt —, die aufgelöste Version stammt aus dem Lockfile pro Release, und eine optionale Mindestversion :<version> kann als <Library>:<version>#/artifacts/<name> angegeben werden. Siehe entities/artifactlibrary für die Bibliotheks-Entität und die vollständige Grammatik der Referenz.
Ein Datei-$import: wird neben dem Recipe gepinnt. aggrega pin zeichnet den Digest der Bytes jeder importierten Datei in der Datei entity.lock im Verzeichnis des Recipe auf, mit dem Map-Schlüssel des Eintrags als Schlüssel, und aggrega build berechnet den Digest der Datei erneut und bricht mit [CATALOG_ERROR E0026] ab, wenn er nicht mehr übereinstimmt — oder zuerst mit E0130, wenn das Lockfile des Release, vor der Änderung geschrieben, das Recipe nach seinem Inhalt verzeichnet —, sodass eine nach dem Pinnen bearbeitete Datei nie ungeprüft gerendert wird. Wenn die Änderung beabsichtigt war, führen Sie aggrega pin für das Recipe aus, um den neuen Digest aufzuzeichnen; andernfalls stellen Sie die Datei wieder her. Ein Inline-Eintrag ist Teil der Recipe-Datei, und ein Bibliothekseintrag ist über die Bibliotheksversion gepinnt, die das Lockfile verzeichnet, sodass keiner von beiden einen eigenen Pin trägt. aggrega pull beschreibt die Datei.
Das Template jedes Artefakt-Eintrags wird mit demselben Template-Kontext ausgewertet wie valuesMapping:, unabhängig davon, welcher Modus seinen Körper geliefert hat. Zwei Ausgaben mit demselben Dateinamen brechen den Build ab, wenn der Knoten gerendert wird. Zwei Einträge einer artifacts:-Map können nicht dieselbe Ausgabe benennen: Ein Map-Schlüssel ist innerhalb eines Dokuments eindeutig und schreibt einen einzigen Dateinamen, daher ist die Ausgabe eines Einzeldatei-Eintrags sein Schlüssel, und die Dateien eines Bundle-Eintrags liegen unter einem Verzeichnis, das nach seinem Schlüssel benannt ist — das erste Segment jedes Pfads, den ein Eintrag ausgibt, ist der Schlüssel, der ihn erzeugt hat, sodass verschiedene Schlüssel verschiedene Ausgabenamen bleiben, wie auch immer die importierten Dateien heißen. Was der Abbruch abdeckt, ist ein einziger Dateiname, den zwei verschiedene Input-Arten beitragen — ein Chart-Template und ein Artefakt-Eintrag, die beide servicemonitor.yaml erzeugen —, gemeldet für dieses Recipe mit einer Diagnose, die jeden beitragenden Ursprung nennt.
Anwendungsfälle. artifacts: ist der Ort für Hilfsressourcen, die das primäre Chart oder Modul nicht erzeugt: eine NetworkPolicy, die eine Arbeitslast begleitet, ein HPA zusammen mit einem Deployment, eine Sidecar-ConfigMap mit instance_id als Schlüssel. Querschnittliche Hilfsressourcen, die für viele Komponenten gelten (zum Beispiel ein Backup-Sidecar an jedem Datastore), gehören zur Resource Generation des FeatureRecipe statt zu den artifacts: eines einzelnen Recipe — siehe entities/featurerecipe.md für die Erweiterungsoberfläche des FeatureRecipe.
Der boundary:-Block — Dateien für die gemeinsame Ausgabe der Boundary
Die meisten Recipes brauchen das nie. Alles andere, was ein Recipe schreibt, gehört zu seiner eigenen Komponente: Der Provider legt es unter der eigenen Position dieser Komponente in der Ausgabe der Boundary ab. Manche Dateien gehören stattdessen zur Boundary als Ganzes — eine Datei, die das Ziel einmal für alles liest, was die Boundary bereitstellt. Die Provider-Konfiguration von Terraform ist der typische Fall: Die Dokumentation von Terraform hält provider-Blöcke aus einem Modul heraus, das eine andere Konfiguration aufruft, und ein Modul mit einem eigenen solchen Block kann nicht mit depends_on, count oder for_each aufgerufen werden. In spec.boundary.artifacts schreibt ein Recipe eine solche Datei.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }Der Block ist artifacts: auf einer zweiten Ebene. artifacts ist sein einziges Element, und es hat genau die Form des eigenen artifacts: des Recipe: dieselben drei Modi — Inline-Inhalt, ein Datei-$import:, ein Bibliotheks-$import:, dessen Dateien unter dem Schlüssel des Eintrags als <key>/<filename> verschachtelt werden —, dieselbe Regel vom Schlüssel zum Dateinamen, dasselbe Alphabet für einen Schlüssel und derselbe Template-Kontext, sodass ein Eintrag .values, .infra, .locals und den Rest genau so liest wie ein artifacts:-Eintrag. Er braucht mindestens einen Eintrag, und jedes andere Element unter boundary: wird abgelehnt, wenn das Recipe gelesen wird. Ein FeatureRecipe hat keinen solchen Block.
Wo eine Datei geschrieben wird. Einmal, in dem Verzeichnis mit der assemblierten Ausgabe der Boundary, neben den Dateien, die die eigene Assemblierung des Providers dort schreibt — bei terraform neben der Root-Konfiguration aggrega.modules.tf statt im Modul der Komponente. Dem Provider wird keine dieser Dateien übergeben: Der Compiler wertet sie aus und schreibt sie selbst und vermerkt in keiner, von welcher Komponente sie stammt, weil sie jeder Komponente gehört, die sie deklariert hat. Ein Eintrag, dessen Template zu nichts gerendert wird, schreibt keine Datei.
Wie mehrere Beitragende zusammentreffen. Jeder Eintrag wird für jede Komponente ausgewertet, die das Recipe in der Boundary rendert, und die Dateien, die alle Beitragenden der Boundary deklariert haben, werden nach Namen zusammengeführt. Ein Name, der zu denselben Bytes ausgewertet wird — durch zwei Komponenten, die an ein Recipe gebunden sind, oder durch zwei Recipes, die einen Provider identisch konfigurieren —, ist eine einzige Datei. Ein Name, der zu unterschiedlichen Bytes ausgewertet wird, stoppt den Build und nennt die Datei und jeden Beitragenden, weil keine einzelne Datei das ist, was alle geschrieben haben; dasselbe gilt für einen Namen, den die eigene Assemblierung des Providers schreibt, etwa aggrega.modules.tf. Beides ist die Kollision der assemblierten Ausgabe. Zwei Recipes, die einen Provider unter zwei verschiedenen Dateinamen konfigurieren, werden nicht zusammengeführt — jede Datei wird geschrieben —, und dann meldet das Ziel die doppelte Konfiguration; Recipes, die eine Provider-Konfiguration teilen sollen, teilen daher deren Dateinamen, per Konvention einen, der nach dem Provider benannt ist, den sie konfiguriert.
Welche Provider ihn akzeptieren. Ob eine neben der assemblierten Ausgabe einer Boundary abgelegte Datei etwas bedeutet, ist eine Eigenschaft des Ziels des Providers; sie ist daher Teil der eigenen Deklaration des Providers. Ein Recipe, das den Block deklariert und dessen Provider ihn nicht akzeptiert, wird abgelehnt, bevor irgendetwas gerendert wird, unabhängig davon, wozu seine Einträge gerendert werden; siehe The provider does not support boundary artifacts (Der Provider unterstützt keine Boundary-Artefakte). Das Fähigkeitsraster führt die Angabe jedes Providers auf.
| Provider | boundary.artifacts: |
|---|---|
terraform | Akzeptiert. Jede Datei wird neben der Root-Konfiguration der Boundary geschrieben, die Terraform zusammen mit jeder anderen Konfigurationsdatei in diesem Verzeichnis liest. |
helm, compose, helm-chart, cloudformation | Abgelehnt, bevor irgendetwas gerendert wird. |
Ein Datei-$import: wird hier wie einer gepinnt, den ein artifacts:-Eintrag importiert. Der Entity-Lock zeichnet seinen Digest in derselben Liste artifactDigests auf, unter boundary/<key> statt unter dem Schlüssel allein, sodass ein Eintrag jedes Blocks, der unter demselben Schlüssel geschrieben ist, getrennt gepinnt wird. Der Pin-Schritt zeichnet ihn auf, ein Pull, der nicht pinnt, bricht ab, wo sein Pin fehlt oder nicht mehr übereinstimmt, und ein Build lehnt eine seit dem Pinnen bearbeitete Datei genau so ab wie eine artifacts:-Datei.
Das Feld outputLabels: — vom Autor deklarierte Labels auf der gerenderten Ausgabe
Recipe.spec.outputLabels: ist eine Map von Label-Schlüssel → Wert, die der Provider auf jedes Objekt stempelt, das die gerenderte Ausgabe des Recipe erzeugt. Sie ist der ehrliche Ort für ein Realisierungsmerkmal — eine Eigenschaft davon, wie ein bestimmtes Recipe eine Komponente realisiert, im Gegensatz zu dem, was die Komponente ist. Nehmen Sie den Speicher, mit dem eine Realisierung ihre Daten persistiert, unten als illustrativer Schlüssel example.io/storage-backing geschrieben: Ein Helm-Recipe, das einen PersistentVolumeClaim einhängt, und ein Compose-Recipe, das ein benanntes Volume einhängt, realisieren dieselbe Komponente mit unterschiedlicher Mechanik, daher tragen sie unterschiedliche outputLabels, und nachgelagerte Werkzeuge (Kostenzuordnung, Policy, Inventar) können sie an den ausgegebenen Ressourcen unterscheiden. Der Schlüssel ist illustrativ — example.io/ ist ein Beispiel-Namespace, und ein Katalog wählt die Schlüssel, die seine eigenen Werkzeuge lesen.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformOutput-Labels laufen auf derselben Schiene wie die festen Build-Provenienz-Labels: Sie werden in die Label-Menge zusammengeführt, die jede ausgebende Oberfläche stempelt, und landen daher überall dort, wo die Provenienz landet. Was sich unterscheidet, ist die Zuständigkeit — Provenienz-Schlüssel gehören dem Compiler, outputLabels dem Autor des Recipe.
Das eigene Identitäts-Label einer Komponente wird nicht hier eingetragen — eine Konvention des Katalogs, keine Regel, die der Compiler durchsetzt. Schlüssel, die angeben, was die Komponente ist, statt wie ein Recipe sie realisiert — ihre kognitive Kategorie, ihr operativer Typ, ihre Fähigkeits-Labels pro Rolle, wer die zugrunde liegende Ressource betreibt, die Lizenzklasse dessen, was sie kapselt —, werden in den metadata.labels des Component deklariert; siehe entities/component „Die semantische Label-Taxonomie“ für die Achsen. Ein Recipe bringt eines davon auf seine gerenderte Ausgabe, indem es den Schlüssel unten in outputComponentLabels: nennt, nicht indem es hier Schlüssel und Wert einträgt. Der Grund ist, dass ein literaler Eintrag eine zweite Kopie eines Werts ist, den die Komponente bereits trägt, und eine zweite Kopie kann der ersten widersprechen: Ein Recipe-Autor kann auf einem Knoten, dessen Component eine andere Ausrichtung deklariert, eine Ausrichtung eintragen und damit einem nachgelagerten Leser etwas mitteilen, was der Graph nicht sagt. Ein hochgestufter Eintrag kopiert per Referenz und hat daher keine zweite Kopie, die abweichen könnte. Der Kern akzeptiert, was auch immer Sie schreiben, abgesehen von der Regel für reservierte Namespaces unten; die Konvention wird von den Katalogautoren getragen.
Reservierte Namespaces. Die Namespaces aggrega.ai/ und app.kubernetes.io/ sind für plattformeigene Provenienz reserviert. Ein Recipe, das einen outputLabels-Schlüssel unter einem der beiden Präfixe deklariert, wird beim Laden mit einem klaren Katalogfehler abgelehnt, der den betroffenen Schlüssel nennt. Jeder andere Schlüssel wird akzeptiert. Darüber hinaus kontrolliert der Kern weder Schlüssel noch Wert — ein Schlüssel oder Wert, der für die Label-Oberfläche der Ziel-Engine nicht gültig ist, liegt in der Verantwortung des Autors, und die nachgelagerte Laufzeit lehnt ihn ab; der Compiler hält sich über die Regel für reservierte Namespaces hinaus heraus.
Darstellung pro Provider. Jeder Provider überträgt die Labels auf seine eigene Ausgabeoberfläche:
- helm, Workload-Synthese — sowohl auf den
metadata.labelsdes Objekts als auch auf denmetadata.labelsdes Pod-Templates, entsprechend der Stelle, an der die Synthese die Provenienz ablegt. - helm, Rendering aus der Quelle und Artefakte — auf den
metadata.labelsdes Objekts. - compose — auf der
labels:-Map jedes Services. - terraform — als Tags pro Ressource auf strukturell adressierbaren
.tf.json-Artefakt-Körpern, nach bestem Bemühen: Ein Ressourcenblock, der bereits eine Maptags(AWS/azurerm) oderlabels(Google) deklariert, erhält die Output-Labels dort, ein vom Autor deklarierter Schlüssel wird nie überschrieben, und eine Ressource ohne ein solches Attribut bleibt unverändert (ein Attribut wird nie erfunden). Native HCL-Körper (main.tf,*.tf) und vendorte Module werden unverändert ausgegeben und tragen keine injizierten Tags. Die Terraform-Provenienz reist weiterhin in ihrer begleitenden Kommentardatei, getrennt von der Tag-Schiene.
Output-Labels sind ausschließlich Labels; es gibt keine separate Oberfläche für Output-Annotationen. outputLabels wird vom Autor des Recipe deklariert (der von Ops verfassten Realisierungsschicht), nicht vom Aggregate — es beschreibt die Realisierung, nie die Identität des abstrakten Graphen des Entwicklers.
Das Feld outputComponentLabels: — die eigenen Labels einer Komponente hochstufen
Recipe.spec.outputComponentLabels: ist eine Liste von Label-Schlüsseln, nicht von Schlüssel-Wert-Paaren. Für jeden Schlüssel, den sie nennt, stempelt der Provider diesen Schlüssel auf die gerenderte Ausgabe, mit dem Wert, den der Schlüssel auf der gerade gerenderten Komponenteninstanz trägt. Wo outputLabels einen Wert angibt, nennt outputComponentLabels, woher der Wert zu lesen ist.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingBei einem Component, dessen metadata.labels component.aggrega.ai/hosting: managed deklarieren, trägt jedes Objekt, das dieses Recipe für diese Komponente rendert, component.aggrega.ai/hosting: managed. Binden Sie dasselbe Recipe an eine Komponente, die self-hosted deklariert, und die Objekte dieser Komponente tragen stattdessen self-hosted — ein Recipe, ein benannter Schlüssel, ein Wert pro Komponente.
Die Hochstufung erfolgt per Referenz, und genau darum geht es. Der Wert wird bei jedem Rendern der Ausgabe von der Komponente gelesen, kann also nicht von der Identität abweichen, aus der er stammt: Es gibt keine zweite Kopie, die beim Ändern des Labels der Komponente mitgezogen werden müsste. Ein literaler outputLabels-Eintrag, der das Label einer Komponente wiederholt, ist diese zweite Kopie, und die beiden widersprechen sich, sobald sich eines von beiden ändert. Greifen Sie also zu outputLabels, wenn der Wert eine Eigenschaft davon ist, wie dieses Recipe die Komponente realisiert, und zu outputComponentLabels, wenn der Wert bereits auf der Komponente existiert und auch die gerenderte Ausgabe ihn tragen soll.
Ein hochgestufter Schlüssel landet auf genau derselben Oberfläche wie ein literaler — die oben beschriebene Darstellung pro Provider gilt unverändert, und kein Provider unterscheidet einen hochgestuften Schlüssel von einem, der direkt geschrieben wurde.
Reservierte Namespaces. Die Namespaces aggrega.ai/ und app.kubernetes.io/ sind für plattformeigene Provenienz reserviert, und ein hochgestufter Schlüssel unter einem der beiden Präfixe wird beim Laden mit einem Katalogfehler abgelehnt, der den Schlüssel und das Feld nennt, in dem er steht. Maßgeblich ist das bloße Präfix: Ein Schlüssel wie component.aggrega.ai/hosting liegt in einem eigenen Namespace statt unter der reservierten Wurzel und kann hochgestuft werden.
Ein Schlüssel gehört zu dem einen oder dem anderen Block. Denselben Schlüssel sowohl in outputLabels als auch in outputComponentLabels zu deklarieren, wird beim Laden abgelehnt, sodass jeder gestempelte Schlüssel eine einzige Quelle hat — entweder den auf dem Recipe geschriebenen literalen Wert oder das eigene Label der Komponente, nie beides.
Ein hochgestufter Schlüssel, den die Komponente nicht deklariert, stempelt nichts. Der Build läuft weiter und gibt eine Warnung aus, die den Knoten, das Recipe und den fehlenden Schlüssel nennt. Das ist beabsichtigt: Ein Recipe, das an Komponenten mit unterschiedlichen Label-Mengen gebunden ist, wird trotzdem gerendert, und die Abweichung wird gemeldet, statt den Build abzubrechen.
Komponenten mit einer einzigen Ausrichtung — eine Konvention, keine Regel. Die Hochstufung überträgt jeden Wert, den die Komponente deklariert, und der Compiler interpretiert diesen Wert nicht. Eine Komponente, deren Identitäts-Label einen Platzhalter für „variiert“ enthält, stuft diesen Platzhalter daher auf jedes für sie gerenderte Objekt hoch. Wo eine Komponente tatsächlich mehr als eine Ausrichtung hat, sieht die Konvention des Katalogs der Standardbibliothek vor, dass jedes Recipe die Ausrichtung seiner eigenen Realisierung über einen outputLabels-Schlüssel angibt, der dem Recipe gehört, statt über den Identitätsschlüssel der Komponente, den dieselbe Konvention stattdessen über outputComponentLabels: leitet — oder gar nichts stempelt. Die beiden Schlüssel beantworten verschiedene Fragen, und keiner ersetzt den anderen: Der Identitätsschlüssel sagt, was die Komponente über alle Realisierungen hinweg ist, der Schlüssel des Recipe sagt, was diese eine Realisierung tut. Das ist eine Konvention des Katalogs, die von seinen Autoren getragen wird, keine Einschränkung, die der Compiler durchsetzt.
Der Block locals:
Recipe.spec.locals: ist der private Ops-Zustand — eine Map benannter Go-Template-Strings, deren gerenderte Ausgabe den späteren Templates des Recipe eine Map .locals.* bereitstellt. Er ist der Arbeitsbereich, um physische Gegebenheiten (Zielcontainer, JSON-Pfade, abgeleitete Hostnamen) einmal zu berechnen und sie in den Payloads von provides:, source:, valuesMapping:, workload:, artifacts:, assertions: und pipeline[].with ohne Neuberechnung wiederzuverwenden. Die gerenderte Ausgabe jedes Eintrags wird ohne führenden und nachgestellten Leerraum gespeichert.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: wird Aufrufern nie bereitgestellt — nachgelagerte Komponenten, die dieses Recipe über uses: konsumieren, sehen nur provides:. Die eigenen Templates provides:, source:, valuesMapping:, workload:, artifacts:, assertions: und pipeline[].with des Recipe sehen alle die aufgelöste Map .locals.*. Werte pro Schlüssel können einfache Strings oder Go-Templates sein; der Compiler löst den ganzen Block in der Locals-Präambel auf, vor dem provides: dieses Knotens, sodass jedes spätere Template stabile aufgelöste Werte sieht.
Jeder Eintrag wird gegen einen in sich geschlossenen, knotenlokalen Kontext ausgewertet: .context.instance_id, .values, .infra und die bereits aufgelösten Einträge desselben Blocks. Ein Local kann .provides nicht lesen — diese Säule ist auf dieser Oberfläche nicht vorhanden, und ein Eintrag, der danach greift, bricht ab. Ebenso wenig kann er .context.rendered_name lesen, den Namen, den ein Provider wie helm den Ressourcen gibt, die er für den Knoten rendert; daher trägt ein Local, der eine dieser Ressourcen benennt, nur den Teil nach diesem Namen, wie secret_target_db_password oben, und das Template, das den vollständigen Namen schreibt, fügt beide zusammen.
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: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveDie Verkettung läuft nur nach unten. Wo ein Eintrag einen anderen liest, entscheidet die Reihenfolge der Einträge, ob der Build gelingt: Verschieben Sie db_identifier unter secret_target, und der Build bricht ab. Der Compiler sortiert oder ordnet den Block nie um, damit eine Referenz aufgelöst werden kann; die geschriebene Reihenfolge ist also der Vertrag — einen locals:-Block umzuordnen ist eine Verhaltensänderung, keine kosmetische.
Zwei Abbrüche trennen die beiden Fehler, die ein Autor machen kann, weil sie unterschiedliche Korrekturen haben:
- Eine Referenz auf einen Eintrag, den der Block später definiert, bricht ab und nennt den Reihenfolgefehler; die Korrektur besteht darin, die Definition über ihren Leser zu verschieben.
- Eine Referenz auf einen Schlüssel, den der Block gar nicht deklariert, bricht ab und nennt den Schlüssel; die Korrektur besteht darin, die Schreibweise zu berichtigen.
Die Prüfung folgt einem Alias für den Block. Ein Schlüssel, der über den Punkt erreicht wird, den ein with .locals-Körper neu bindet, oder über eine an .locals gebundene Variable, wird genau zu denselben Bedingungen geprüft wie die direkte Schreibweise: {{ with .locals }}{{ .nope }}{{ end }} und {{ $l := .locals }}{{ $l.nope }} brechen beide ab und nennen .locals.nope, genau wie {{ .locals.nope }}, und ebenso {{ (.locals).nope }} und {{ ($.locals).nope }}, weil die Klammern den Block selbst liefern und nichts weiter. Eine Schreibweise entgeht der Prüfung: 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 }} —, weil das, was ein solcher Aufruf liefert, bei der Ausführung des Templates entschieden wird und nicht durch das Geschriebene. Ein fehlender Schlüssel, der als Feld vom Ergebnis eines solchen Aufrufs gelesen wird, bricht nicht ab und rendert den literalen Text <no value> statt gar nichts. Ein fehlender Schlüssel, der über index erreicht wird, bricht ab und nennt den Schlüssel, weil index auf jeder Template-Oberfläche abbricht, wenn die gelesene Map den angefragten Schlüssel nicht enthält — eine andere Meldung als die dieser Prüfung, dokumentiert unter errors/fatal-halts.md bei „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)“. index bleibt daher der Weg, einen Schlüssel zu erreichen, dessen Name selbst berechnet wird, etwa {{ index .locals (printf "secret_target_%s" .values.slot) }}, und ein berechneter Name, den der Block nicht deklariert, wird weiterhin anhand seines Schlüssels gemeldet.
provides: liest .locals und erhält aufgelöste Werte, weil die Locals eines Knotens vor seinen Provides aufgelöst werden. Ein provides:-Template, das einen Schlüssel nennt, den der Locals-Block nicht deklariert, bricht ab. Ein Wert, den sowohl ein provides:-Eintrag als auch ein Artefakt brauchen, wird also einmal in locals: verfasst und an beiden Stellen gelesen.
Für das Gegenstück der öffentlichen API siehe Der provides:-Block unten. Die FeatureRecipe-Oberfläche folgt denselben Regeln — siehe entities/featurerecipe.md „Der locals:-Block“.
Der Block provides:
Recipe.spec.provides: ist die öffentliche Entwickler-API — eine Map von Name → Go-Template-String, die die Werte deklariert, die dieses Recipe zu den Pipes .context.inject und .context.uses nachgelagerter Aufrufer beiträgt. Der Compiler wertet provides:-Templates bei der Provides-Auswertung aus (in sich abgeschlossen, in beliebiger Reihenfolge); die inject-Schlüssel der Aufrufer werden bei der Inject-Hydratisierung gegen diese Werte aufgelöst.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"Das Template jedes Eintrags wird gegen die in sich abgeschlossene Oberfläche der Provides-Auswertung ausgewertet — .context.instance_id, .context.rendered_name, sofern der Provider des Knotens einen meldet, .values, .infra, die aufgelösten .locals des Knotens und statischer Text. Der Namespace, in dem der Knoten platziert ist, gehört nicht dazu, daher trägt ein veröffentlichter Host keinen: Ein Konsument in einem anderen Namespace qualifiziert ihn auf seiner eigenen Seite. .locals gehört dazu, weil die Locals des Knotens in der Präambel derselben Stufe aufgelöst werden, vor seinen Provides; ein provides-Template, das einen Schlüssel nennt, den der Locals-Block nicht deklariert, hält den Build an. Die Trennung der Provides-Auswertung von der Inject-Hydratisierung ist tragend: Das provides: eines Recipe kann nicht auf den Zustand eines Aufrufers verweisen, weil die Aufrufer noch nicht aufgelöst sind, wenn die Provides-Auswertung läuft — provides: ist gemäß der architektonischen Invariante in sich abgeschlossen. Aufrufer lesen diese Werte dann über .context.uses.<alias>.provides.<provided-name> in ihren eigenen Templates — die bereitgestellten Namen sind auf der Kante unter provides verschachtelt, neben den anderen Feldern der Kante. Ein Aufrufer, der auf der Kante eine inject:-Allowlist deklariert, erreicht dieselben Werte stattdessen über seine .context.inject-Pipe.
provides:-Schlüssel sind Teil der Vertragsoberfläche des Recipe. Das Umbenennen oder Entfernen eines Schlüssels ist eine inkompatible Änderung für jeden Aufrufer, der sich auf den alten Namen verlässt; die Schnittstellenversion implements: sollte die Weiterentwicklung des Vertrags widerspiegeln. Zur Semantik der kaskadierenden Auflösung, zum Inject-Pipe-Vertrag und zu ausgearbeiteten Beispielen für namespace- und regionsübergreifendes Routing siehe architecture/06-data-taxonomy-and-composition.md §3 und templates/expansion-matrix.md.
Die veröffentlichten Werte einer Anbindung lesen
Ein Recipe liest die an seine Komponente angebundenen Features unter .features.<instance-name> und die Credential-Features unter .features.<slot>. Beide haben dieselbe Anbindungsform — .type, .values, .infra, .provides —, sodass eine Anbindung auf dieselbe Weise gelesen wird, gleich welche Map sie enthält; was sie unterscheidet, ist das, was die Anbindung erzeugt.
.provides ist die veröffentlichte Ausgabe der Anbindung, aufgelöst aus dem an sie gebundenen FeatureRecipe. Es ist das Gegenstück zum obigen provides:-Block, gesehen von der konsumierenden Seite: Wo ein Recipe an seine Aufrufer veröffentlicht, veröffentlicht eine Anbindung an ihre Host-Komponente.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Den veröffentlichten Wert zu lesen, statt ihn aus denselben values/infra-Eingaben neu zu berechnen, ist der Unterschied zwischen einer einzigen Angabe eines Namens und zweien, die auseinanderdriften können. Die vollständige Form Feld für Feld, einschließlich der Verfügbarkeitsregeln, finden Sie unter templates/template-context-contract.md.
Eine Anbindung, die auf einer der Verbindungen der Komponente geschrieben ist — ein Credential, das die Komponente gegenüber einem Ziel vorweist —, wird in derselben Form unter dieser Verbindung gelesen, unter .context.uses.<alias>.features.<slot>, und gehört nie zu .features. Ein Recipe, das mehrere Ziele erreicht, liest das eigene Credential jedes Ziels unter dem Alias dieses Ziels, und eine Schleife über .features, die Anbindungen nach Typ auswählt, trifft nur auf die eigenen der Komponente:
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Siehe Die Anbindungen einer Verbindung für die Form und für die Reihenfolge, in der ein Template die Verbindungen durchläuft.
Das Feld pipeline:
Recipe.spec.pipeline: ist ein sequenzielles Array von Wasm-Pipeline-Schritten, die nach dem Rendern über der gerenderten Dokumentmenge laufen und jeweils Patches nach RFC 6902 sowie Seiteneffekte zurückgeben. Jeder Eintrag deklariert eine id (Bezeichner pro Schritt: Buchstaben, Ziffern und Unterstriche), ein plugin (die Plugin-Entität, die der Schritt ausführt, qualifiziert durch ihren Plugin-Typ — pipeline-step/<name>, optional mit einer Version; eine bloße .wasm- oder Artefaktreferenz wird abgelehnt), eine function (der aufzurufende Export des Plugin), einen optionalen with:-Go-Template-Body, der die Nutzlast des Plugin liefert, und ein optionales when:-Go-Template, das steuert, ob der Schritt läuft — ein als falsch ausgewertetes Ergebnis überspringt den Schritt als Pass-through und lässt die Dokumentmenge unverändert. Das when:-Gate, seine Unabhängigkeit von optional: und seine Wahrheitsregel werden vollständig unter entities/featurerecipe.md „Bedingte Schritte — when:“ behandelt:
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"Der Compiler führt die pipeline:-Schritte eines Basis-Recipe in deklarierter Reihenfolge aus, auf dieselbe Weise, wie er das pipeline: eines FeatureRecipe ausführt: Er ruft das von jedem Schritt genannte Wasm-Plugin auf der gerenderten Ausgabe auf, wendet die zurückgegebenen JSON-Patch-Operationen auf die adressierten Dokumente an und gibt die Seiteneffekte des Schritts aus. Das Feld pipeline: des FeatureRecipe teilt dieselbe Schemaform und dieselbe Ausführung — siehe entities/featurerecipe.md „Authoring-Vertrag“ und Status der Sprache für den Ausführungsstand jeder Oberfläche.
Die Mechanik des Feldes spiegelt die FeatureRecipe-Semantik wider: sequenzielle Auswertung in deklarierter Reihenfolge, auf die gerenderten Dokumente angewendete JSON-Patch-Operationen, daneben ausgegebene Seiteneffekte und Fehler mit einer Herkunftsangabe, die auf den verursachenden Schritt zeigt. Ein Schritt, dessen when:-Gate als falsch gerendert wird, wird als Pass-through übersprungen und lässt die Dokumentmenge für den nächsten Schritt unverändert.
Der Block assertions:
Recipe.spec.assertions: ist eine optionale Map benannter Regeln, die Implementierungsinvarianten des Recipe ausdrücken — feldübergreifende Regeln, die für das konkrete Chart oder Modul gelten, aus dem das Recipe seine Quelle bezieht. Jeder Schlüssel ist ein Regelbezeichner, der in der Fehlermeldung erscheint; jeder Wert ist ein Go-Template-Body. Anders als Component-Assertions (die Invarianten auf Vertragsebene ausdrücken, unabhängig davon, welches Recipe gebunden wird) sind Recipe-Assertions Eigenschaften der gewählten konkreten Implementierung.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}Die obige Regel ist spezifisch für das Bitnami-Chart 20.x; sie gilt nicht, wenn ein anderes MariaDB-Recipe gebunden wird. Die Regeln auf Component-Ebene aus dem Vertrag gelten daneben weiterhin und werden in einer früheren Pipeline-Phase ausgewertet.
Recipe-Assertions werden nach der Recipe-Bindung und vor dem Rendern ausgewertet, sobald die Locals und Provides jedes Knotens aufgelöst sind. Der Template-Kontext enthält die .provides, .locals und .recipe.source des Recipe zusätzlich zu den Feldern der Entitätsinstanz (.values, .infra, .uses, .features). .uses und .features sind dort die engeren Formen der Assertion-Oberfläche, nicht die eines Recipe-Templates: Der Eintrag einer Verbindung trägt ihr Ziel und ihren Alias, die labels des Ziels, die eigenen values der Verbindung und die auf ihr unter features geschriebenen Anbindungen, aber nichts, was das Ziel veröffentlicht; und der Eintrag einer Anbindung, ob der Komponente selbst oder einer Verbindung, trägt ihren type, ihre resolved_version und ihre values, aber weder ihr infra noch ihr provides — das FeatureRecipe einer Anbindung hat seine Provides noch nicht aufgelöst, wenn die Assertion läuft. Ein Verweis auf .features.<name>.provides hält daher den Build an, und ein anwesenheitsbewusster Lesezugriff darauf liefert seinen Fallback. Zur vollständigen Authoring-Grammatik, zur Aufteilung der Verantwortung zwischen Regeln auf Vertragsebene und auf Implementierungsebene sowie zu ausgearbeiteten Beispielen siehe templates/assertions-block.md.
Das Feld omits: — gerenderte Dokumente aus einer Quelle auslassen
Die meisten Recipes brauchen dies nie. Es ist für eine Quelle gedacht, die Sie so übernehmen, wie sie ist — meistens ein aus einer Registry abgerufenes Chart —, die ein Dokument rendert, das Ihr Release nicht ausliefern darf: etwa ein Secret, das das Chart bei jedem Rendern neu generiert, wodurch sich zwei Builds unterscheiden und das, einmal angewendet, das vom Betreiber bereitgestellte Secret überschreibt. Ein abgerufenes Chart bearbeiten Sie nicht, und keine Ignore-Regel reicht in eines hinein, daher ist omits: der Weg, auf dem ein Recipe ein solches Dokument aus dem Build herauslässt. Eine abgerufene Compose-Datei ist derselbe Fall: Sie kann einen Service, ein Volume oder eine Config bündeln, die das Release nicht haben darf, und ein valuesMapping:-Overlay kann eines davon ändern, es aber nie entfernen. Ebenso ein abgerufenes CloudFormation-Template, das eine Ressource deklarieren kann, die das Release nicht erstellen darf: Ein valuesMapping: kann die von ihm deklarierten Parameter füllen, aber nie eine seiner Ressourcen entfernen.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringWas es abdeckt. Nur das, was source: rendert. Ein workload: und die artifacts:-Einträge werden nie gefiltert: Diese schreiben Sie im Recipe, daher ist ein Dokument, das Sie dort nicht wollen, eines, das Sie einfach nicht schreiben. Der Schlüssel erfordert source:; ein Dokument, das gegen diese Regel verstößt, wird beim Lesen abgelehnt, wobei die Regel genannt wird.
Ein Eintrag. Jeder Eintrag benennt über drei Felder, was weggelassen wird, und ein viertes entscheidet, ob er gilt. Was die ersten drei benennen, ist das eigene Vokabular des Providers für das, was seine Quelle rendert, wie es in der folgenden Tabelle pro Provider dargelegt ist:
kind— die Art dessen, was die Quelle rendert: bei einem Chart der Kind eines gerenderten Dokuments —Secret,ConfigMap,Deployment; bei einer Compose-Dateiservice,volumeoderconfig; bei einem CloudFormation-Template derTypeeiner Ressource —AWS::S3::Bucket. Er hat nichts mit demkind:zu tun, den eine strukturiertesource:trägt und der angibt, wie die Quelle abgerufen wird.name— sein Name: dermetadata.nameeines Dokuments; der Schlüssel einer Compose-Einheit unterservices:,volumes:oderconfigs:; die logische ID einer CloudFormation-Ressource, ihr Schlüssel unterResources.namespace(optional) — der Namespace, in dem sich das Dokument befindet, für einen Provider, dessen Ausgabe Namespaces hat. Ohne ihn benennt der Eintrag den Kind und den Namen in jedem Namespace; einnamespace, der zu nichts gerendert wird, wird als nicht vorhanden behandelt.when(optional) — ob der Eintrag für diesen Build gilt. Es wird zuerst ausgewertet und nach derselben Regel gelesen wie daswhen:eines Pipeline-Schritts: Ein falsches Ergebnis verwirft den Eintrag, sodass seine anderen Felder nicht ausgewertet werden und er weder an den Provider übergeben noch geprüft wird, während ein fehlendes oder leereswhen:ihn beibehält.
kind und name sind erforderlich, und ein Eintrag mit einem anderen Feld wird beim Lesen des Recipe abgelehnt.
Jeder Wert ist ein Template, ausgewertet gegen denselben Kontext wie valuesMapping:. Dieser Kontext trägt .context.rendered_name, den Namen, den der Provider den Ressourcen des Knotens gibt und nach dem ein Chart sie typischerweise benennt, sodass ein Eintrag ein Dokument genau so benennen kann, wie das Chart es tun wird. Ein Template, das nicht gerendert werden kann, hält den Build an, wie es ein fehlschlagendes valuesMapping:-Template tut.
Jeder geltende Eintrag muss etwas weglassen. Der Provider meldet, wie viele Einheiten jeder Eintrag weggelassen hat, und ein Eintrag, der keine weggelassen hat, stoppt den Build und nennt den Eintrag; siehe An omits entry left out nothing the source rendered (Ein omits-Eintrag hat nichts von dem weggelassen, was die Quelle gerendert hat). Ein Upgrade der Quelle, das das Dokument umbenennt oder entfernt, ist die übliche Ursache, und der Abbruch ist das, was verhindert, dass ein umbenanntes Dokument unbemerkt Ihre Ausgabe erreicht. Um ein Dokument nur manchmal wegzulassen, sagen Sie das mit when:, statt sich darauf zu verlassen, dass das Dokument fehlt.
Die Quelle wird trotzdem vollständig gerendert. Nur ihre Ausgabe wird gefiltert: Jedes Template des Charts läuft weiterhin, sodass ein fehlschlagendes Template den Build weiterhin fehlschlagen lässt, und ein weggelassenes Dokument wird gerendert und dann verworfen. Einmal verworfen, erreicht es nichts mehr, was der Build danach tut — keine ausgegebene Datei, keinen mit den Namen anderer Komponenten verglichenen Namen, keinen Fakt, den ein Feature über das Rendern liest, nichts, was einem Pipeline-Schritt übergeben wird.
Ein Release erreicht den Schlüssel über infra und parameters. Der Schlüssel gehört zum Recipe, daher kann ein Release ihn nicht schreiben. Es kann aber trotzdem entscheiden, was ein Eintrag tut: Die Templates eines Eintrags lesen das infra, das das Release ausfüllt, und die parameters, die es liefert, erreichen die .values des Recipe überall dort, wo das Aggregate sie dorthin leitet. So schaltet ein Release einen Eintrag mit when: ein oder aus, wie es der zweite Eintrag oben tut, oder entscheidet, was er benennt.
Was Sie weglassen, verantworten Sie. Nichts im Build weiß, wofür ein Dokument da ist. Eines wegzulassen, von dem der Rest des Charts zur Laufzeit abhängt — das Secret, das ein Deployment einbindet, der ServiceAccount, unter dem ein Pod läuft —, erzeugt eine Ausgabe, die sauber baut und dann beim Anwenden fehlschlägt, es sei denn, etwas anderes, das daneben angewendet wird, stellt dieses Dokument bereit. Bei einer Compose-Datei und einem CloudFormation-Template prüft der Build sehr wohl, weil jede ihre eigenen Verweise angibt: Was übrig bleibt und noch eine weggelassene Einheit nennt — ein Service, der einen weggelassenen Service nennt, eine Ressource oder ein Output, die eine weggelassene Ressource nennen —, stoppt den Build, wie die folgende Tabelle beschreibt.
Welche Provider ihn berücksichtigen. Ein Dokument wegzulassen ist etwas, das nur der Provider tun kann, weil nur der Provider weiß, was seine Quelle rendert; ob ein Provider den Schlüssel berücksichtigt, ist daher Teil der eigenen Deklaration des Providers. Ein Recipe, das omits: deklariert und dessen Provider ihn nicht berücksichtigt, wird abgelehnt, bevor irgendetwas gerendert wird, unabhängig davon, wozu die when: seiner Einträge gerendert werden; siehe The provider does not support omits (Der Provider unterstützt omits nicht).
| Provider | omits: |
|---|---|
helm | Berücksichtigt. Ein Eintrag benennt ein Dokument, das das Chart rendert — aus einem Template oder aus seinem Verzeichnis crds/ —, über den eigenen kind und metadata.name des Dokuments und, sofern der Eintrag einen nennt, den Namespace, in dem sich das Dokument befindet. Siehe helm → Modus mit Quelle. |
compose | Berücksichtigt. Ein Eintrag benennt einen service, ein volume oder eine config der als Quelle verwendeten Compose-Datei über seinen Schlüssel unter services:, volumes: oder configs:, abgeglichen, nachdem valuesMapping: in die Datei gemergt wurde, und nennt keinen Namespace: Ein Eintrag, der eine andere Art oder einen Namespace nennt, stoppt den Build, wenn die Komponente gerendert wird. Eine Datei, in der das Übrige noch eine weggelassene Einheit nennt — über depends_on, links, volumes_from, einen service:-Netzwerk- oder -Namespace-Modus, extends, einen Build-Kontext oder einen volumes:- oder configs:-Eintrag —, stoppt den Build und nennt jeden Verweis. Siehe compose → Modus mit Quelle. |
cloudformation | Berücksichtigt. Ein Eintrag benennt eine Ressource des als Quelle verwendeten Templates über ihren Type und ihre logische ID, in jedem Template einer Verzeichnisquelle, und nennt keinen Namespace: Ein Eintrag, der einen trägt, stoppt den Build, wenn die Komponente gerendert wird. Ein Template, in dem das Übrige noch eine weggelassene Ressource nennt — über Ref, Fn::GetAtt, DependsOn oder eine Fn::Sub-Variable —, stoppt den Build und nennt jeden Verweis. Siehe cloudformation → Ressourcen aus einem als Quelle verwendeten Template weglassen. |
helm-chart, terraform | Abgelehnt: Der Provider reicht seine Quelle weiter, damit sie bei der Bereitstellung gerendert wird, daher existiert zur Build-Zeit kein Dokument, das weggelassen werden könnte. Bei einem lokalen Chart oder Modul lässt stattdessen eine Zeile in der .aggregaignore neben dem Recipe eine Datei davon weg. |
Derselbe Schlüssel wird in einem FeatureRecipe geschrieben; siehe entities/featurerecipe.md.
Für ein ausgearbeitetes Beispiel — das generierte Secret eines abgerufenen Charts weggelassen, der Determinismus-Abbruch, auf den dasselbe Chart ohne den Eintrag trifft, und der Abbruch bei einem Eintrag, der auf nichts passt, jeweils aus einem echten Build — siehe ai-gateway-own-webhook-certificate.