Datentaxonomie und Komposition
Die einheitliche Datentaxonomie und die Kompositionsregeln
Um ein vorhersehbares Schema zu schaffen und kognitive Reibung zu beseitigen, verwendet die Plattform genau fünf allgemein verständliche Schlüsselwörter und eine streng Map-basierte (Dictionary-)YAML-Struktur, mit Maps statt verschachtelter Arrays an der strukturellen Wurzel.
1. Der Map-Standard mit 5 Schlüsselwörtern und die vollständige Schemasymmetrie
Das direkte strukturelle Vokabular: Eine grundlegende Regel des Schemadesigns lautet, dass Wurzeldatenstrukturen einzelne, strukturelle Schlüsselwörter sein müssen. Umgangssprachliche englische Wendungen (wie depends_on oder runs_within) können eine YAML-DSL für Entwickler natürlicher lesbar machen, sie bringen jedoch strukturelle Komplexität mit sich, wenn diese Schlüssel auf programmatische Go-Templates abgebildet werden. Um eine direkte 1:1-Variablenzuordnung beizubehalten und eine Fragmentierung der domänenspezifischen Sprache (DSL) zu verhindern, weisen die JSON-Schemas der zentralen Katalogentitäten (Component, Feature) eine nahezu vollständige strukturelle Symmetrie auf, getragen von demselben Kernsatz struktureller Schlüsselwörter, der in allen verfassten Instanz-Slots verwendet wird. Credential-Features (mit dem Label feature.aggrega.ai/kind: secret) teilen genau dieses Paradigma — es gibt kein separates Schema für Secrets.
parameters(der globale Umgebungsvertrag)- Geltungsbereich: Definiert an der Wurzel des
Aggregate; erfüllt durch dasRelease(CI/CD) inline unterparameters:oder überparameters: { $import: <path> }, das auf eine externe Parameterdatei verweist. - Bedeutung: Externe Argumente, die den kognitiven oder logischen Zustand der Anwendung über Umgebungen hinweg dynamisch verändern (z. B.
workers: 2inworkers: 10ändern). Unterstützt einen typisierten Vertrag (siehe data-pillars für die vollständige Syntax des typisierten Vertrags), der vor der Interpolation validiert wird. Für GitOps-Workflows, die Parameterwerte in einer separaten Datei halten, verwendet das Release die Form$import:; der Compiler lädt den Inhalt der Datei und ersetzt die Inline-Mapparameters:. Eine Schichtung über mehrere Dateien wird überextends:-Ketten des Release ausgedrückt.
- Geltungsbereich: Definiert an der Wurzel des
values(die kognitive Absicht - im Besitz des Entwicklers)- Geltungsbereich: Einheitlich verwendet innerhalb von
componentsund ihrenfeatures-Anhängen imAggregate, einschließlich Credential-Features. - Bedeutung: Der zentrale kognitive Zustand, die Geschäftslogik und die operative Konfiguration. Undurchsichtig für den Go-Compiler, aber streng validiert durch die einheitliche
schema:-Deklaration des Katalogs (kompakte Form oder JSON Schema 2020-12).
- Geltungsbereich: Einheitlich verwendet innerhalb von
uses(die strukturelle Topologie - deklarativer Zustand)- Geltungsbereich: Einheitlich verwendet innerhalb von
componentsund ihrenfeatures-Anhängen imAggregate, einschließlich Credential-Features. - Bedeutung: Eine deklarative Tatsachenaussage, die Netzwerkkanten und Abhängigkeiten definiert (z. B. „Dieser Agent verwendet diese Datenbank“). Wird vom Go-Compiler nativ geparst, um den Graphen der Zwischenrepräsentation (IR) zu zeichnen. Validiert durch die einheitliche
usesSchema-Deklaration des Katalogs, um knotenübergreifende Typsicherheit durchzusetzen.
- Geltungsbereich: Einheitlich verwendet innerhalb von
infra(die physische Realität - im Besitz von Ops)- Geltungsbereich: Einheitlich verwendet innerhalb der
componentseiner Boundary und ihrerfeatures-Anhänge imRelease. - Bedeutung: Der physische Footprint und die mechanische Dimensionierung, die beim Late Binding injiziert werden (z. B.
cpu_limit: "4",port: 5432). Die Komponenteninstanzen des Aggregate und ihrefeatures-Anhänge enthalten kein Feldinfraund lehneninfrazusammen mitadditionalProperties: falsebei der Schemavalidierung ab. Validiert durch die einheitlicheschema:-Deklaration des Katalogs.
- Geltungsbereich: Einheitlich verwendet innerhalb der
inject(der Bereitstellungsvertrag - imperativer Befehl)- Geltungsbereich: An einer Komponenteninstanz, innerhalb expliziter Zieldefinitionen in
usesund an angehängtenfeaturesverwendet, einschließlich Credential-Features. - Bedeutung: Ein expliziter, imperativer Befehl, der die Absicht der Bereitstellung vorgibt (z. B. „Compiler, injiziere diesen zugeordneten Wert als Umgebungsvariable“). Er legt den abstrakten Vertrag (
env,file,argoder benutzerdefinierte Mechanismen) für eine physische Ausgabe, einen aufgelösten Endpunkt oder eine abgerufene Anmeldeinformation fest, während die physische Mechanik, wie genau dieses Mounten ausgeführt wird, vollständig an die zugrunde liegende Ops-Recipe delegiert wird. Jeder Mechanismus ist eine Liste von Einträgen ([{ in: API_HOST, from: "host" }]), von denen jeder seinen lokalen Bezeichner mitin:benennt und genau eines vonfrom:odervalue:trägt.
- Geltungsbereich: An einer Komponenteninstanz, innerhalb expliziter Zieldefinitionen in
.context(die generische Metadaten-Pipe)- Geltungsbereich: Vom Compiler stillschweigend in die Templates der Ops-
Recipeinjiziert. - Bedeutung: Trägt das, was der Compiler für den Knoten aus dem Rest des Graphen zusammengestellt hat (wie
.context.uses), und wird direkt an die Templating-Engine von Ops übergeben.
- Geltungsbereich: Vom Compiler stillschweigend in die Templates der Ops-
Die Realität der 1:1-Zuordnung
Indem umgangssprachliche Präpositionen durch strikte Infrastruktur-Schlüsselwörter ersetzt werden, entsteht eine direkte 1:1-Zuordnung. Der Ops-Engineer muss keine Grammatik übersetzen; er referenziert einfach genau die Schlüssel, die der Entwickler geschrieben hat.
Strukturelle Formen: Maps an der Wurzel, Arrays in Payloads. Wurzel-Topologieblöcke — components, features, aggregates, subsystems, boundaries — sind YAML-Maps, deren vom Benutzer verfasste Schlüssel als stabile Instanz-IDs dienen. Arrays sind an diesen Positionen nicht gültig; der Map-Schlüssel ist die Identität, die der Compiler für Querverweise (target: my-db), den Aufbau von Graphknoten und die Manifest-Auflösung verwendet. Innerhalb der undurchsichtigen Payload-Blöcke (values, infra, parameters) sind Arrays uneingeschränkt erlaubt — Entwickler können tools_allowed: ["sql", "web"] oder hostnames: ["stripe.com", "twilio.com"] in die values einer Component schreiben. Das Aggregate-Schema deklariert diese Payload-Blöcke als additionalProperties: true, sodass sie für den Go-Compiler undurchsichtig sind und vollständig durch die eingebettete schema:-Deklaration des Katalogs validiert werden. Damit liegt die Volatilität der Frameworks (neue Formen von KI-APIs, neue Cloud-native Payload-Formate) in der Katalogdomäne, wo sie sich unabhängig entwickeln kann, während der Go-Compiler an der strukturellen Wurzel auf adressierbare Schlüssel beschränkt bleibt.
2. Die Informationsflüsse: Wer, wann und wofür?
Um Namensraumkollisionen in Templates und das unbeabsichtigte Durchsickern physischer Infrastrukturkonfigurationen in die kognitive Anwendungslogik zu verhindern, trennt die Architektur Daten explizit in sechs verschiedene Ströme:
- Fluss 1: Die Umgebungsinjektion (
parameters): Die CI/CD-Pipeline injiziert Deployment-Realitäten. Der Compiler validiert jeden vom Release gelieferten Wert gegen den typisiertenparameters:-Vertrag und interpoliert dann die aufgelösten Go-Template-Variablen, bevor die nachgelagerte Schemavalidierung vonvalues:ausgeführt wird.- Empfohlene Verwendung:
parameterssind kognitiver Anwendungslogik vorbehalten, die zwischen Umgebungen variiert (z. B.LOG_LEVEL=debug,ENABLE_BETA=true). Operative Dimensionierung und Belange der physischen Infrastruktur — Replikate, CPU-Limits, AWS-ARNs, Ingress-Hostnamen — fließen durch deninfra-Block desReleaseund die Boundary-Overlays, sodass dasAggregatedes Entwicklers auf die Anwendungsabsicht fokussiert bleibt. - Pragmatischer Ausweg: Für kleinere Teams, schnelles Prototyping oder ältere CI/CD-Integrationen, bei denen eine strikte Trennung nicht praktikabel ist, können
parametersglobale Umgebungskonfigurationen durch den Stack tragen. Der Compiler akzeptiert alles, was die Schemavalidierung besteht; die obige Empfehlung ist ein Gesellschaftsvertrag, keine Compiler-Regel.
- Empfohlene Verwendung:
- Fluss 2: Kognitive Anwendungsabsicht (
valuesin Components): Definiert die intrinsische Anwendungslogik. Dieschema:-Deklaration der Component (kompakte Form oder JSON Schema 2020-12) bietet strikte Typprüfung und Validierung für diese Payload, liefert Entwicklern sofortiges „Shift-Left“-Feedback und stellt sicher, dass die angeforderten Konfigurationen zur zugrunde liegenden Infrastruktur-API passen. - Fluss 3: Operative Feature-Absicht (
valuesin Features): Im Aggregate fordert der Entwickler die Infrastrukturfähigkeiten an, deren Verhalten Anwendungsabsicht ist, und fragt streng typisierte Anmeldeinformationen ab, ohne den internen Code zu ändern. Ein Feature, dessen Eingaben alle operativ sind, trägt keine Entwickler-values: Der Betrieb hängt es im Release an, mit seineminfra(Fluss 4). - Fluss 4: Dimensionierung der physischen Infrastruktur (
infra): Unter vollständiger Umgehung des Entwicklers wird die physischeinfra-Dimensionierung explizit aus dem umgebungsspezifischenReleasedirekt auf lokal begrenzte Components und ihre angehängten Features projiziert, einschließlich Credential-Features. Um Validierungskollisionen mit geschlossenen Schemas durch die wörtliche Verbreitung von Dictionaries zu vermeiden, ist dieinfra-Dimensionierung strikt auf die explizite Komponente begrenzt, die sie adressiert. Das hält Rechenlimits, Replikate und mechanische Ressourcenanforderungen in der Ops-Domäne. - Fluss 5: Kaskadierende Annotationen (kontextuelle Metadaten): Breite kontextuelle Daten (wie operative Domänen, Namespaces oder Abrechnungscodes) werden über kaskadierende Annotationen behandelt, was eine Verschmutzung durch verbreitete
infraverhindert. Sie werden nach ihrer Herkunft in Buckets getrennt, und der unten beschriebene vorgesehene Zweck jedes Buckets ist ein Gesellschaftsvertrag: Ein Recipe-Template kann alle drei lesen, und der Compiler erzwingt die Trennung nicht (siehe labels-and-annotations):.context.annotations.release(Boundaries der Domäne 4): Ausschließlich zur Steuerung physischer Realitäten verwendet. Ops leitet diese Annotationen über Go-Templates explizit in strikte lokaleinfra-Felder (z. B. indem ein regionaler Namespace einer Rechenkomponente zugeordnet wird)..context.annotations.aggregate(Subsysteme der Domäne 1): Ausschließlich zur Steuerung kognitiver und operativer Logik verwendet. Diese Annotationen werden explizit in dievalues-Payloads der Komponente geleitet (z. B. indem ein Team-Abrechnungscode kaskadierend bis in eine Anwendungskonfiguration weitergegeben wird)..context.annotations.catalog(Katalog der Domäne 2): Unveränderliche intrinsische Merkmale, vom Architekten verfasst und vor allem für die programmatische Auswertung von Wasm-Richtlinien verwendet.
- Fluss 6: Die Metadaten-Pipe (
.context): Wendet globale Unternehmensanforderungen (SOC2-Tags) direkt auf die Templates der physischen Infrastruktur an.
3. Netzwerkabstraktion: Die „Zero-Port“-Konvention
- Die Best Practice: Entwickler sollten Ports im
Aggregateweglassen. Die Ops-Recipe übernimmt das interne Routing dynamisch. - Der Ausweg: Wenn der interne Code einer Anwendung nicht geändert werden kann, stellt der Plattformarchitekt in der
schema:-Deklaration explizit ein Feldportbereit. Architekturhinweis: Die „Zero-Port“-Konvention ist das prominenteste Beispiel für die umfassendere Trennung der Zuständigkeiten der Plattform. Genau dieselbe Philosophie — die physische Mechanik vom Entwickler fernzuhalten — gilt für CPU-Anforderungen, Speicherlimits, operative Domänen und Festplattendimensionierung. Wann immer eine Einschränkung der physischen Infrastruktur in die Anwendungs-Payload des Entwicklers durchsickern muss (wegen Legacy-Code oder strikter Hardwareanforderungen), muss sie stets durch einen expliziten „Ausweg“ in derschema:-Deklaration des Architekten geregelt werden, der Deklaration, gegen die die Payload des Entwicklers validiert wird.
Der Name „Zero-Port“ steht für diese Konvention; das Prinzip lässt sich auf jede Einschränkung der physischen Infrastruktur verallgemeinern, die eine Legacy-Anwendung fest codiert. Das folgende Schema verwendet tcp_keepalive_seconds als ausgearbeitetes Beispiel — ein Kernel-/Netzwerk-Timing, das die Anwendung auf der Socket-Ebene erwartet —, weil es eindeutig auf der Achse des Infra-Durchsickerns liegt.
Das Schema (Domäne 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }Das Entwickler-YAML (Domäne 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaCompiler-Verhalten: Der Go-Compiler übergibt tcp_keepalive_seconds: 120 in den IR-Graphen. Die Ops-Recipe liest dann {{ .values.tcp_keepalive_seconds }}, um die Kubernetes-Pod-Spezifikation oder das Idle-Timeout des Load Balancers des Cloud-Providers zu konfigurieren, und überbrückt so die Legacy-Lücke, ohne das Schema zu verletzen.
4. Der Injection-Vertrag und die vorab aufgelöste Map
Unter den fünf strukturellen Schlüsselwörtern hat inject eine andere Form als seine Geschwister. parameters, values, uses und infra sind deklarativer Zustand — der Entwickler schreibt Fakten darüber, was die Anwendung ist und wovon sie abhängt. inject ist ein imperativer Befehl — der Entwickler gibt vor, wie ein Wert an den laufenden Container geliefert werden soll, und ordnet abstrakte Datenquellen (die provides-Schlüssel eines Ziels, die eigenen Werte der Komponente, die Vault-Antwort eines Credential-Feature) konkreten Bereitstellungsmechanismen zu (env, file, arg oder ein benutzerdefinierter Mechanismus, den die Component deklariert).
Diese Entkopplung ist strukturell. Das Aggregate des Entwicklers sagt „injiziere den Datenbank-Host als Umgebungsvariable DB_HOST“, ohne die physische Adresse der Datenbank, den Vault-Pfad des Secret-Stores oder das Hostnamenformat des Cloud-Providers zu nennen. Die Ops-Recipe erhält die aufgelöste Zeichenkette über .context.inject und verwendet sie, ohne die Lookup-Kette selbst zu verfassen.
Die vorab aufgelöste Map. Beim Rendering löst der Compiler jede Inject-Quelle — Self-Inject-Literale und from:-Referenzen auf die eigenen provides der Komponente, komponentenübergreifende Referenzen über uses[].inject, injectMapping-Abfangungen des FeatureRecipe — in ein einziges flaches Dictionary unter .context.inject auf. Wenn das valuesMapping-Template der Basis-Recipe läuft, trägt jeder Inject-Schlüssel bereits seinen endgültigen Zeichenkettenwert. Recipes iterieren direkt über die Map ({{ range $k, $v := .context.inject.env }}), ohne die Auflösungskette zu durchlaufen.
Die Namen des Entwicklers für die eigenen Werte der Komponente. Wo die Component spec.inject deklariert, wählt der eigene Block inject: des Entwicklers die Namen, unter denen die eigenen Werte und provides der Komponente die Zustell-Pipe erreichen. Der Compiler teilt dem Recipe unter .context.self_inject den einen eigenen Wert mit, den das Template jedes Eintrags liest — je Mechanismus jeder Name zugeordnet zu provides.<key>, zu values.<key> für ein Template, das genau einen eigenen Wert und sonst nichts liest, oder zu einer leeren Zeichenkette —, in der Form, die die Namen einer Verbindung unter .context.uses.<alias>.inject annehmen. Die Konvention des Standardbibliothekskatalogs für ein Recipe, das das Image des Entwicklers ausführt, besteht darin, die Namen, die es sonst für die eigenen Werte der Komponente wählen würde, als Standardwerte zu behandeln und einen eigenen Wert nur dann unter seinem Standardnamen zu liefern, wenn noch kein Eintrag ihm zugeordnet ist. Das ist eine Konvention des Katalogs, keine Regel des Compilers: Ein Unternehmenskatalog kann die eigenen Werte seiner Komponenten liefern, wie er es wünscht. Der Compiler liest die Zuordnung aus dem Text, den der Entwickler geschrieben hat, und misst den Namen keine Bedeutung bei.
Die vollständige Spezifikation des Injection-Vertrags — Semantik des Kontexts mit doppeltem Zustand, Regeln für Schlüsselkollisionen, das Abfangmodell des FeatureRecipe und ausgearbeitete Beispiele — findet sich in topology-triad.
5. Die Templating-Engine (Ops-DX)
Platform-Ops-Engineers verfassen die Übersetzungstemplates und benötigen die volle Leistungsfähigkeit des üblichen Infrastruktur-Templatings ohne proprietäre Template-Sprache. Die Templates von Aggrega sind Go-text/template:
- Keine „magischen“ Zeichenketten: Der Compiler bewahrt die exakten Map-Schlüssel des Entwicklers. Ops greift sicher über die übliche Go-Map-Indizierung auf Features zu:
{{ (index .features "public-route").infra.hostname }}. - Die Sprig-Bibliothek: Der Compiler registriert nativ die Helm-übliche Sprig-Bibliothek und bietet so sofortigen Zugriff auf Pipelines wie
| default,| quoteund| toYaml. - MappingLibrary-Fragmente: Ein Mapping-Fragment, das mehrere Recipes wiederverwenden, liegt in einer MappingLibrary und wird mit
$import:in jedes Recipe eingebunden. Die Chart-Template-Helfer von Helm (include,tpl,required,warn) sind nicht registriert; sprig-functions listet auf, was registriert ist.
6. Kompositionsregeln: Aggregates, Subsysteme und Components
- Logische Gruppierung (das
subsystems-Array): Entwickler können mitsubsystemslogische Metadaten (Teamzuständigkeit, Compliance-Labels) und übergreifende Features auf Dutzende von Komponenten gleichzeitig anwenden. Subsysteme wirken als rekursive Ordner auf der logischen bzw. Absichtsebene, gebenannotationskaskadierend nach unten in den Bucket.context.annotations.aggregateweiter und hängen Features an alle enthaltenen Komponenten an, ohne physische Grenzen vorzugeben. Features auf Subsystemebene folgen demselben Schema wie Features auf Komponentenebene (mit Unterstützung fürtype,values,uses,inject), weil sie in Domäne 1 (Entwicklerabsicht) liegen. Der Compiler flacht die Subsystem-Features bei der Finalisierung des Graphen in die Feature-Liste jeder enthaltenen Komponente ab, in der Ausführungsreihenfolge nach den eigenen Features der Komponente und vor allen im Release angehängten Features.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Zusammengesetzte Aggregates werden UNTERSTÜTZT (das Modulmuster): Aggregates fungieren sowohl als Stamm-Aggregate, das ein Release baut, als auch als wiederverwendbare Module. Ein übergeordnetes Aggregate kann ein untergeordnetes Aggregate genau wie eine Komponente deklarieren und
parametersan es weitergeben. Um eine enge Kopplung zu vermeiden, stellen untergeordnete Aggregates einenexportedComponents:-Vertrag bereit, der einen stabilen öffentlichen Schnittstellennamen festlegt. Das übergeordnete Element erreicht die Komponenten des Moduls nur über diese Schnittstelle: Einuses:-Ziel nennt das Modul und einen seiner exportierten Aliasse, und der Compiler verdrahtet die Kante mit der internen Komponente, die der Alias benennt, während ein Ziel, das über einen anderen Namen in ein Modul hineingreift, den Build anhält und dabei das Modul und die von ihm exportierten Aliasse nennt. Ein Modul kann seinerseits die exportierte Komponente eines verschachtelten Moduls unter seinem eigenen Schnittstellennamen erneut exportieren — optional unter neuem Namen —, und der Compiler löst eine solche Re-Export-Kette transitiv bis zum zugrunde liegenden internen Knoten auf, sodass Module sich in beliebiger Tiefe zusammensetzen lassen, ohne dass ein übergeordnetes Element wissen muss, wie tief das Ziel verschachtelt ist. Ein Ziel, das zu keinem internen Knoten aufgelöst wird, hält den Build weiterhin deutlich an, und eine Re-Export-Kette, die sich zu sich selbst schließt, wird abgelehnt, statt endlos verfolgt zu werden.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components können keine Unterkomponenten enthalten: Components sind atomare Bausteine. Die Komposition erfolgt auf Aggregate-Ebene über Subsysteme und Sub-Aggregate. Wenn eine Anwendung mehrere physische Container benötigt (etwa eine API + einen Sidecar), lebt diese physische Verschachtelung im Template der Ops-Recipe, nicht in der Component-Definition.
-
Ein zusammenhängender Dienst pro Component — die Grenze des einzelnen Workloads: Eine Component modelliert einen zusammenhängenden Dienst — einen einzelnen bereitgestellten Dienst oder den bzw. die Workloads eines Dienstes zusammen mit seinen ausschließlich internen Hilfs-Workloads. Ihr Label
component.aggrega.ai/typebenennt die operative Form dieses einen Dienstes. Mehrere physische Workloads innerhalb einer einzelnen Component sind in Ordnung, wenn sie ein zusammenhängendes Produkt ohne unabhängig nutzbare Teile bilden: Ein Dienst, dessen Chart einen Controller plus einen Webhook plus einen Injector ausführt, ist dennoch eine Component. Nicht mehrere Workloads sind das Kriterium, sondern die unabhängige Nutzbarkeit.Die Grenze wird dort gezogen, wo ein Bundle etwas enthält, das eine andere Komponente sinnvoll für sich allein verwenden (
use) könnte — insbesondere fremde Infrastruktur wie eine Datenbank, ein Cache oder ein Message Broker, die Aggrega bereits als eigene Component modelliert. Ein solches Bundle ist nicht eine Component; es ist ein Sub-Aggregate-Modul — das oben gezeigte Musterspec.aggregates+exportedComponents—, das eine Component pro Dienst zusammensetzt, sodass jeder Dienst ein adressierbarer Knoten mit eigenem Typ, eigenen Kanten und eigener Richtlinien- und Skalierungsoberfläche ist.Die Heuristik, als klare Regel formuliert: Enthält das Chart etwas, das eine andere Komponente sinnvoll für sich allein verwenden könnte, oder für das Aggrega bereits eine Component hat? Falls ja, modellieren Sie es als Stack — ein Sub-Aggregate-Modul, das Components pro Dienst zusammensetzt. Falls es immer nur diesem einen Dienst dient, modellieren Sie es als eine Component.
Ein ganzes Produkt aus mehreren Diensten als einzelne undurchsichtige Component zu verpacken, ist ein dokumentiertes Antipattern. Der Compiler ist meinungslos und akzeptiert es — er rendert alles, was die Schemavalidierung besteht —, doch die Standardbibliothek setzt stattdessen Components pro Dienst zu einem Modul zusammen, weil eine monolithische Verpackung die unabhängig modellierbaren Dienste vor der Topologie, vor dem Selektor und vor dienstbezogenen Richtlinien und Skalierung verbirgt. Diese Granularitätsdisziplin ist ein Gesellschaftsvertrag — siehe
../language-reference/vocabulary/social-contracts.md(Component-Granularität).
7. Der Standard-Scope — schrittweise Offenlegung der Gruppierung
subsystems (im Aggregate) und boundaries (im Release) sind die Gruppierungskonstrukte, doch ein Entwickler muss sie nicht von vornherein deklarieren. Jede Entität bietet zwei Formen der Erstellung an, und diese schließen sich gegenseitig aus: Komponenten werden entweder unter benannten Scopes gruppiert verfasst, oder Komponenten werden direkt auf oberster Ebene verfasst — niemals beides zugleich. Ein Dokument, das sowohl components auf oberster Ebene als auch benannte Scopes deklariert, bricht beim Laden mit einem Envelope-Fehler ab.
Für die flache Form (components auf oberster Ebene) synthetisiert der Compiler beim Laden einen echten default-Scope und faltet die Komponenten der obersten Ebene hinein, sodass jeder nachgelagerte Durchlauf eine einheitliche, Scope-tragende Struktur sieht. Der synthetisierte Scope ist kein versteckter Container: Er ist ein echter, mit seiner Herkunft gekennzeichneter Knoten in der IR, unterscheidbar von einem Scope, den ein Entwickler ausdrücklich default nennt. Verborgen ist er nur dort, wo der Autor Pfade liest — Diagnosen und Adressierung geben den wurzelförmigen Pfad .spec.components[…] wieder, den der Entwickler tatsächlich geschrieben hat.
- Flaches Aggregate (Komponenten auf oberster Ebene): Komponenten werden unter
spec.componentsohnesubsystemsverfasst. Der Compiler faltet sie beim Laden in ein synthetisiertesdefault-Subsystem. Annotationen auf Subsystem-Scope und Features auf Subsystem-Ebene gelten nur für deklarierte Subsysteme; die flache Form trägt keine. - Flaches Release (Komponenten auf oberster Ebene): Komponenten werden unter
spec.componentsohneboundariesverfasst. Der Compiler faltet sie in eine synthetisiertedefault-Boundary, deren Ausgabe flach ist — Artefakte landen direkt unterdist/(je Provider:dist/compose/,dist/helm/, …), ohne ein Segment mit dem Boundary-Namen. Dies ist der einfachste Fall:aggrega buildüber ein flaches Compose- oder Single-Cluster-Ziel, ohne Boundaries zu benennen. (Eine Boundary, die ein Entwickler deklariert unddefaultnennt, ist eine gewöhnliche benannte Boundary und gibt ohne eigenesdirectory:wie jede andere nachdist/boundaries/default/aus.) - Der Upgrade-Pfad: Wenn eine flache Architektur zu einer wächst, die Gruppierung braucht (unterschiedliche Namespaces, getrennte logische Gruppierungen, Deployment über mehrere Boundaries), verschiebt der Entwickler die Komponenten der obersten Ebene in explizite
subsystems, oder Ops führt expliziteboundariesein. Da sich die beiden Formen gegenseitig ausschließen, ist dies ein Wechsel von der flachen in die gescopte Form — keine Mischung aus beiden —, und die Knotenidentität bleibt über den Übergang hinweg erhalten.
Der Grund ist schrittweise Offenlegung: Eine verpflichtende Gruppierung für triviale Anwendungsfälle (eine Demo mit einem einzigen Dienst, ein schneller lokaler Prototyp) erzeugt unnötige Reibung. Der Onboarding-Test „in 10 Minuten von null zum funktionierenden Ergebnis“ verlangt, dass ein Entwickler ein minimales Aggregate mit einer Komponente, einem Manifest und einem Release schreiben und eine funktionierende Ausgabe erhalten kann, ohne zuerst Subsysteme oder Boundaries verstehen zu müssen. Der Standard-Scope ist die Auffahrt; deklarierte Scopes sind das, wohin eine Architektur wächst.
8. Architektonische Einschränkungen und empfohlene Muster
Die folgenden Einträge sind ein empfohlenes Muster und fünf Einschränkungen. Die Schemas erzwingen die Einschränkungen 4 und 5 — das Release hat keinen values-Block, und die Komponenteninstanz eines Aggregate hat keinen Schlüssel labels; die übrigen sind Konventionen, die der Compiler nicht prüft.
-
Empfohlenes Muster: Parameter-Hoisting über Template-Strings
- Beispiel: Der Entwickler schreibt
workers: {{ .parameters.env_workers }}in seinenvalues-Block, ohne Anführungszeichen, sodass der Wert als die Ganzzahl ankommt, als die er deklariert wurde. - Warum: Wenn das Aggregate
env_workersals typisierten Parameter (type: integer) deklariert, validiert der Compiler zuerst den vom Release bereitgestellten Wert gegen den Vertrag. Die Validierung des Parametervertrags erfolgt vor der Interpolation; die Interpolation erfolgt vor der Validierung des umgebendenvalues:-Schemas. Dies erhält die Wiederverwendbarkeit des Aggregate: Ops liefert die Ganzzahl über dieparameters:desRelease, der Compiler validiert sie gegen die typisierteparameters:-Deklaration, setzt den aufgelösten Wert in das Dokument ein, und dieschema:-Deklaration der Component validiert die resultierende Ganzzahl erfolgreich.
- Beispiel: Der Entwickler schreibt
-
Einschränkung 1: Zugangsdaten sind Anhänge, keine Werte
- Abgeratenes Muster: Der Entwickler schreibt
values: { password: "123" }an eine Komponente. - Warum: Die Konvention der Standardbibliothek ist, dass Zugangsdaten als Anhang unter
features:angefordert werden, wobei ein Feature-typefür Zugangsdaten benannt wird (einer mit dem Labelfeature.aggrega.ai/kind: secret) und die eigenenvaluesdieses Anhangs die Abfrage an einen Secret-Store beschreiben. Dies ist eine Konvention, keine Prüfung des Compilers — der Compiler interpretiert nicht, was einvalues-Blatt bedeutet, und überträgt ein Inline-Literal unverändert. Die Anhangsoberfläche ist es, die die sauber verfasste Form verfügbar und typisiert macht.
- Abgeratenes Muster: Der Entwickler schreibt
-
Einschränkung 2: Fähigkeitsagnostische Components
- Nicht unterstütztes Muster: Der Architekt schreibt
aws_instance_type: stringin dieschema:-Deklaration der Component. - Warum: Components sind per Konvention agnostisch gegenüber Fähigkeiten. Physische Hardwareziele gehören in Ops-Recipes oder generische
.context-Annotationen, nicht in die kognitive Kernlogik der Anwendung.
- Nicht unterstütztes Muster: Der Architekt schreibt
-
Einschränkung 3: Bedingte Logik auf Metadaten
- Nicht unterstütztes Muster: Ops schreibt
{{ if eq .context.labels.gpu "true" }}in einRecipe, um die Deployment-Strategie grundlegend zu ändern. - Warum: Der
.context-Kanal umgeht dieschema:-Validierung der einzelnen Säulen. Sich bei der Kernlogik der Infrastruktur auf nicht validierte Labels zu verlassen, macht die Plattform fragil. Das.context-Objekt trägt Metadaten-Tags (z. B. Abrechnung, SOC2); strukturelles Routing gehört in schemavalidierte Säulen.
- Nicht unterstütztes Muster: Ops schreibt
-
Einschränkung 4: Das Release kann Entwicklerwerte nicht überschreiben
- Nicht unterstütztes Muster: Ops versucht, die kognitive Logik eines Entwicklers vom
Releaseaus zu überschreiben (z. B.workers: 4inworkers: 10zu ändern). - Warum: Das
Aggregateist die einzige Quelle der Wahrheit für die Absicht des Entwicklers. Ist ein Wert imAggregatefest codiert, ist er über alle Umgebungen hinweg unveränderlich. Muss sich ein Wert je Umgebung ändern, verwendet der Entwickler Parameter-Hoisting. DasRelease-Schema setzt dies durch, indem esvalues-Blöcke verbietet und Ops darauf beschränkt, denparameters-Vertrag zu erfüllen und die physischeinfrazu definieren.
- Nicht unterstütztes Muster: Ops versucht, die kognitive Logik eines Entwicklers vom
-
Einschränkung 5: Labels auf Instanzebene im Aggregate
- Nicht unterstütztes Muster: Der Entwickler schreibt
labels: {}an eine Komponenteninstanz innerhalb desAggregate. - Warum: Labels sind unveränderliche Merkmale auf Katalogebene, die der Plattformarchitekt verfasst — die semantische Identität, die Policy-Engines und Selektoren lesen. Das Release leitet Komponenten über explizites, Map-basiertes ID-Targeting (
components: { "my-agent": {} }) an Boundaries weiter, was die Möglichkeit erhält,infraund Feature-Überschreibungen je Komponente zu verschachteln, ohne die Urheberschaft von Labels in das Aggregate des Entwicklers zu mischen.
- Nicht unterstütztes Muster: Der Entwickler schreibt
9. Der Sicherheitsperimeter & explizite Egress-Guardrails (Ziele außerhalb des Perimeters)
Keine Anwendung existiert im luftleeren Raum. Eine kompilierte Aggrega-Architektur stellt einen streng abgebildeten Graphen dar. Moderne KI-Systeme interagieren jedoch ständig mit Entitäten außerhalb dieses kompilierten Perimeters — etwa mit öffentlichen SaaS-LLMs (Anthropic, OpenAI), generischen öffentlichen APIs (Stripe, Twilio) oder Brownfield-Altdatenbanken (On-Premise-Oracle).
Um diese externen Systeme sicher zu integrieren, trennt Aggrega die Sicherheitsgrenze strikt von der Ausführungsmechanik. Die Sicherheitsgrenze wird durch die universelle Component-Regel und den expliziten Egress-Guardrail geregelt.
1. Die universelle Component-Regel
Interagiert eine Anwendung mit einer Entität — ob lokale Datenbank, verwaltete Cloud-Ressource, SaaS-LLM oder generischer öffentlicher API-Endpunkt —, MUSS diese Entität als eigene Component im Aggregate deklariert werden. Diese Regel ist eine Konvention: Der Compiler kann einen Aufruf, den die Anwendung tätigt, nicht sehen, daher prüft nichts sie.
Indem externe SaaS-APIs und Altdatenbanken als vollwertige Knoten im Graphen der Zwischendarstellung (IR) behandelt werden, erhalten Entwickler die Möglichkeit, Zero-Trust-Proxy-Konfigurationen direkt an den ausgehenden Aufruf anzuhängen. Modelliert ein Entwickler beispielsweise die Stripe-API als eigenen Knoten, kann er ihr ein header-injector-Feature anhängen und so sicherstellen, dass die generierte Konfiguration verhindert, dass der aufrufende Agent das rohe API-Token in seinem eigenen Speicher hält.
2. Der explizite Egress-Guardrail (Infrastrukturkonformität)
Statt sich zur Steuerung des Netzwerk-Egress auf fest codierte Compilerlogik zu verlassen, delegiert Aggrega die Perimetersicherheit vollständig an die agnostischen Policy-Engines des Unternehmens und an Wasm-Rendering-Plugins. So wird sichergestellt, dass die generierten Konfigurationen strikt den expliziten Egress-Freigaben entsprechen.
- Der Katalog-Hook (Domäne 2): Wenn ein Architekt eine öffentliche SaaS-Komponente definiert (z. B.
core/external-service), hängt er ihr ein unveränderliches Unternehmenslabel an (z. B.security.enterprise.com/zone: "untrusted-external"). - Der Policy-Guardrail (zur Kompilierzeit): Bevor irgendeine Konfiguration generiert wird, wertet die Policy-Engine OPA oder Kyverno den Graphen aus. Das Unternehmen verfasst eine einfache Regel: „Wenn sich ein interner Knoten mit einem Knoten verbindet, der mit
untrusted-externalgelabelt ist, muss die ID dieses Zielknotens ausdrücklich im Arrayparameters.approved_egressder Umgebung aufgeführt sein.“ Versucht ein Entwickler, Daten an ein nicht freigegebenes externes Ziel zu leiten, bricht die Policy-Engine den Build ab. - Die Konfigurationserzeugung (zur Renderzeit): Besteht die Policy, wird die Egress-Regel aus dem gerendert, was der Operator angehängt hat. Das Feature
core/egress-allowlist, im Release an die aufrufende Komponente angehängt, rendert aufhelmeine Kubernetes-NetworkPolicypro Workload, den diese Komponente rendert, und erlaubt Egress nur zu ihren eigenen Pods, zu den Pods der Ziele ihreruses-Kanten auf den Ports, die diese Pods deklarieren, zum DNS des Clusters und zu den Adressbereichen, die der Anhang für ein Ziel auflistet, das der Cluster nicht betreibt, etwa eine öffentliche SaaS-API. Der Build bricht ab, sofern das Release nicht mitinfra.control_plane_present: truebestätigt, dass das Netzwerk-Plugin des Clusters Network Policies durchsetzt, und bricht unter Nennung jeder solchen externen Verbindung ab, für die kein Adressbereich aufgeführt ist; aufcompose, das keine Network Policy kennt, bricht der Anhang den Build ab. Der Entwickler schreibt nie eine Firewall-Regel.
Dies garantiert — über eine Governance-Verdict-Rolle, die die deklarierte Topologie auswertet —, dass die ausdrücklich deklarierte Infrastruktur der Egress-Policy entspricht, ohne dass der Go-Kerncompiler verstehen muss, was „extern“ bedeutet. (Hinweis: Echter Zero-Trust-Egress setzt voraus, dass auf dem Zielcluster zur Laufzeit ein Default-Deny-CNI läuft; die generierten Konfigurationen bilden lediglich die autorisierten Ausnahmen ab).
Eine Component pro externem Dienst
Jeder externe Dienst wird als eigene Komponente deklariert, nicht in ein Array mit mehreren Zielen zusammengefasst. Ruft eine Anwendung fünf verschiedene Drittanbieter-APIs auf, deklariert der Entwickler fünf eigene core/external-service-Komponenten. Diese Deklaration pro Dienst ermöglicht es Policy-Engines und Wasm-Plugins, jedes ausgehende Ziel einzeln anzusprechen — und jeder externen Abhängigkeit unterschiedliche Egress-Policies, unterschiedliche Proxy-Features oder unterschiedliche Observability-Hooks anzuhängen.
Sicherheit von Ausführung entkoppeln (das „Brownfield“-Szenario)
Es ist entscheidend zu beachten, dass das semantische Label (z. B. untrusted-external) die Netzwerksicherheits-Policy bestimmt, nicht die Ausführung. Es ist unabhängig davon, ob Aggrega Artefakte rendert, die die Ressource bereitstellen.
- Szenario A (öffentliche SaaS-API): Im Katalog mit
untrusted-externalgelabelt (löst die Egress-Guardrails der Policy aus). Realisiert durch einen Referenz-Workload (keine Rechenressourcen bereitgestellt; siehe §10). - Szenario B (interne Altdatenbank): Mit
internal-trustedgelabelt (umgeht die Egress-Guardrails, bleibt innerhalb der VPC). Realisiert durch einen Referenz-Workload (keine Rechenressourcen bereitgestellt; siehe §10). - Szenario C (selbst gehostete Datenbank): Mit
internal-trustedgelabelt. Ausgeführt über das Helm-Renderer-Plugin (physisch als Kubernetes-StatefulSet bereitgestellt).
10. Dienste, die der Build nicht bereitstellt: Referenz-Workloads
Interagiert eine Anwendung mit einer On-Premise-Altdatenbank oder einer öffentlichen SaaS-API (etwa Stripe), schreibt die universelle Component-Regel vor, dass diese externen Entitäten als eigene Komponenten im Aggregate deklariert werden müssen. Aggrega darf jedoch nicht versuchen, für sie ein physisches Artefakt für einen Kubernetes-Pod oder eine AWS-RDS-Instanz zu generieren.
Das Recipe, das eine solche Komponente realisiert, deklariert einen Workload mit form: reference: einen endpoint — einen Host oder eine URL —, optional einen port und keine Container. Der Compiler leitet beide als deterministische Zeiger-Strings durch und löst sie nie auf. Was ein Provider für einen Referenz-Workload rendert, ist Sache des Providers: helm gibt einen ExternalName-Service aus, der den Host des Endpunkts trägt, sodass Workloads im Cluster einen Dienst, dessen Endpunkt ein DNS-Name ist, unter einem stabilen clusterinternen Namen erreichen können; compose rendert dafür nichts. Kubernetes behandelt einen externalName als DNS-Namen, sodass ein als IP-Adresse geschriebener Endpunkt unter der Adresse erreicht wird, die ein Konsument erhält, und nicht über den Service.
Bei beiden Providern erreichen die provides: des Recipe jeden Konsumenten über .context.uses und den inject-Vertrag genau wie die einer bereitgestellten Komponente. Die Verdrahtung eines Konsumenten ändert sich daher nicht, wenn sein Ziel von bereitgestellt zu referenziert wechselt: Es ändert sich nur das Recipe, dem das Manifest das Ziel zuordnet.
Die Ausführungspipeline Schritt für Schritt
1. Domäne 1 (das Aggregate): Entwicklerabsicht Der Entwickler fordert eine Oracle-Altdatenbank an. Wo sie liegt, ist ihm gleich; er legt nur fest, dass sein aufrufender Agent erwartet, den Verbindungsstring als Umgebungsvariable zu erhalten. Da die IP statisch und im Voraus bekannt ist, übergibt er sie über Parameter.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Domäne 4 (das Manifest): Das Routing Ops ordnet den Typ der Altdatenbank dem Recipe zu, das ihren Verbindungsstring formatiert. Das Manifest benennt ein Recipe und sonst nichts; das benannte Recipe deklariert einen Workload mit form: reference, und diese Form verhindert, dass der Knoten Rechenressourcen bereitstellt. Das Routing bleibt vollkommen flach und vorhersehbar, weil die Map unabhängig vom Ziel genau eine Form hat.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Domäne 3 (das Referenz-Recipe): Strukturierung der Übergabe Der Ops-Engineer schreibt das Recipe. Es baut in seinem locals-Block aus den values des Entwicklers den Verbindungsstring primary_endpoint, veröffentlicht ihn unter provides und deklariert einen Referenz-Workload, der auf den Host der Datenbank zeigt.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Compilerausführung beim Rendering (die Übergabe)
- Der Compiler wertet das Recipe für
legacy-oracleaus. Für ein Release, daslegacy_oracle_ip: "10.0.4.55"liefert, ist seinprimary_endpointgleichoracle://10.0.4.55:1521/PROD_DB. - Auf
helmrendert der Referenz-Workload einen ExternalName-Service,legacy-oracle, mitexternalName: 10.0.4.55und Port1521; aufcomposerendert er nichts. - Anschließend rendert der Compiler das Recipe für
my-agent. Sein.context.uses-Kanal trägt dieprovidesdes Oracle-Knotens, und der Injektionsvertrag hatORACLE_DSNbereits anhand dieser aufgelöst.
5. Domäne 3 (das aufrufende Recipe): Erfüllung des Vertrags Das Standard-Helm-Rezept für den Python-Worker liest die erhaltene Inject-Map, genau wie es das für eine Datenbank täte, die der Build bereitstellt.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Säulenübergreifendes Piping per Schema-Bridge: Brücke von der Absicht zur Infrastruktur
Siehe inheritance-and-interface für das Schema-Bridge-Muster, das spezialisierte Infrastrukturregler sicher über Kindkomponenten zugänglich macht — ein entwicklerseitiges values:-Feld, deklariert im schema: der Component, das die valuesMapping:-Vorlage des Recipe in die gerenderte, infra:-förmige Ausgabe leitet.
12. Greenfield-Provisionierung („Plattform-Aggregates“)
Eine wiederkehrende Falle im Platform Engineering besteht darin, den Router (die Release-Datei) zu zwingen, aufwendige Day-0-Cluster-Provisionierung zu übernehmen (z. B. einen neuen AWS-EKS-Cluster hochzufahren, bevor die App darin deployt wird). Das führt zu langen, schwer lesbaren Routing-Dateien.
Aggrega begegnet dem nach dem Prinzip „Turtles All the Way Down“. Das Release-Schema hat keinen Block zum Installieren von Infrastruktur; die Cluster-Provisionierung wird mit Plattform-Aggregates modelliert.
Da ein AWS-EKS-Cluster, eine Istio-Control-Plane und eine AWS-VPC letztlich nur physische Cloud-Ressourcen sind, werden sie genau wie Anwendungskomponenten modelliert.
- Das Plattform-Aggregate: Das Infrastrukturteam schreibt ein gewöhnliches
Aggregate.yaml, dessen Komponentencore/aws-vpc,core/eks-clusterundcore/istio-basesind. - Das Plattform-Release: Das Team deployt dieses Aggregat. Der für diese Plattformkomponenten gebundene Renderer gibt die Artefakte aus, die zum Aufbau der Basisinfrastruktur nötig sind.
- Das Anwendungs-Release: Sobald der Anwendungsentwickler bereit ist, seinen KI-Agenten zu deployen, zielt das Ops-Team einfach mit einer Boundary in der eigenen
Release-Datei der Anwendung auf den neu erstellten Cluster.