Provider-Architektur
Ein Provider rendert die Eingabearten eines Recipe in Provider-native Manifestdateien. Wenn ein Recipe capability: helm, capability: compose oder einen anderen Provider-Namen deklariert, verteilt der Compiler das Rendering an den Provider, der diesen Namen bedient. Dieses Kapitel behandelt, wie ein Provider als Provider-Rendering-Plugin umgesetzt wird, wie die Verteilung funktioniert und den Plugin-Socket-Vertrag, der den Compiler an jeden Provider bindet.
Was dieses Kapitel nicht behandelt: das Kompositionsmodell mit drei Eingabearten (source: + valuesMapping:, workload:, artifacts: — jede akzeptiert Inline-Inhalt oder $import:), das ein Recipe nutzt, um seine Ausgabe zu erzeugen. Dieses Modell ist querschnittlich über alle Provider und steht in ../../architecture/16-recipe-input-composition.md, einschließlich der Provider-Fähigkeitsmatrix, die abbildet, welche Eingabeart jeder Provider unterstützt.
Das Provider-Rendering-Plugin
Provider-Rendering wird von einem Plugin mit pluginType: provider bereitgestellt. Das Provider-Rendering-Plugin:
- bedient einen oder mehrere Provider-Namen — deklariert in
spec.provider.capabilities. Der Provider-Name, den ein Recipe nennt (spec.capability: helm), bindet an das Provider-Rendering-Plugin, dessen Listespec.provider.capabilitiesdiesen Namen enthält. Wenn mehr als ein Plugin dasselbe Ziel bedient, wählt der Workspace zwischen ihnen über ein Provider-Binding in.aggrega-config.yaml, das beiaggrega pullaufgelöst und in der Lockfile aufgezeichnet wird; ohne Binding und mit genau einem Kandidaten wird dieser Kandidat verwendet, und ohne Binding und mit mehr als einem Kandidaten hält der Build laut an und nennt die Kandidaten-Plugins. - trägt seine Provider-Socket-Metadaten im selben Block —
spec.providerenthält die obige Fähigkeitenliste neben den übrigen Deklarationen des Providers.spec.provider.workloadSchemaist eine Deklaration in JSON Schema 2020-12, die dokumentiert, wie die plattformeigene Workload-Art in die native Ausgabe dieses Providers übersetzt wird; der Katalog der Standardbibliothek deklariert sie bei Providern, die synthetisieren, als dokumentierten Übersetzungsvertrag.spec.provider.wellKnownAnnotationszählt die Boundary-Annotationenaggrega.ai/auf, die der Provider liest. Die Unterstützung synthetisierter Eingaben (workload:) ist eine Eigenschaft des Providers, die zur Render-Zeit durchgesetzt wird — sie wird nicht durch das Vorhandensein vonworkloadSchemabestimmt.
Siehe ../entities/plugin.md für die vollständige Authoring-Oberfläche der Plugin-Entität auf Feldebene, einschließlich des Blocks spec.provider.
Verteilung pro Provider
Jedes Recipe deklariert genau ein capability: am Anfang seines spec. Der Compiler liest dieses Feld und verteilt das Rendering an den Provider, der den Namen bedient. Ein Recipe kann nicht mehrere Provider gleichzeitig ansteuern. Multi-Provider-Komposition findet auf Release-Ebene statt: Eine Boundary kann Komponenten gemischter Provider enthalten, und die Beitragenden jedes Providers am ausgewerteten Assemblierungspfad der Boundary werden unabhängig assembliert — eine Assemblierung pro Tupel (path, provider).
Der Verteilungspfad für einen einzelnen Knoten:
- Der Compiler löst die Recipe-URI für diesen Knoten über die dreistufige Suche des Manifest im Mapping-Abschnitt des Ziel-Providers auf. Die Gruppierung nach der Provider-Achse im Manifest ist es, was „dieselbe Component, verschiedene Recipes für verschiedene Provider“ zu einem natürlichen Muster macht.
- Das
spec.capabilitydes aufgelösten Recipe bestimmt den Provider-Namen, an den verteilt wird. - Der Compiler bindet den Provider für diesen Namen: Er löst das Provider-Rendering-Plugin auf, dessen Liste
spec.provider.capabilitiesden Namen enthält, und rendert über den Guest, den dieses Plugin mitbringt. Rendering erfolgt ausschließlich über Wasm — es gibt keinen Renderer im Host, auf den zurückgegriffen werden könnte, daher hält ein Provider-Name, der sich zu keinem bedienenden Plugin auflöst, den Build zur Routing-Zeit laut an. - Der Provider wird mit dem Render-Kontext pro Knoten aufgerufen (Säulenwerte, Projektionen von
.context.*, die Eingabearten des Recipe). - Der Provider gibt die gerenderte Ausgabe zurück. Der Compiler leitet die gerenderten Dateien an den Assembler pro
(path, provider)weiter, der über das ausgewertetedirectory:der Boundary, verbunden mit demsubDirectory:pro Komponente, geschlüsselt ist. Zwei Boundaries, die unter demselben Provider zum selben Pfad ausgewertet werden, teilen sich einen Assembler — das kanonische Muster ist eine übergeordnete Boundary plus zwei untergeordnete Boundaries mitdirectory: "{{ .parent_boundary.directory }}", die zu einer zusammengeführten Assemblierung zusammenfallen.
Siehe ../entities/manifest.md für die Verteilungsform des Manifest nach Provider-Achse und ../entities/recipe.md für die Einzel-Provider-Deklaration auf Recipe-Seite. Das Assemblierungsmodell pro (path, provider) und die Allowlist der Pfad-Template-Variablen, die ausgewertete Pfade steuert, sind in ../path-template-variables.md dokumentiert.
Der Wasm-Plugin-Vertrag
Provider-Rendering läuft in einer WebAssembly-Sandbox. Der Go-Compiler ist der Host; das Provider-Rendering-Plugin ist der Guest. Für jeden Knoten übergibt der Compiler dem Plugin den Render-Kontext des Knotens, und das Plugin gibt die Dateien zurück, die es gerendert hat. Dieser Vertrag ist für jeden Provider einheitlich:
- Eine kanonische Binärkodierung in beide Richtungen. Der Compiler kodiert den Render-Kontext — die Werte und Anbindungen des Knotens, das geparste
.workload, die ausgewerteten Artefakteinträge, die reine Namensliste einer aufgelösten.sourceund die Boundary-Metadaten — als kanonisches CBOR (RFC 8949 §4.2.1) und übergibt ihn dem Plugin. Das Plugin antwortet in derselben Kodierung mit der Liste der Dateien, die es gerendert hat — jeweils ein Pfad relativ zum Ausgabe-Root des Knotens und die genauen Bytes, die dort zu schreiben sind, optional mit dem Format der Datei —, neben etwaigen Diagnosen. Jeder Export des Sockets, vom Rendern eines Knotens über das Assemblieren einer Boundary bis zur Verdrahtung einer Boundary-übergreifenden Verknüpfung, trägt diese Kodierung in beide Richtungen, und das Plugin-Entwicklungskit jeder Sprache dekodiert und kodiert sie für das Plugin. Eine Antwort, die nicht die Ausgabeform des Exports in dieser Kodierung hat, hält den Build an. Der Plugin-Vertrag dokumentiert die Payload jedes Exports. - Kein Dateisystemzugriff. Plugins können keine beliebigen Dateien aus dem Dateisystem des Hosts lesen. Eine Quelle, die ein Recipe nennt — ein Chart in einer Registry, ein Modul in einem Repository —, wird vom Compiler aufgelöst, bevor das Plugin läuft; das Plugin erhält eine reine Namensliste davon und fordert die Dateien, die es auswählt, über eine Host-Funktion beim Compiler an, die nur für Dateien unterhalb der Quelle dieses Knotens antwortet.
- Kein Netzwerkzugriff. Plugins sind deterministisch und hermetisch und öffnen keine eigene Verbindung. Eine externe Eingabe, die ein Plugin beim Rendern benötigt — ein entferntes Schema, auf das die Werte eines Charts verweisen —, wird über die Host-Funktion des Compilers für externe Eingaben angefordert, die aus dem Inhalt antwortet, den der Workspace für diese Referenz fixiert hat.
- Deterministische Ausgabe. Bei identischer Eingabe und derselben Plugin-Version muss ein Plugin byteidentische Ausgabe erzeugen. Dies ist der Vertrag, durch den die Garantie byteidentischer Ausgabe des Compilers durchgängig über die Plugin-Schicht hinweg gilt. Ein Build-Lauf mit
--verify-determinismrendert jeden Knoten zweimal und hält an, wenn sich die beiden Renderings eines Knotens unterscheiden.
Die Plugin-Socket-Architektur auf der übergeordneten Ebene der Erweiterbarkeit, einschließlich der anderen Wasm-Sockets in der Kompilierungs-Pipeline (die Transformations- und Verdikt-Rollen des Governance-Sockets), ist in ../../architecture/14-extensibility.md beschrieben.
Die Provider der Standardbibliothek von Aggrega
Die Provider helm, helm-chart, compose, terraform und cloudformation bilden zusammen den Provider-Satz der Standardbibliothek. Sie decken die gängigen Bereitstellungsziele ab, ohne dass Unternehmensteams eigene Provider erstellen müssen.
helm unterstützt alle drei Eingabearten: quellbasiert (ein Upstream-Helm-Chart, das über das Helm SDK abgerufen wird, mit der Ausgabe des valuesMapping des Recipe als Overrides des Charts), synthetisiert (flaches Kubernetes-YAML — ein Controller-Objekt, das durch das Feld form der Workload gewählt wird (Deployment, StatefulSet, DaemonSet, Job oder CronJob), plus Services und PVCs —, erzeugt aus einer geparsten Workload) und Artefakte (eigenständige YAML-Dateien neben der Chart-Ausgabe). Siehe die Provider-Fähigkeitsmatrix in ../../architecture/16-recipe-input-composition.md dazu, welche der drei Arten er akzeptiert.
helm-chart unterstützt den quellbasierten Modus (Umbrella-Chart-Komposition: ein Chart pro Boundary, ein Sub-Chart pro Komponente) und artifacts:, die ihn begleiten, in beiden Authoring-Formen. Ein per $import: geladener Eintrag in artifacts: wird zuerst von Aggrega als Go-Template ausgewertet und dann vor dem Rendern in das Verzeichnis templates/ des Charts eingefügt; ein Eintrag in artifacts: mit Inline-Inhalt wird auf dieselbe Weise ausgewertet und im Root des Sub-Charts abgelegt, ohne eingemischte Herkunftsangaben, wo die eigenen Templates des Charts ihn über Helms .Files.Get / .Files.Glob lesen. Ein eigenständiges Recipe nur aus Artefakten gehört nicht zu den Arten, die er deklariert, und ebenso wenig die synthetisierte Art: Das Umbrella-Chart orchestriert Sub-Charts, während die Workload-Art ein Blattkonzept ist, das in jedes Sub-Chart gehört (die Domäne des Providers helm).
compose unterstützt quellbasiert (lädt eine Compose-Datei und führt das Overlay aus valuesMapping tief mit ihr zusammen), synthetisiert (erzeugt services: + volumes: + networks: für Compose aus einer geparsten Workload für die Formen stateless und stateful, mit eingeschränkter Volume-Behandlung für persistentTemplate — PVCs pro Replik fallen mit einer Warnung zu einem einzigen gemeinsam genutzten benannten Volume zusammen; die Formen daemon, scheduled und task haben keine Compose-Abbildung und halten laut an) und Artefakte (Compose-Fragmente, deren Schlüssel oberster Ebene services: / networks: / volumes: / configs: in die kombinierte Datei docker-compose.yaml pro Boundary zusammengeführt werden). Artefakte können jede der beiden anderen Arten begleiten, und ein eigenständiges Recipe nur aus Artefakten — artifacts: ohne source: und ohne workload: — ist ebenfalls eine Art, die dieser Provider deklariert: Seine Fragmente werden nach denselben Regeln zusammengeführt, sodass der Knoten genau das beiträgt, was er deklariert, und keine Workload braucht, die für Rechenleistung einsteht, die er nicht hat.
terraform unterstützt quellbasiert (übernimmt ein Terraform-Modul unverändert und liefert die Ausgabe des valuesMapping als Argumente des Blocks module dieser Komponente in der Root-Konfiguration der Boundary) und Artefakte (gibt einen verfassten Körper in HCL oder .tf.json so aus, wie sein Template ihn auswertet, ohne ihn umzuschreiben). Er bietet die synthetisierte Eingabeart nicht an — es gibt keine getreue Abbildung von der Workload-Art der Plattform auf beliebige Terraform-Ressourcen. Der Provider erzeugt Konfiguration und führt Terraform nie aus; laufzeitabhängige Werte bleiben als Interpolations-Zeichenketten ${ ... } erhalten, die die Terraform-Laufzeit zum Apply-Zeitpunkt auflöst.
cloudformation rendert eine Boundary in ein einziges AWS-CloudFormation-Stack-Template, indem er die Ressourcenfragmente, die seine Komponenten verfassen, zu einem einzigen reinen JSON-Template assembliert, die provides jeder Komponente als Outputs des Stacks ausweist und Kanten uses innerhalb eines Stacks als Fn::GetAtt und stackübergreifend als Fn::ImportValue / Fn::GetStackOutput verdrahtet. Er unterstützt quellbasierte und Artefakt-Eingaben und erzeugt Konfiguration, ohne jemals CloudFormation auszuführen; reine Laufzeitwerte bleiben als intrinsische CloudFormation-Funktionen erhalten.
Der Provider-Referenzindex führt Sie zur eigenen Referenzseite jedes Providers; welche Eingabearten jeder akzeptiert, beantwortet die Fähigkeitsmatrix in ../../architecture/16-recipe-input-composition.md.
Benutzerdefinierte Provider
Unternehmensteams, die eigene Provider erstellen, folgen demselben Muster wie die Standardbibliothek: Sie erstellen ein Provider-Rendering-Plugin (pluginType: provider), das den oder die Provider-Namen, die es bedient, in spec.provider.capabilities deklariert, neben den übrigen Metadaten in spec.provider, und liefern dann das Wasm-Artefakt aus, das den obigen Rendering-Vertrag implementiert. Der Compiler behandelt benutzerdefinierte Provider genauso wie Provider der Standardbibliothek; die Verteilung pro Provider arbeitet mit dem Provider-Namen, den das Recipe deklariert.
Wie man einen erstellt, ist dokumentiert statt aufgeschoben. Einen Provider erstellen baut durchgängig einen funktionierenden Provider-Guest — die Selbstauskunft describe(), den Build, die Entität Plugin, die Anbindung und ein Rendering, dessen Ausgabe Sie lesen können. Der Entwicklerleitfaden für Wasm-Plugins ist die Referenz für die Entität und den Veröffentlichungslebenszyklus, und der Plugin-Vertrag dokumentiert die Payload- und Ergebnisformen jedes Sockets. Guests werden in Go, Rust oder TypeScript mit dem Plugin-Entwicklungskit verfasst.