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

Aggregate

Die konzeptionelle Rolle der Aggregate-Entität (Domäne 1 — der deklarative Topologie-Bauplan des Entwicklers) ist in architecture/04-entity-taxonomy.md beschrieben. Die Kompositionsmuster (Subsysteme, verschachtelte Aggregationen, Zero-Port-Konvention, Parameter Hoisting) sind in architecture/06-data-taxonomy-and-composition.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche des Katalogs für das Aggregate — insbesondere das Erstellen wiederverwendbarer Aggregate-Module für die Verteilung über den Katalog.

Component-Bereich: das Standard-Subsystem

Ein Aggregate organisiert Komponenten in Subsysteme — benannte Gruppierungen für querschnittliche Belange (eine Datenschicht, eine Edge-Schicht), die ihre eigene Annotationskaskade mitbringen. Die meisten Aggregates haben eine einzige Gruppierung, die daher keinen Aufwand erfordert.

Einzelner Bereich (der Standard). Schreiben Sie Komponenten direkt unter spec.components: und lassen Sie den Block subsystems: weg:

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Der Compiler fasst diese in einem synthetisierten Subsystem default zusammen. Die Knotenidentität bleibt unverändert — api bleibt api, niemals default.api —, sodass ein so geschriebenes Aggregate mit der expliziten Form mit einem einzigen Subsystem austauschbar ist und seine Adressierung (in uses:-Zielen, in Diagnosen) den einfachen Pfad spec.components.<name> verwendet. Der synthetisierte Bereich wird in der exportierten IR wahrheitsgetreu erfasst (mit einer Markierung für synthetisierte Subsysteme), erscheint aber nie in den Pfaden, die ein Autor schreibt oder liest.

Mehrere Bereiche. Wenn Komponenten in unterschiedliche querschnittliche Gruppen fallen, deklarieren Sie benannte Subsysteme unter subsystems:. Jedes Subsystem trägt seine eigenen Komponenten und seine eigene Annotationskaskade und kann weitere Subsysteme verschachteln.

Gegenseitiger Ausschluss. spec.components: und spec.subsystems: schließen sich an der Wurzel des Aggregate gegenseitig aus — schreiben Sie das eine oder das andere, niemals beides. Ein Dokument, das beides deklariert, hält beim Laden mit einem Envelope-Fehler an. (Ein Subsystem, das ein Entwickler ausdrücklich default nennt, ist ein gewöhnliches deklariertes Subsystem und wird über seinen qualifizierten Pfad spec.subsystems.default.components.<name> adressiert — das Weglassen des synthetisierten Bereichs richtet sich nach der Herkunft, nicht nach dem Namen.)

Wiederverwendbare Aggregate-Module

Aggregates dienen sowohl als Wurzel-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 ist der Name des Moduls, ein Punkt und einer seiner exportierten Aliase, und der Compiler verdrahtet die Kante mit der internen Komponente, die der Alias nennt. Ein Ziel, das unter einem anderen Namen in ein Modul hineingreift — dem Namen der Komponente innerhalb des Moduls oder einem Pfad in ein darin verschachteltes Modul —, hält den Build an und nennt das Modul und die Aliase, die es exportiert; siehe A uses target names a module’s component the module does not export (Ein Ziel nennt eine Komponente eines Moduls, die das Modul nicht exportiert).

Warum eine explizite exportedComponents:-Liste. Die Autoren eines Moduls entscheiden, welche seiner Komponenten die öffentliche Schnittstelle bilden und welche Implementierungsdetail bleiben. Da ein übergeordnetes Element nur nennen kann, was die Liste veröffentlicht, lassen sich die Interna des Moduls umbauen — eine Komponente umbenannt, eine Komponente in zwei aufgeteilt, ein Worker durch einen verwalteten Dienst ersetzt —, ohne ein übergeordnetes Element zu brechen, solange jeder veröffentlichte Name noch auf eine Komponente zeigt. Die Liste kostet einen Eintrag pro veröffentlichter Komponente, und eine Komponente kann unter ihrem eigenen Namen veröffentlicht werden (store: store), wo dies der Name ist, den Importeure verwenden sollen. Dieselbe Regel gilt innerhalb einer Komposition: Ein Modul erreicht ein Modul, das es importiert, über dessen exportierte Aliase. Ein Release darf zwei Komponenten eines Moduls miteinander verdrahten, da diese Verbindung die Schnittstelle keines Moduls überquert.

Die Schnittstelle eines verschachtelten Moduls erneut exportieren. Ein exportedComponents:-Eintrag kann auf den exportierten Alias einer verschachtelten Unter-Aggregation zeigen statt auf eine direkt deklarierte Komponente — ein Modul, das einen Teil eines von ihm importierten Moduls unter seinem eigenen Schnittstellennamen und optional unter neuem Namen erneut veröffentlicht. Eine uses:-Kante, die einen solchen erneut exportierten Alias zum Ziel hat, wird transitiv über die Kette bis zum konkreten internen Knoten aufgelöst, sodass ein Modul tiefere Module in seine eigene öffentliche Schnittstelle einbindet, ohne deren interne Struktur offenzulegen, und ein Verbraucher nie wissen muss, wie tief das Ziel verschachtelt ist. Die Disziplin der stabilen Schnittstelle gilt auf jeder Stufe: Jedes Modul exportiert erneut nur, was es veröffentlichen will. Ein erneut exportiertes Ziel, das zu keinem internen Knoten aufgelöst wird, hält den Build ebenso deutlich an wie ein direktes ins Leere zeigendes Ziel, und eine Re-Export-Kette, die sich zu sich selbst schließt, wird abgelehnt, statt endlos verfolgt zu werden.

Die Deklarationen eines Moduls werden wie die des Aggregate geprüft. Das Dokument eines Moduls wird erst gelesen, wenn die Komposition gebaut wird, die es importiert, und seine Deklarationen werden ab diesem Punkt geprüft, in jeder Verschachtelungstiefe. Der eigene inject:-Block einer Modulkomponente wird an der spec.inject-Allowlist ihres Typs gemessen sowie an den Regeln, die verbieten, einen Zustellungsschlüssel zweimal zu beanspruchen oder einen Schlüssel zu lesen, den der Typ nicht veröffentlicht. Eine Anbindung, die an einem der eigenen Subsysteme des Moduls geschrieben ist, darf nur einen Socket nennen, den ihr Feature deklariert, und dasselbe gilt für eine Anbindung, die das Release an einer von einem Modul beigesteuerten Komponente schreibt.

Die Subsystem-Anbindungen eines Moduls erreichen seine Komponenten. Ein Feature, das ein Modul an einem seiner eigenen Subsysteme anbindet, wirkt kaskadierend auf jede Komponente, die das Modul unterhalb dieses Subsystems deklariert, verschachtelte Subsysteme eingeschlossen, genau wie eine Subsystem-Anbindung im Aggregate — und nur auf diese Komponenten, niemals auf die Komponente eines importierenden Aggregate unter einem gleichnamigen Subsystem. Es wird direkt nach den eigenen Anbindungen der Komponente ausgewertet, äußere Subsysteme vor inneren. Bei einem Feld, das beide schreiben, gewinnt die gleichnamige eigene Anbindung der Komponente, und die Felder, die sie weglässt, behalten die Werte des Subsystems. Jede Komponente, die es erreicht, prüft es gegen das appliesTo des Feature. Ein Befund zu den eigenen Deklarationen eines Moduls nennt das Modul und den Schlüssel in dessen Dokument — etwa .spec.subsystems.<subsystem>.features.<attachment> —, sodass die Änderung im Modul vorgenommen wird, wo die Deklaration steht, und nicht im Aggregate, das es importiert.

Ort im Katalog

Ein wiederverwendbares Aggregate-Modul liegt unter dem Art-Verzeichnis aggregate/ an dem Pfad, den sein metadata.name Segment für Segment vorgibt, mit einem Versionsverzeichnis als Blatt:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Ein Modulname kann ein führendes Segment {publisher} tragen, das den Anbieter oder Autor nennt — core für die Standardbibliothek, acme für ein Unternehmen —, und die veröffentlichten Module der Standardbibliothek sind so benannt: core/agenta liegt unter aggregate/core/agenta/1.0.0/aggregate.yaml. Ein Name aus einem einzigen Token liegt eine Ebene flacher, unter aggregate/{module-name}/{version}/aggregate.yaml. Beide Formen sind wohlgeformt; der Name ist das, was der Autor schreibt, und das Verzeichnis spiegelt ihn wider. Diese Spiegelung ist eine Katalogkonvention und nichts, was der Compiler prüft — ein Modul wird über den Namen gefunden, den es deklariert, nicht darüber, wo seine Datei liegt.

OCI-URI: hub.aggrega.ai/aggregate/{module-name}:{version}, in Kleinbuchstaben — ein Modul namens core/agenta wird also unter hub.aggrega.ai/aggregate/core/agenta:1.0.0 veröffentlicht und eines namens db-module unter hub.aggrega.ai/aggregate/db-module:1.0.0.

Das Modulmuster

Untergeordnetes Modul (aggregate/child-database-module/1.0.0/aggregate.yaml, veröffentlicht als hub.aggrega.ai/aggregate/child-database-module:1.0.0):

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"

Übergeordnetes Aggregate:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Modul-Labels

Wenn ein Aggregate als wiederverwendbares Modul im Katalog veröffentlicht wird, kann es metadata.labels in seinem YAML-Envelope tragen — zum Beispiel aggregate.aggrega.ai/tier: infrastructure oder aggregate.aggrega.ai/compliance: pci-dss. Diese Labels beschreiben die Identität des Moduls und werden auf dem Moduldokument wie veröffentlicht mitgeführt; noch liest sie kein Befehl. Die Katalogsuche indiziert keine Aggregates, und der Build-Graph führt weder die Labels eines Moduls noch seinen Katalognamen mit, sodass eine Governance-Policy die Komponenten eines Moduls nicht nach dem Modul auswählen kann, aus dem sie stammen.

Die entscheidende Unterscheidung. Aggregate-Labels beschreiben die Identität des wiederverwendbaren Moduls im Katalog. Sie werden nicht kaskadierend an untergeordnete Komponentenknoten weitergegeben. Komponenten-Labels stammen ausschließlich aus der Katalogentität Component in Domäne 2. Wenn ein Entwickler ein Modul mit dem Label aggregate.aggrega.ai/tier: infrastructure importiert, behalten die einzelnen Komponenten in diesem Modul nur ihre eigenen im Katalog definierten Labels (z. B. component.aggrega.ai/type: stateful-server). Das Aggregate-Label wird niemals in das labels-Dictionary des IR-Knotens injiziert.

Siehe architecture/06-data-taxonomy-and-composition.md §6 für die vollständige Erörterung zusammengesetzter Aggregates / des Modulmusters (einschließlich der Regel, dass Components keine Unterkomponenten haben) und für den querschnittlichen Gruppierungsmechanismus subsystems. Siehe vocabulary/data-pillars für die Authoring-Oberfläche des typisierten parameters-Vertrags.

Typisierte Parameterverträge

Der Block spec.parameters: des Aggregate deklariert den typisierten Vertrag für die Parameter, die das Release erfüllt. Jeder Parameter-Slot trägt einen deklarierten type, eine optionale description, einen optionalen default, optionale Einschränkungen des Wertebereichs und (bei objekttypisierten Slots) eine verschachtelte Struktur. Der Compiler validiert jeden vom Release gelieferten Wert während der Auflösung gegen den Vertrag, bevor die Parameterinterpolation läuft.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Die Anführungszeichen an jeder Referenz sind beabsichtigt: Sie entscheiden, mit welchem Typ der hochgezogene Wert ankommt. Siehe templates/parameters-context.md.

Vokabular der Parameter-Slots

Der typisierte Block parameters: akzeptiert das Vokabular der kompakten Form: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate und validateMessage (eine benutzerdefinierte Prüfung und die Meldung, die sie ausgibt), items (für Arrays), properties (für Objekte), valuesType (für Maps mit typisierten Werten) und required: true (Markierung pro Slot). Drei dieser Schlüsselwörter nehmen als Wert einen Vertrag statt einer einfachen Einstellung — items, valuesType und jeder Eintrag unter properties —, und an einem Parameter-Slot wird dieser verschachtelte Vertrag in derselben typisierten Form geschrieben wie der umgebende Slot: valuesType: { type: boolean }, nicht valuesType: boolean. Vor der Interpolation prüft der Compiler die zusammengeführte Parameter-Map direkt gegen diese Deklarationen: Ein Parameter, den kein Slot deklariert, wird abgelehnt; ein mit required: true markierter Slot, den weder das Release füllt noch ein default liefert, hält den Build an; und jeder gelieferte Wert wird gegen den deklarierten type seines Slots, die Zugehörigkeit zu seinem enum, die Grenzen minLength und maxLength, den regulären Ausdruck pattern und das format bei einem String-Slot sowie gegen die Grenzen min und max geprüft — den Wert eines numerischen Slots, die Länge eines String-Slots und die Anzahl der Elemente eines Array-Slots. Objekt- und Array-Slots werden rekursiv geprüft: Jeder Eintrag unter properties und jedes Element gegen items wird auf dieselbe Weise geprüft, ein valuesType-Vertrag regelt die Schlüssel, die properties nicht nennt, und ein verschachtelter Schlüssel, den keine Deklaration nennt, wird abgelehnt. Das vollständige Schlüsselwortvokabular, einschließlich der Stellen, an denen eine schema:-Säule diese Schlüsselwörter anders schreibt, finden Sie in vocabulary/compact-form-authoring.md.

Die folgenden Schlüsselwörter werden auch an der Deklaration selbst geprüft, bevor irgendein Release-Wert gelesen wird, sodass ein Slot, der nichts einschränken könnte, den Build auch dann anhält, wenn kein Release ihn liefert:

  • Längengrenzen sind null oder größer. Ein negatives minLength oder maxLength an der eigenen Deklaration eines Parameters wird vom Schema des Aggregate beim Laden des Aggregate abgelehnt, unter Nennung des Parameters und des Schlüssels. Innerhalb eines verschachtelten Vertrags — unter items, properties oder valuesType — wird eine Längengrenze so gelesen, wie sie geschrieben ist, und beim Laden des Aggregate nicht an dieser Untergrenze gemessen; schreiben Sie sie daher auch dort als null oder größer: Ein negatives minLength schränkt nichts ein, und ein negatives maxLength lehnt jeden Wert ab.
  • min und max müssen etwas begrenzen. An einem booleschen oder Objekt-Slot begrenzt das Paar nichts, daher wird ein dort geschriebenes min oder max beim Laden des Aggregate abgelehnt, unter Nennung des Parameters und des Schlüssels.
  • Ein Pattern muss kompilieren. Jedes pattern wird als regulärer Ausdruck kompiliert, wenn der Parametervertrag gelesen wird — am Slot selbst und innerhalb jedes verschachtelten Vertrags, in beliebiger Tiefe —, und eines, das nicht kompiliert, wird unter Nennung des Parameters, des Patterns und des Grundes abgelehnt. Der Vertrag wird bei jedem Build, jedem Pull und jeder Release-Validierung gelesen, die das Aggregate erreicht, ob es das eigene Aggregate des Release ist oder ein Modul, das dieses Aggregate importiert. Die Wertprüfung gleicht dann jeden gelieferten Wert mit genau diesem kompilierten Ausdruck ab.
  • Ein Format muss eines sein, das der Compiler prüft. format nennt eines von email, uri, hostname, ipv4, ipv6, uuid, date-time und date, so geschrieben, wie JSON Schema sie schreibt. Jeder andere Name — ein Tippfehler wie emial oder ein Name, den JSON Schema nicht definiert, wie password — wird beim Laden des Aggregate abgelehnt, unter Nennung des Parameters und Auflistung der unterstützten Namen: am Slot selbst durch das Schema des Aggregate und innerhalb eines verschachtelten Vertrags, in beliebiger Tiefe, wenn der Parametervertrag gelesen wird. Ein gelieferter String, der das genannte Format nicht hat, wird dann unter Nennung des Parameters, des Werts und des Formats abgelehnt. Was jeder Name prüft, steht in vocabulary/compact-form-authoring.md.

Objekttypisierte und arraytypisierte Parameter

Parameter-Slots akzeptieren jeden Typ, den die kompakte Form unterstützt, einschließlich verschachtelter Objekte und Arrays typisierter Elemente:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

Das Release erfüllt objekttypisierte Parameter mit strukturiertem YAML; der Compiler validiert die Struktur vor der Interpolation gegen das deklarierte Schema. Templates, die auf die Felder des Objekts verweisen, verwenden die Standard-Template-Syntax von Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} usw.

Validierung des Parametervertrags

Zuerst wird der Vertrag selbst geprüft, wenn er gelesen wird — die Prüfungen der Längengrenzen und Patterns unter „Vokabular der Parameter-Slots“ oben. Anschließend führt der Compiler während der Parameterverarbeitung drei Teilschritte aus:

  1. Default-Befüllung — Slots mit definiertem default: und ohne vom Release gelieferten Wert erhalten ihren Default. Parameter mit verschachtelten Objekten haben eine Authoring-Semantik mit drei Fällen für ausgelassene, explizit leere und teilweise geschriebene übergeordnete Slots: Wird der übergeordnete Slot ausgelassen, werden die Defaults der untergeordneten Slots gefüllt; wird er als {} geschrieben, bleibt das explizite Leere erhalten (die Defaults der untergeordneten Slots werden unterdrückt); und wird er als nicht leere Map geschrieben, werden nur die untergeordneten Slots gefüllt, die das Release nicht geliefert hat. YAML-Beispiele und die Entscheidungshilfe „wann welche Form verwenden“ finden Sie in templates/parameters-context.md.
  2. Vertragsvalidierung — jeder Wert in der zusammengeführten Map, ob ihn das Release geliefert oder ein default: gefüllt hat, wird gegen die deklarierten Einschränkungen type / enum / min / max / pattern / verschachtelte Struktur validiert. Validierungsfehler halten den Build mit einem klaren Fehler an, der den betroffenen Slot, den gelieferten Wert und die verletzte Einschränkung nennt. Fehlende Pflichtparameter ohne default: erzeugen einen ähnlichen Halt mit dem Slot-Namen.
  3. Interpolation — der Compiler wertet den gesamten Text des Aggregate als Template aus, bevor er ihn als YAML liest, und ersetzt jede Referenz {{ .parameters.<slot> }} — typischerweise innerhalb von values:-Strings von Komponenten / Features / Sub-Aggregaten — durch den aufgelösten Wert; jedes andere {{ im Text wird ebenfalls als Template-Syntax gelesen, sodass ein Wert mit eigenen doppelten geschweiften Klammern — etwa die exportierte Definition einer Flow-Plattform — jedes {{ als {{"{{"}} schreibt, wie Text mit eigenen doppelten geschweiften Klammern beschreibt. Nach diesem Durchlauf verarbeiten Wert-Template-Oberflächen bereits interpolierte Literale und erhalten .parameters nicht in ihrem Template-Kontext.

Die zusammengeführte Parameter-Map bleibt während des Renderings erhalten, um die Auswertung von Pfad-Templates zu unterstützen. Vom Operator geschriebene directory:- und subDirectory:-Templates an Release-Grenzen lesen .parameters.<slot> zur Renderzeit direkt, gegen eine geschlossene Allowlist; die Pfadausgabe benötigt Regions- / Umgebungsvokabular für ein umgebungsspezifisches Artefakt-Layout, und die asymmetrische Freigabe hält dieses Anliegen des Operators innerhalb der Operator-Oberfläche, ohne den Umweg über die values des Aggregate. Die Map bleibt lesbar, bis jede Renderphase abgeschlossen ist, und ist nur von der Kompilierung aus erreichbar, für die sie aufgelöst wurde; Recipes, die vom Entwickler geschriebene values: verarbeiten, sehen die Strings nach der Interpolation, während Pfad-Templates während des Renderings lebendige .parameters-Daten sehen. Die Verfügbarkeitsmatrix der Pfad-Templates finden Sie in templates/expansion-matrix.md Zeile 3, die Allowlist der Pfad-Template-Variablen in path-template-variables.md.

Die umfassendere Checkliste zum Parameter-Hoisting (Deklaration im Aggregate → Referenz in den values → Erfüllung im Release → Verarbeitung im Recipe) und die säulenübergreifende Mechanik finden Sie in vocabulary/data-pillars.md §„Parameter“ und §„Die Checkliste zum Parameter-Hoisting“. Die während der Interpolation bereitgestellten Felder des Template-Kontexts und die Ausnahme für Pfad-Templates finden Sie in templates/parameters-context.md.

Eine uses-Kante ist ein Aufruf, den das Aggregate deklariert

Eine uses-Kante ist die Aussage des Aggregate, dass eine Komponente eine andere aufruft. Der Compiler leitet die Werte, die das Ziel veröffentlicht, an den Aufrufer weiter und schränkt nichts ein: Für sich genommen lässt eine Kante weder den Aufrufer zu noch weist sie jemand anderen ab, und eine Workload-Instanz, die die Adresse des Ziels ohne Kante erreicht, erreicht sie trotzdem.

Einzuschränken, wer eine Komponente aufrufen darf und was sie aufrufen darf, ist die Entscheidung des Operators, die pro Umgebung im Release getroffen wird. Wo ein Release das Feature core/caller-allowlist aus dem Katalog der Standardbibliothek an eine Komponente anhängt, schreibt der Build eine Network Policy, die genau die Komponenten zulässt, deren uses-Kanten auf sie zeigen, die eigenen Pods dieser Komponente und die Quellen, die der Anhang nennt. Das ausgehende Gegenstück, core/egress-allowlist, lässt die Komponente, an die es angehängt ist, nur die Komponenten erreichen, auf die ihre eigenen uses-Kanten zeigen, ihre eigenen Pods, das DNS des Clusters und die Adressbereiche, die das Release auflistet. Ein Aufruf, den das Aggregate nicht als Kante deklariert, kann dann vom Cluster an beiden Enden abgewiesen werden, überall dort, wo sein Netzwerk-Plugin Network Policies durchsetzt. Schreiben Sie daher eine Kante für jeden Aufruf, den Ihre Komponenten tätigen, auch für einen, der keinen Wert injiziert: Eine fehlende Kante ist ein Aufruf, den eine abgeschirmte Komponente abweisen kann. model-server-caller-allowlist zeigt einen Model-Server, der nur über das vorgelagerte Gateway erreichbar ist.

Die eigenen Anhänge einer Verbindung: features an einem uses-Eintrag

Eine Verbindung, die eine Komponente in ihrer ausführlichen uses:-Form zieht, ist ein eigener Eintrag und kann neben target, inject und values Anhänge tragen, unter features:. Jeder ist durch einen Slot, den der Socket deklariert, geschlüsselt: Die konsumierende Component listet im featuresSchema des Sockets die Slots auf, die jede durch diesen Socket verdrahtete Verbindung füllen darf (siehe Topologie-Sockets). So hält eine Komponente für jede Komponente, die sie erreicht, eine andere Anmeldeinformation — ein Gateway, das zwei Modelle mit zwei Schlüsseln aufruft, oder ein Agent, der einem Modell einen eigenen Schlüssel vorlegt.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Ein Anhang an einer Verbindung trägt type (erforderlich), eine optionale description und values für das Feature. Er trägt weder uses noch inject: Ein Anhang an einer Verbindung wird nicht verschachtelt, und wie sein Material den Konsumenten erreicht, entscheidet das Recipe der konsumierenden Komponente und nicht ein inject-Block. Ein Dokument, das einen der beiden Schlüssel schreibt, wird beim Laden abgelehnt, unter Nennung des Schlüssels.

Nur die Slots, die der Socket deklariert. Ein Anhang unter einem Namen, den das featuresSchema des Sockets nicht auflistet, hält den Build beim Laden an, unter Nennung der Verbindung, des Sockets, der Komponente und der Slots, die der Socket deklariert — und, wo der Name eine Bearbeitung von einem davon entfernt ist, dieses Slots als wahrscheinlich gemeinte Schreibweise. Ein gefüllter Slot wird dann an jeder Verbindung an der eigenen Deklaration des Slots gemessen: Ein selector, den die Labels des Features nicht erfüllen, hält an diesem Eintrag an, und ein required-Slot, der an irgendeiner Verbindung leer bleibt, hält unter Nennung dieser Verbindung an. Ein Socket, der keine Slots deklariert, lässt an seinen Verbindungen keinen Anhang zu, und ebenso wenig ein Ad-hoc-Socket — einer, den das Aggregate verdrahtet, ohne dass die Component ihn deklariert —, da er überhaupt keine Slots deklariert. Für eine Komponente, die ein Untermodul beisteuert, gilt dieselbe Regel, und der Befund verweist in das eigene Dokument des Untermoduls. Siehe A connection carries an attachment under a name its socket declares no slot for (Eine Verbindung trägt einen Anhang unter einem Namen, für den ihr Socket keinen Slot deklariert).

Eine Verbindung, die ein Feature zieht, trägt keine. Der eigene uses:-Block eines angehängten Features — an einer Komponente oder an einem Subsystem — wird in derselben Form geschrieben, lehnt features: aber beim Laden des Dokuments ab. Eine Anmeldeinformation, die eine solche Verbindung benötigt, füllt einen Slot, den das Feature in seinem eigenen featuresSchema deklariert, angehängt neben dem Feature; siehe Die eigene Anmeldeinformation eines Features.

Der Name, den der Anhang erhält. Jeder Verbindungsanhang wird zu einem Anhang der konsumierenden Komponente, benannt <alias>.<slot> — der Alias, unter dem die Verbindung geschrieben ist, ein Punkt und der Slot: oben gpt.credential. Der Punkt ist das Trennzeichen, das für vom Compiler zusammengesetzte Namen reserviert ist und das kein Alias, Slot oder Anhangsname in einem Aggregate enthalten darf, sodass der zusammengesetzte Name nie einem Namen entspricht, der im eigenen features:-Block der Komponente geschrieben ist; ein Release, das ihn an einer Komponente oder einer Grenze schreibt, wird abgelehnt (siehe Konfiguration von Verbindungen pro Kante). Es ist der Name, unter dem die Instanzebene des Manifest den Anhang schlüsselt (siehe Flache URI-Zuordnung), der Name, unter dem Diagnosen und der IR-Graph ihn melden, und der Wert, den das FeatureRecipe des Anhangs als .attachment_name liest (siehe Aus dem Anhang einer Verbindung abgeleitete Namen).

Von dort aus wird er wie jeder Anhang aufgelöst: Das Manifest bindet seinen Feature-Typ an ein FeatureRecipe, seine values werden gegen das Schema des Features validiert — ein Fehler wird am Verbindungseintrag gemeldet, der sie geschrieben hat —, und sein FeatureRecipe rendert gegen die eigenen values und infra des Anhangs. Zwei Dinge unterscheiden ihn von den eigenen Anhängen der Komponente:

  • Er steht nicht in .features des konsumierenden Recipe. Diese Säule trägt nur die Anhänge, die im eigenen Block der Komponente geschrieben sind, sodass einem Recipe, das .features nach seinen eigenen Anhängen nach Typ durchsucht, nie die Anmeldeinformation einer Verbindung übergeben wird. Ein Recipe liest den Anhang einer Verbindung aus der Verbindung selbst, unter .context.uses.<alias>.features.<slot>, in der Form, die .features trägt — einschließlich seiner aufgelösten provides (siehe Die Anhänge einer Verbindung).
  • Er landet nur beim Konsumenten. Die gerenderte Ausgabe eines Ziels ist dieselbe, was auch immer die Verbindungen tragen, die es erreichen.

Die Kopie des geschriebenen Blocks im Graphen. Der IR-Graph bewahrt den uses:-Block jeder Komponente so, wie er geschrieben wurde, und dort behält ein Verbindungsanhang seinen type und seine description und keine seiner values. Die Werte erscheinen einmal, an dem Anhang, den der Konsument trägt, wobei ein Wert, den das Feature als sensibel deklariert, zurückgehalten wird.

Ein Release kann einen hier deklarierten Anhang mit infra dimensionieren oder an einer Verbindung, die es erreicht, einen eigenen anhängen — siehe Konfiguration von Verbindungen pro Kante.

Eine Komponente oder ein Modul abschalten: active:

Eine Komponenteninstanz und ein Sub-Aggregat-Modul akzeptieren jeweils einen Schalter active:, der entscheidet, ob diese Entität überhaupt Teil der kompilierten Topologie ist. Lassen Sie ihn weg, ist die Entität vorhanden; das ist der Default und der gewöhnliche Fall.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Schreiben Sie direkt einen booleschen Wert oder ein Template über .parameters, das zu einem solchen aufgelöst wird. Die Template-Form ist der Grund, warum es den Schalter gibt: Sie lässt ein Release die Anwesenheit einer Entität entscheiden, indem es einen Parameter erfüllt, sodass ein einziges Aggregate Umgebungen abdeckt, die sich darin unterscheiden, welche Teile sie bereitstellen — ohne dass das Release etwas deklariert, was das Aggregate nicht deklariert hat.

Was ein falscher Schalter entfernt. Die Entität wird entfernt, bevor der Graph gebaut wird, und das Entfernen kaskadiert: Eine Komponente nimmt ihre eigenen uses:-Kanten und ihre angehängten Features mit, und ein Modul nimmt alles mit, was es beigesteuert hat — seine Komponenten, deren Kanten, deren Anhänge. Nichts, was die entfernte Entität mitgebracht hat, wird gerendert. Was das Entfernen nicht erreicht, ist ein Verweis auf sie von einer Stelle, die erhalten geblieben ist; davon handelt der nächste Absatz.

Eine verbleibende Komponente, die noch auf eine entfernte zeigt, hält den Build an. Wenn api eine uses:-Kante auf redis deklariert und redis abgeschaltet ist, stoppt der Build, statt die Kante verschwinden zu lassen, was die injizierten Werte von api zur Deployment-Zeit stillschweigend leer ließe. Entscheiden Sie, welche der beiden in diese Umgebung gehört: Schalten Sie das Ziel wieder ein, machen Sie den Konsumenten vom selben Parameter abhängig, sodass das Paar gemeinsam wegfällt, oder entfernen Sie die Kante aus dem uses:-Block des Konsumenten.

Ein geschriebener Schalter muss zu einem booleschen Wert aufgelöst werden, und ein leerer Wert ist keiner. Der Schalter wird nach der Auflösung seines Templates strikt gelesen, und ein Literal, das sich nicht als boolescher Wert parsen lässt, stoppt den Build, statt auf irgendetwas zurückzufallen. Der Fall, auf den zu achten ist, ist ein Schalter, der einen Parameter ohne Wert liest: Er wird zu nichts aufgelöst, und nichts als „vorhanden“ zu lesen, würde genau die Entität bereitstellen, die Sie von diesem Parameter abhängig gemacht haben. Daher ist active: ohne etwas dahinter zu schreiben nicht dasselbe, wie den Schlüssel wegzulassen — nur ein Schalter, den niemand geschrieben hat, gilt standardmäßig als vorhanden. Geben Sie dem Parameter ein default: in spec.parameters, damit jede Umgebung eine Antwort hat, oder erfüllen Sie ihn im Release. Um eine Entität bedingungslos vorhanden zu machen, entfernen Sie den Schlüssel active:, statt ihn zu leeren. Der Halt ist unter „An active: toggle does not resolve to true or false (Ein Schalter wird nicht zu true oder false aufgelöst)“ in der Referenz der Haltebedingungen beschrieben.

Eine abgeschaltete Komponente bleibt von einem Release aus benennbar. Ein Release kann sie weiterhin in einer Grenze nennen, und das ist beabsichtigt: Eine Komponente abzuschalten ist ein Authoring-Akt, und vom Release, das sie konfiguriert, wird nicht erwartet, dass es in derselben Bearbeitung umgeschrieben wird.

Annotationen an Subsystemen und Komponenten

Subsysteme und Komponenteninstanzen tragen beide ein Feld annotations:. Vom Entwickler verfasste Annotationen auf der Oberfläche des Aggregate steuern die Annotationskaskade auf der Aggregate-Seite — eine Subsystem-Annotation wird an jedes verschachtelte Subsystem und jede enthaltene Komponente weitergegeben, wobei näher liegende Ebenen auf Ebene einzelner Schlüssel überschreiben. Die Map mappings.features.annotations des Manifest deklariert die Bindings, die Annotationsschlüssel zur Build-Zeit in synthetische Feature-Anbindungen übersetzen. Die Invariante „Aggregate als Authoring-Oberfläche“ beschränkt diese Annotationen auf das Routing über die maps.values-Pfade des Bindings; ein Binding, das nur maps.infra-Pfade deklariert, greift von der Release-Seite aus, nicht von der Aggregate-Seite.

Formen der Werte

Jeder Annotationsschlüssel nimmt eine von vier Formen an und unterscheidet „Ich schweige“ von „Ich deklariere einen Wert“ — einen Skalar oder ein strukturiertes Objekt — und von „Ich steige aus“:

  • Fehlender Schlüssel — der Geltungsbereich deklariert keinen Wert für diese Annotation. Verschachtelte Subsysteme und enthaltene Komponenten erben jedes Binding aus einem übergeordneten Geltungsbereich.
  • Ein skalarer String — ein einzelner Wert. Das Binding des Manifest muss insgesamt genau einen Pfad deklarieren; der Skalar wird zu diesem Pfad geleitet.
  • Ein strukturiertes Objekt — eine Map von Unterschlüssel zu Unterwert. Jeder Unterschlüssel des Objekts wird über die maps des Manifest-Bindings zum entsprechenden Feld des Feature-Schemas in der deklarierten Säule geleitet.
  • Explizites YAML-null — der Geltungsbereich entfernt jedes geerbte Binding für diesen Schlüssel aus seinem Teilbaum. Geschwisterkomponenten und Geschwister-Subsysteme behalten ihre Vererbung; nur der aussteigende Geltungsbereich verliert das Binding.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Strukturierte Werte für Features mit mehreren Feldern

Ein Feature mit mehreren konfigurierbaren Feldern legt einen strukturierten Annotationswert nahe: ein Annotationsschlüssel, der in einer einzigen Deklaration Werte für mehrere Felder des Feature-Schemas trägt. Die Aggregate-Seite löst nur die Unterschlüssel aus, deren Säule in der Binding-Map values ist; Unterschlüssel, die zu infra geleitet werden, gehören in Annotationen auf der Release-Seite.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Strukturierte Werte kaskadieren mit einem tiefen Merge pro Unterschlüssel: Unterschlüssel näher liegender Ebenen überschreiben die der übergeordneten Ebene; ein explizites null an einem Unterschlüssel unterdrückt den geerbten Unterschlüssel für diesen Geltungsbereich, während Geschwister-Unterschlüssel bestehen bleiben. Die vollständige Darstellung strukturierter Werte — seitenübergreifende Komposition mit infra-Unterschlüsseln der Release-Seite, Typvalidierung pro Unterschlüssel, die gelockerte Standarddisziplin für Schemafelder ohne deklarierten type — finden Sie unter providers/well-known-annotations.md §„Strukturierte Annotationswerte“.

Unabhängigkeit pro Schlüssel

Jeder Annotationsschlüssel erbt, überschreibt und steigt unabhängig aus. Eine Komponente, die annotations.feature.myco/db-pool: null deklariert, steigt nur aus diesem Schlüssel aus; andere vom umschließenden Subsystem geerbte Schlüssel werden weiterhin an diese Komponente weitergegeben. Geschwisterkomponenten im selben Subsystem behalten ihre eigenen Annotations-Maps unabhängig voneinander — der Ausstieg einer Komponente wirkt sich nicht auf ihre Geschwister aus.

Annotationen von Komponenten der obersten Ebene

Komponenten der obersten Ebene (direkt unter spec.components statt innerhalb eines Subsystems deklariert) tragen keine geerbte Kaskade. Ihr Feld annotations: deklariert Werte direkt im Geltungsbereich der Komponente; die Expansion synthetisiert Feature-Anbindungen aus jeder deklarierten Annotation, für die das Manifest ein passendes Binding enthält.

Die Kaskadenregel der Aggregate-Seite angewendet auf Bindings, die Aufteilung nach Seite und Säule sowie ein durchgehendes Beispiel, das zeigt, wie die Bindings Annotationen in synthetische Feature-Anbindungen übersetzen, finden Sie unter providers/well-known-annotations.md §„Annotationskaskade auf der Aggregate-Seite“.

YAML-Anker-Muster (Block defs:)

Das Aggregate-Schema akzeptiert einen optionalen Block defs: auf der Wurzelebene — eine Liste von YAML-Strings, die ausschließlich als Träger für standardmäßige YAML-Anker (&anchor) und Referenzen (*anchor) dient. Der Inhalt des Blocks wird vom Compiler nie gelesen; er existiert, damit Autoren Ankerdefinitionen an einer Stelle deklarieren und im restlichen Aggregate darauf verweisen können, sodass wiederholte Werte DRY bleiben, ohne das flache O(1)-Dictionary zu verlieren, über das der Compiler iteriert. Der Mechanismus entspricht dem gleichwertigen Block defs: der Entität Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Anker werden beim YAML-Parsing aufgelöst, sodass *default_log_level bereits der String "info" ist, wenn der Compiler den Werteblock liest. Der Block defs: ist der konventionelle Ort für die Ankerdefinitionen; YAML erlaubt es, Anker überall zu deklarieren, doch sie an einer Stelle zu bündeln hält das restliche Aggregate lesbar. Der Block ist optional — Aggregates, die keine Anker benötigen, lassen ihn ganz weg.