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

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 das Release (CI/CD) inline unter parameters: oder über parameters: { $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: 2 in workers: 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-Map parameters:. Eine Schichtung über mehrere Dateien wird über extends:-Ketten des Release ausgedrückt.
  • values (die kognitive Absicht - im Besitz des Entwicklers)
    • Geltungsbereich: Einheitlich verwendet innerhalb von components und ihren features-Anhängen im Aggregate, 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).
  • uses (die strukturelle Topologie - deklarativer Zustand)
    • Geltungsbereich: Einheitlich verwendet innerhalb von components und ihren features-Anhängen im Aggregate, 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.
  • infra (die physische Realität - im Besitz von Ops)
    • Geltungsbereich: Einheitlich verwendet innerhalb der components einer Boundary und ihrer features-Anhänge im Release.
    • 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 ihre features-Anhänge enthalten kein Feld infra und lehnen infra zusammen mit additionalProperties: false bei der Schemavalidierung ab. Validiert durch die einheitliche schema:-Deklaration des Katalogs.
  • inject (der Bereitstellungsvertrag - imperativer Befehl)
    • Geltungsbereich: An einer Komponenteninstanz, innerhalb expliziter Zieldefinitionen in uses und an angehängten features verwendet, 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, arg oder 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 mit in: benennt und genau eines von from: oder value: trägt.
  • .context (die generische Metadaten-Pipe)
    • Geltungsbereich: Vom Compiler stillschweigend in die Templates der Ops-Recipe injiziert.
    • 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.

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 typisierten parameters:-Vertrag und interpoliert dann die aufgelösten Go-Template-Variablen, bevor die nachgelagerte Schemavalidierung von values: ausgeführt wird.
    • Empfohlene Verwendung: parameters sind 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 den infra-Block des Release und die Boundary-Overlays, sodass das Aggregate des 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 parameters globale Umgebungskonfigurationen durch den Stack tragen. Der Compiler akzeptiert alles, was die Schemavalidierung besteht; die obige Empfehlung ist ein Gesellschaftsvertrag, keine Compiler-Regel.
  • Fluss 2: Kognitive Anwendungsabsicht (values in Components): Definiert die intrinsische Anwendungslogik. Die schema:-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 (values in 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 seinem infra (Fluss 4).
  • Fluss 4: Dimensionierung der physischen Infrastruktur (infra): Unter vollständiger Umgehung des Entwicklers wird die physische infra-Dimensionierung explizit aus dem umgebungsspezifischen Release direkt 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 die infra-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 infra verhindert. 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 lokale infra-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 die values-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 Aggregate weglassen. 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 Feld port bereit. 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 der schema:-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 versa

Compiler-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, | quote und | 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 mit subsystems logische Metadaten (Teamzuständigkeit, Compliance-Labels) und übergreifende Features auf Dutzende von Komponenten gleichzeitig anwenden. Subsysteme wirken als rekursive Ordner auf der logischen bzw. Absichtsebene, geben annotations kaskadierend nach unten in den Bucket .context.annotations.aggregate weiter 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ür type, 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.
aggregate.yaml
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 parameters an es weitergeben. Um eine enge Kopplung zu vermeiden, stellen untergeordnete Aggregates einen exportedComponents:-Vertrag bereit, der einen stabilen öffentlichen Schnittstellennamen festlegt. Das übergeordnete Element erreicht die Komponenten des Moduls nur über diese Schnittstelle: Ein uses:-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.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type benennt 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 Muster spec.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.components ohne subsystems verfasst. Der Compiler faltet sie beim Laden in ein synthetisiertes default-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.components ohne boundaries verfasst. Der Compiler faltet sie in eine synthetisierte default-Boundary, deren Ausgabe flach ist — Artefakte landen direkt unter dist/ (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 und default nennt, ist eine gewöhnliche benannte Boundary und gibt ohne eigenes directory: wie jede andere nach dist/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 explizite boundaries ein. 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.

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 seinen values-Block, ohne Anführungszeichen, sodass der Wert als die Ganzzahl ankommt, als die er deklariert wurde.
    • Warum: Wenn das Aggregate env_workers als 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 umgebenden values:-Schemas. Dies erhält die Wiederverwendbarkeit des Aggregate: Ops liefert die Ganzzahl über die parameters: des Release, der Compiler validiert sie gegen die typisierte parameters:-Deklaration, setzt den aufgelösten Wert in das Dokument ein, und die schema:-Deklaration der Component validiert die resultierende Ganzzahl erfolgreich.
  • 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-type für Zugangsdaten benannt wird (einer mit dem Label feature.aggrega.ai/kind: secret) und die eigenen values dieses Anhangs die Abfrage an einen Secret-Store beschreiben. Dies ist eine Konvention, keine Prüfung des Compilers — der Compiler interpretiert nicht, was ein values-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.
  • Einschränkung 2: Fähigkeitsagnostische Components

    • Nicht unterstütztes Muster: Der Architekt schreibt aws_instance_type: string in die schema:-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.
  • Einschränkung 3: Bedingte Logik auf Metadaten

    • Nicht unterstütztes Muster: Ops schreibt {{ if eq .context.labels.gpu "true" }} in ein Recipe, um die Deployment-Strategie grundlegend zu ändern.
    • Warum: Der .context-Kanal umgeht die schema:-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.
  • Einschränkung 4: Das Release kann Entwicklerwerte nicht überschreiben

    • Nicht unterstütztes Muster: Ops versucht, die kognitive Logik eines Entwicklers vom Release aus zu überschreiben (z. B. workers: 4 in workers: 10 zu ändern).
    • Warum: Das Aggregate ist die einzige Quelle der Wahrheit für die Absicht des Entwicklers. Ist ein Wert im Aggregate fest codiert, ist er über alle Umgebungen hinweg unveränderlich. Muss sich ein Wert je Umgebung ändern, verwendet der Entwickler Parameter-Hoisting. Das Release-Schema setzt dies durch, indem es values-Blöcke verbietet und Ops darauf beschränkt, den parameters-Vertrag zu erfüllen und die physische infra zu definieren.
  • Einschränkung 5: Labels auf Instanzebene im Aggregate

    • Nicht unterstütztes Muster: Der Entwickler schreibt labels: {} an eine Komponenteninstanz innerhalb des Aggregate.
    • 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, infra und Feature-Überschreibungen je Komponente zu verschachteln, ohne die Urheberschaft von Labels in das Aggregate des Entwicklers zu mischen.

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-external gelabelt ist, muss die ID dieses Zielknotens ausdrücklich im Array parameters.approved_egress der 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 auf helm eine Kubernetes-NetworkPolicy pro Workload, den diese Komponente rendert, und erlaubt Egress nur zu ihren eigenen Pods, zu den Pods der Ziele ihrer uses-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 mit infra.control_plane_present: true bestä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; auf compose, 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-external gelabelt (löst die Egress-Guardrails der Policy aus). Realisiert durch einen Referenz-Workload (keine Rechenressourcen bereitgestellt; siehe §10).
  • Szenario B (interne Altdatenbank): Mit internal-trusted gelabelt (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-trusted gelabelt. 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Compilerausführung beim Rendering (die Übergabe)

  1. Der Compiler wertet das Recipe für legacy-oracle aus. Für ein Release, das legacy_oracle_ip: "10.0.4.55" liefert, ist sein primary_endpoint gleich oracle://10.0.4.55:1521/PROD_DB.
  2. Auf helm rendert der Referenz-Workload einen ExternalName-Service, legacy-oracle, mit externalName: 10.0.4.55 und Port 1521; auf compose rendert er nichts.
  3. Anschließend rendert der Compiler das Recipe für my-agent. Sein .context.uses-Kanal trägt die provides des Oracle-Knotens, und der Injektionsvertrag hat ORACLE_DSN bereits 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.

  1. Das Plattform-Aggregate: Das Infrastrukturteam schreibt ein gewöhnliches Aggregate.yaml, dessen Komponenten core/aws-vpc, core/eks-cluster und core/istio-base sind.
  2. 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.
  3. 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.