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

Release

Die konzeptionelle Rolle der Release-Entität (Domäne 4 — der Bereitstellungs-Router, der ein Aggregate an ein Manifest bindet und Komponenten auf physische Grenzen abbildet) ist in architecture/04-entity-taxonomy.md beschrieben. Der Mechanismus der zeitlichen Sequenzierung (syncWave pro Grenze), das Dynamic Addressing Polyfill und das Muster Parameter Hoisting sind in architecture/12-day-two-lifecycles.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche des Release.

Die Rolle des Release

Das Release bindet ein aggregate an ein manifest und bildet Komponenten auf physische Bereitstellungsgrenzen ab (z. B. aws-eks-production). Es ist der einzige Einstiegspunkt für die Kompilierung: aggrega build --release release.yaml.

Das Release erfüllt den abstrakten Aggregat-Vertrag, indem es physische Gegebenheiten ausschließlich in den Block parameters einspeist, und speist die physische Dimensionierung (etwa CPUs oder Ports) über den parallelen Namespace infra ein.

Jedes Release deklariert ein Feld manifest:, das sein Manifest benennt (es sei denn, das Release verwendet extends:, das den Manifest-Zeiger des übergeordneten Release erbt). Die CLI aggrega build liest dieses Feld direkt; es gibt kein CLI-Flag --manifest, sodass die Abhängigkeitsspezifikation zusammen mit dem Release selbst in Git committet bleibt und die Bereitstellungshistorie über die eigene Git-Historie des Release nachvollziehbar wird.

Die Felder aggregate: und manifest: werden über eine Identität oder über eine Datei mit relativem Pfad aufgelöst, auf dieselbe Weise, wie der Rest der Sprache Verweise auflöst — nie als Dateinamensstamm relativ zum Release. Ein Wert ./ oder ../ ist eine explizite lokale Datei, die direkt relativ zum Release gelesen wird. Ein bloßes Token ist eine Identität — der metadata.name der referenzierten Entität. Eine manifest:-Identität wird aufgelöst, indem das eigene Verzeichnis des Release durchsucht wird (ein Manifest ist Betreiberkonfiguration auf der Bereitstellungsseite und hat daher keine Katalog- oder Registry-Ebene). Eine aggregate:-Identität wird über die vollständige Kaskade aufgelöst — das Verzeichnis des Release, dann der Katalog, dann die Registry —, sodass ein Release ein veröffentlichtes Aggregate über seine Identität benennen kann und dasselbe veröffentlichte Modul aufgelöst wird, ob es nun das spec.aggregate der obersten Ebene eines Release ist oder ein Sub-Aggregat innerhalb eines anderen Aggregate. Dieses Identitäts-oder-Pfad-Modell ermöglicht es, dass ein gemeinsam genutztes Aggregate vielen Release-Varianten zugrunde liegt, ohne den Verweis an einen Dateinamen zu koppeln, und dass ein veröffentlichtes Aggregate direkt über seinen Namen bereitgestellt wird.

Ein Pfad bleibt innerhalb des Workspace. Ein Wert ./ oder ../ benennt eine Datei, die der Workspace enthält, und ebenso jeder andere Pfad, den ein Release schreibt — sein extends: und ein $import: der Parameter, siehe unten. Ein Pfad, der so, wie er geschrieben ist, aus dem Workspace herausführt oder den ein symbolischer Link auf dem Weg aus ihm hinausführt, wird abgelehnt, bevor irgendetwas aus der Datei gelesen wird, die er benennt. Um ein Aggregate bereitzustellen, das außerhalb des Workspace liegt, benennen Sie es über seine Identität und führen Sie das Verzeichnis, das es enthält, in der Workspace-Konfiguration als Katalogverzeichnis auf; ein Manifest, ein Release, das ein extends: nennt, und eine Parameterdatei werden neben dem Release gelesen und nie über ihren Namen gesucht, daher werden sie innerhalb des Workspace aufbewahrt. Ein Release, das Sie auf der Befehlszeile nennen oder das die Workspace-Konfiguration nennt und das außerhalb des Workspace liegt, ist eine eigene Wurzel: Jeder Pfad, den es schreibt — und jeder Pfad, den ein Release schreibt, zu dem seine extends:-Kette führt —, muss zu einer Datei innerhalb des Verzeichnisses führen, das dieses Release enthält, und ein Pfad, der aus diesem Verzeichnis herausführt oder den ein Link aus ihm hinausführt, wird ebenso abgelehnt. Bewahren Sie das, was ein solches Release nennt, neben ihm auf, oder bauen Sie es in dem Workspace, der beide enthält. Siehe errors/fatal-halts.md §„A reference to another file leads out of the directory it must stay inside (Ein Verweis auf eine andere Datei führt aus dem Verzeichnis hinaus, innerhalb dessen er bleiben muss)“.

Das Release bestimmt das Ziel für kompilierte Artefakte; die Zuteilung an die Provider gehört zu dem Manifest, auf das das Release zeigt (siehe Manifest vs. Release: Trennung der Zuständigkeiten für die Rollenaufteilung).

Umgebungsmetadaten

Jeder Metadatenblock eines Release akzeptiert ein Feld environment: — einen frei formulierten String, der die Umgebung identifiziert, in die das Release bereitgestellt wird (typische Werte: production, staging, dev). Das Feld ist informativ: Es trägt keine Aufzählung, kein Muster auf Schemaebene und keine entitätsübergreifende Validierung über type: string hinaus. Der Compiler gibt seinen Wert als Label aggrega.ai/environment auf jedem Kubernetes-Manifest aus, das der helm-Provider rendert, zusammen mit den übrigen Provenienz-Labels von Aggrega — unverändert, wenn er ein gültiger Kubernetes-Labelwert ist, und andernfalls in einen solchen umgeschrieben, wobei der exakte Wert als Annotation aggrega.ai/environment mitgeführt wird (so erhält eu/prod das Label eu-prod); der helm-chart-Provider fügt dieselben Labels jedem über $import: geladenen Artefakt hinzu, das er in einem Sub-Chart platziert, während die eigenen Templates des Sub-Charts das tragen, was ihr Autor geschrieben hat. Der compose-Provider trägt denselben Wert als Label aggrega.ai/environment auf jedem Service, den er ausgibt.

Fünf praktische Muster bestimmen das Schreiben von environment::

  1. Kostenzuordnung mit OTel/FinOps. Cloud-Kosten-Dashboards (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtern Kubernetes-Pods per Tag nach Umgebung. Das Label aggrega.ai/environment: production fließt über die Label-Injektion des Helm-Providers in die Pod-Labels ein; Kostenberichte gruppieren die Ausgaben nach aggrega.ai/environment ohne manuelles Tagging pro Ressource.

  2. Filtern von OTel-Traces und -Logs. Observability-Dashboards (Datadog, New Relic, Honeycomb, Grafana Tempo) filtern Telemetrie nach dem Umgebungslabel. aggrega.ai/environment: staging ermöglicht es Betreibern, Log-Abfragen und Trace-Suchen auf Staging einzugrenzen, ohne nach Namespace-Konventionen oder Chart-Namen zu filtern — ein einziges kanonisches Label über die gesamte gerenderte Oberfläche.

  3. Ausrichtung von Kubernetes-Operatoren. GitOps-Controller (ArgoCD, Flux) und Policy-Operatoren (Kyverno, OPA Gatekeeper) filtern Ressourcen manchmal nach dem Umgebungslabel, um umgebungsspezifische Richtlinien umzusetzen (zum Beispiel „Ressourcen nur für die Produktion erfordern ein approved-image-source-Label“). Das Label aggrega.ai/environment bietet einen stabilen Selektor, der sich von Namespace-Konventionen oder Benennungsmustern unterscheidet.

  4. Unterscheidung der Produktion über mehrere Regionen. Ein Team, das ein Release production-us-east neben einem Release production-eu-west betreibt — beide mit metadata.environment: production —, erhält in allen Regionen dasselbe Label aggrega.ai/environment: production. In Kombination mit einem separaten Regionslabel ermöglicht dies eine regionsübergreifende Kostenzusammenfassung („gesamte Produktionsausgaben“) und einen Drilldown pro Region.

  5. Eingrenzung der Compliance. Die Erhebung von Nachweisen für SOC 2, PCI und HIPAA wird nach Umgebung eingegrenzt (Audit nur für die Produktion usw.). Das Label aggrega.ai/environment wird von Werkzeugen zur Sammlung von Compliance-Nachweisen (Vanta, Drata) genutzt, um Ressourcen nach Audit-Umfang zu filtern.

Das Schema verlangt environment: in jedem Release; der Wert ist informativ, und der Compiler liest ihn nur, um das Label aggrega.ai/environment zu schreiben.

Einschränkungen auf Schemaebene

Zwei strukturelle Garantien schützen das Aggregate als Single Source of Truth:

  • values: ist verboten. Um das Aggregate als Single Source of Truth zu schützen, verbietet das Schema des Release mechanisch einen values:-Block — der Operator kann aus einem Release heraus für keine Component und kein Feature values deklarieren. Das Verbot erstreckt sich auf uses-Kanten: Ein uses-Eintrag pro Kante in einem Release trägt infra und die Anbindungen, die er auf der Verbindung schreibt, und auch diese tragen infra — niemals values (entwicklerseitige Werte pro Kante und die Werte einer Anbindung auf einer Verbindung bleiben im Aggregate). Umgebungsspezifische Variationen der entwicklerseitigen Werte laufen über Parameter Hoisting: Der Entwickler stellt im Aggregate ein typisiertes Feld parameters.* bereit, das values-Template der Component referenziert es, und das Release erfüllt den Parameter für seine Umgebung. Das explizit formulierte Verbot auf Schemaebene finden Sie unter architecture/06-data-taxonomy-and-composition.md §8 Einschränkung 4. Die uses-Kantenoberfläche des Release — was es konfigurieren und verdrahten darf — ist weiter unten unter Verbindungskonfiguration pro Kante dokumentiert.
  • extends + aggregate: wird abgelehnt. Um nicht nachvollziehbare, „das Aggregate verändernde“ Releases zu verhindern, wird die Deklaration eines aggregate-Zeigers vom Schema des Release abgelehnt, wenn ein Release extends verwendet. Das abgeleitete Release muss genau derselben Entwicklerabsicht entsprechen wie sein übergeordnetes. Das manifest wird hingegen optional und ermöglicht so „späte Bindung“ — der Operator kann die gesamte physische Topologie erben, aber das Manifest gezielt austauschen.

Der parameters:-Block

Ein Release erfüllt den typisierten Parametervertrag, den das Aggregate deklariert. spec.parameters: ist die Autorenoberfläche — eine YAML-Map, deren Schlüssel den parameters.*-Deklarationen des Aggregate entsprechen und deren Werte die umgebungsspezifische Erfüllung liefern.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Jeder Wert durchläuft auf der Ebene des Parametervertrags die vom Aggregate deklarierte Schemaprüfung, und der Build bricht ab, wenn ein Release einen erforderlichen Parameter auslässt (E0165, parameter-missing) oder einen Wert liefert, den der Vertrag seines Slots ablehnt (E0164, parameter-contract-violation). Parameter, die mit einem default: deklariert sind, erhalten den Standardwert, wenn das Release den Slot auslässt; der typisierte Vertrag ist das einzige Autorenvokabular.

Zwei Autorenmodi — Auswahl nach der Form des Inhalts. parameters: akzeptiert entweder eine Inline-YAML-Map (Modus 1, oben gezeigt) oder einen einzelnen $import:-Schlüssel, der auf eine lokale Datei verweist (Modus 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Ein relativer $import:-Pfad wird vom Verzeichnis aus aufgelöst, das das Release enthält, in dem er steht, unabhängig davon, von wo ein Befehl ausgeführt wird, sodass Kommandozeile und Editor dieselbe Datei lesen; ein absoluter Pfad benennt seinen eigenen Ort, und beide müssen zu einer Datei innerhalb des Workspace führen — oder, bei einem Release, das außerhalb des Workspace angegeben wird, innerhalb des Verzeichnisses, das es enthält. Die beiden Modi schließen sich an dieser Stelle gegenseitig aus, und es kann nur eine einzige Datei importiert werden. Die Schichtung von Parametern über mehrere Dateien ist Sache von extends:-Ketten des Release: Das übergeordnete Release liefert einen Basissatz von Parametern, und das abgeleitete erweitert und überschreibt ihn pro Umgebung. Das Muster finden Sie weiter unten unter Zusammengesetztes Release / extends:-Vererbung.

Abgrenzung zwischen Parametern und infra. Parameter tragen die kognitive Absicht des Entwicklers, ausgedrückt als typisierte Slots, die das Aggregate deklariert; das Release erfüllt sie. infra: am Release trägt die physische Dimensionierung des Operators (Replikatanzahlen, CPU-/Speichergrenzen, Storage-Klassen), die bestimmten Komponenten oder Feature-Anbindungen zugeordnet ist. Parameter fließen über .parameters.X in die values:-Templates des Aggregate; infra: fließt über .infra.X in das valuesMapping:-Template des Recipe. Die Taxonomie der Datensäulen finden Sie unter architecture/06-data-taxonomy-and-composition.md §3, den Lebenszyklus der Parameter durch die Pipeline unter templates/parameters-context.md.

Boundaries und der Standardbereich

Ein Release gruppiert Komponenten in Boundaries — physische Bereitstellungseinheiten, jede mit eigenem Ausgabeverzeichnis und eigener Annotations-Kaskade. Der Fall mit einer einzigen Boundary ist der übliche und braucht daher keinen Aufwand.

Einzelner Bereich (der Standard). Verfassen Sie Komponenten direkt unter spec.components: und lassen Sie den boundaries:-Block weg. Der Compiler faltet sie in eine synthetisierte default-Boundary, deren Ausgabe flach ist — Artefakte landen direkt unter dist/ (je Provider, über den sicheren subDirectory-Standard weiter unten: dist/compose/, dist/helm/, …), ohne ein Segment mit dem Boundary-Namen im Pfad. Dies ist die einfachste Bereitstellung: aggrega build über ein flaches Compose- oder Single-Cluster-Ziel, ohne Boundaries zu benennen.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Mehrere Bereiche. Wenn ein Release mehr als eine physische Gruppierung umfasst — getrennte Cluster, Regionen oder Sync-Waves — deklarieren Sie benannte Boundaries unter boundaries:. Jede Boundary trägt ihr eigenes directory:, ihre eigene Annotations-Kaskade und ihren eigenen syncWave:, und Komponenten werden innerhalb ihrer Boundary adressiert.

Gegenseitiger Ausschluss. spec.components: und spec.boundaries: schließen sich an der Wurzel des Release gegenseitig aus — ein Release verfasst das eine oder das andere, niemals beides. Ein Dokument, das beides deklariert, hält beim Laden mit einem Envelope-Fehler an. Die components-Oberfläche auf oberster Ebene trägt dieselbe operatorseitige Form pro Komponente wie die components einer Boundary (infra:, annotations:, uses:).

Eine deklarierte Boundary namens default. Die flache Ausgabe ist eine Eigenschaft der synthetisierten Standard-Boundary, nicht des Namens. Eine Boundary namens default, die ein Release ausdrücklich unter boundaries: deklariert, ist eine gewöhnliche benannte Boundary: Ihre Ausgabe folgt ihrem directory: (standardmäßig dist/boundaries/default/), genau wie bei jeder anderen deklarierten Boundary.

Das Muster des Standardbereichs finden Sie unter architecture/06-data-taxonomy-and-composition.md §7.

Räumliche Trennung und Ausgabepfade

Jede Boundary deklariert ein physisches Ausgabe-directory für ihre kompilierten Artefakte; Komponenten innerhalb einer Boundary können es über ein subDirectory pro Komponente überschreiben. Der Compiler berechnet den endgültigen Artefaktpfad, indem er beide verbindet, auf jeder Plattform in durch Schrägstriche getrennter Form: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Ein Verzeichnis, eine Schreibweise. Der ausgewertete Pfad wird einmal bereinigt, sodass out/a, out//a, ./out/a und out/a/ ein einziges Verzeichnis sind. Boundaries, deren Pfade sich zum selben Verzeichnis bereinigen und die über denselben Provider gerendert werden, werden zusammen assembliert, genau wie Boundaries, die mit identischen Pfaden geschrieben sind.
  • Der Pfad bleibt unterhalb der Ausgabewurzel. Ein Pfad, der aus der Ausgabewurzel herausführt (.., ../escape, a/../..), ein absoluter Pfad oder einer, der überhaupt kein Verzeichnis benennt — leer oder zur Ausgabewurzel selbst bereinigt — stoppt den Build, bevor irgendetwas geschrieben wird. Die Meldung nennt das Release, die Boundary, das fehlerhafte Feld (directory: oder subDirectory:) und den Wert, zu dem es ausgewertet wurde, da dieser Wert oft das Ergebnis eines Templates ist.
  • Sicherer Standard. Wenn subDirectory weggelassen wird oder leer ist, wendet der Compiler automatisch subDirectory: "{{ .capability }}" an — die Artefakte jeder Rendering-Fähigkeit (Helm, Helm-chart, Compose, Terraform, CloudFormation) landen in einem eigenen Unterordner, was Kollisionen gemischter Artefakte in nachgelagerten CI/CD-Werkzeugen verhindert. Ein ausgeschriebenes subDirectory: "" wird genau wie ein weggelassenes gelesen und erhält daher ebenfalls diesen Standard.
  • Flache Überschreibung. Um Unterverzeichnisse ganz zu deaktivieren (alle Artefakte direkt unter directory), setzen Sie subDirectory: ".". Ein subDirectory-Template, das zu einer leeren Zeichenkette ausgewertet wird — etwa "{{ .parameters.sub }}" mit sub auf "" gesetzt — deaktiviert sie ebenfalls.
  • Template-Variablen. directory wird mit {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }} und {{ .parent_boundary.* }} für kaskadierende Daten aus einer umschließenden Boundary ausgewertet. subDirectory wird mit derselben Menge plus {{ .component_id }} ausgewertet (nur bei Überschreibungen pro Komponente). Der Compiler wertet Pfad-Templates mit missingkey=error aus — der Verweis auf eine nicht deklarierte Variable bricht den Build mit einer präzisen Diagnose ab. Die Matrix pro Kontext und die Kaskadenregeln der übergeordneten Boundary finden Sie unter Pfad-Template-Variablen.

Boundary-Annotationen kaskadieren nach unten auf jede enthaltene Komponente; infra bleibt strikt auf die Komponente beschränkt, auf die es abzielt. Die rekursive boundaries-Map erlaubt beliebige Verschachtelung (Boundary in Boundary in Boundary), während die Invarianten der Annotations-Kaskade und des lokalen infra auf jeder Ebene gelten.

Ausgearbeitetes Beispiel:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Durch diesen Mechanismus kaskadierte Annotationen erscheinen in nachgelagerten Recipe-Templates über .context.annotations.release; wie Renderer sie verwenden, erfahren Sie unter Recipe-Erstellung und in der Template-Expansionsmatrix.

Strukturierte Annotationswerte. Wenn ein Manifest-Binding für einen Annotationsschlüssel mehrere Routing-Pfade der infra-Säule deklariert, kann der Annotationswert auf Release-Seite ein strukturiertes Objekt sein, das in einer einzigen Deklaration Werte für mehrere Schemafelder eines Feature trägt:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

Strukturierte Werte kaskadieren mit einer tiefen Zusammenführung pro Unterschlüssel; Unterschlüssel einer näheren Ebene überschreiben die der übergeordneten Ebene. Ein null pro Unterschlüssel nimmt einen Unterschlüssel aus, während die benachbarten Unterschlüssel bestehen bleiben. Die Release-Seite wendet nur die Unterschlüssel an, deren Säule in der Binding-Map infra ist; Unterschlüssel, die zu values routen, gehören in Annotationen auf Aggregate-Seite. Die vollständige Erläuterung strukturierter Werte — seitenübergreifende Komposition, Typvalidierung pro Unterschlüssel, die Disziplin der gelockerten Standardwerte — finden Sie unter providers/well-known-annotations.md §„Strukturierte Annotationswerte“.

Bekannte Annotationen. Über Ad-hoc-Schlüssel hinaus definiert die Aggrega-Standardbibliothek eine Reihe bekannter Annotationen unter den Namespaces aggrega.ai/ und feature.aggrega.ai/, gruppiert in die Kategorien Platzierung, Netzwerk, Sicherheit und Beobachtbarkeit. Wer einer Release-Boundary Annotationen hinzufügt, sollte providers/well-known-annotations.md für die vollständige Matrix sowie die Verwendungsregeln pro Provider konsultieren — die Seite dokumentiert, welche Provider jeden bekannten Schlüssel anwenden und welches Verhalten sie erzeugen, wenn der Schlüssel vorhanden ist.

Verbindungskonfiguration pro Kante

Eine Boundary-Komponente kann einen uses:-Block tragen, der die Topologiekanten innerhalb der Sockets konfiguriert oder verdrahtet, die das Katalog-usesSchema der Component deklariert. Dies ist die Oberfläche des Operators pro Verbindung, so begrenzt, dass der Entwickler die Hoheit über die Architektur behält, die er verfasst hat:

  • Eine bestehende Kante konfigurieren. Setzen Sie infra pro Kante auf einer Kante, die der Entwickler bereits deklariert hat. Der Eintrag nennt den Alias des Entwicklers und liefert infra; er nennt entweder dasselbe Ziel, das der Entwickler verdrahtet hat, oder lässt das Ziel weg. Das infra wird gegen das infraSchema des Sockets validiert.
  • Einen ungebundenen Socket verdrahten. Erstellen Sie eine Kante in einen Socket, den das usesSchema der Component deklariert, den der Entwickler aber unverdrahtet gelassen hat, mit Verweis auf eine bestehende Komponente. Die erstellte Kante kann auch infra pro Kante tragen.
  • Auf einer Verbindung anbinden. Tragen Sie Anbindungen unter features: des Eintrags ein, geschlüsselt nach einem Slot, den der Socket in seinem featuresSchema deklariert — dieselben Slots, die der Verbindungseintrag des Entwicklers füllt. Jede trägt type, eine optionale description und infra, und niemals values. Unter einem Slot, den der Entwickler auf derselben Verbindung bereits gefüllt hat, dimensioniert der Eintrag diese Anbindung: Schreiben Sie nur infra, da Typ und Werte aus dem Aggregate stammen (ein hier geschriebener type muss mit dem des Aggregate übereinstimmen, sonst bricht der Build an diesem Eintrag ab und nennt beide). Unter einem Slot, den der Entwickler leer gelassen hat, gehört die Anbindung dem Release selbst, und type ist erforderlich. In beiden Fällen unterliegt die Füllung dem selector des Slots und zählt für einen required-Slot, genau wie die des Entwicklers.

Die Oberfläche ist erstellen, nicht umleiten: Ein Release darf eine Kante in einen ungebundenen Socket hinzufügen, aber keine Kante umleiten, die der Entwickler bereits deklariert hat. Ein Eintrag pro Kante, der ein anderes Ziel nennt als die Kante des Entwicklers, bricht den Build ab; ein Eintrag, der dasselbe Ziel nennt (oder es weglässt), konfiguriert diese Kante. Das Release darf außerdem keine values auf einer Kante oder auf einer dort geschriebenen Anbindung deklarieren (entwicklerseitige Werte bleiben im Aggregate), keinen Socket binden, den das usesSchema nicht deklariert, und keine Kante auf eine nicht existierende Komponente richten — jedes davon ist ein fataler Abbruch. Ebenso ein Eintrag, der infra oder features auf einer Verbindung setzt, die nicht existiert, sobald alle Kanten gezogen sind, es sei denn, die konsumierende Komponente ist mit active: false abgeschaltet. Siehe errors/fatal-halts.md §„Beim Aufbau der Topologie“.

Drei weitere Abbrüche halten die Anbindungen einer Verbindung auf ihrer Verbindung:

  • Ein Name, für den der Socket keinen Slot deklariert, führt zum Abbruch, genau wie auf dem Verbindungseintrag des Aggregate, an diesem Eintrag im Release, und nennt die Slots, die der Socket deklariert, sowie jene, von denen der Name nur eine Bearbeitung entfernt ist.
  • Eine Anbindung, die nur das Release vornimmt und die ohne type geschrieben ist, führt am Verbindungseintrag zum Abbruch und nennt den Slot. Eine Anbindung, die das Release vornimmt, trägt keine values und eignet sich daher für ein Feature, dessen values nichts erfordern; eines, dessen Schema einen Wert erfordert, bricht am selben Eintrag wegen des fehlenden Werts ab. Die Credential-Features der Standardbibliothek, die den Lokator eines Aufrufers tragen, erfordern in values keinen: Jedes nimmt ihn auch in infra entgegen (siehe unten).
  • Der zusammengesetzte Name, irgendwo anders als an der Verbindung geschrieben, führt zum Abbruch. Eine Verbindungsanbindung wird zu einer Anbindung der konsumierenden Komponente namens <alias>.<slot> (siehe den Verbindungseintrag des Aggregate), und sowohl die eigenen features:-Schlüssel eines Komponenteneintrags als auch die einer Boundary lassen einen Punkt zu. Ein Komponenteneintrag, der diesen Namen schreibt, oder eine Boundary, die ihn so schreibt, dass er eine Komponente erreicht, deren Verbindung ihn trägt — eine Komponente in dieser Boundary oder in einer darin verschachtelten, einschließlich derer eines gerouteten Untermoduls — führt zum Abbruch und nennt beide Schreibweisen, einmal für jede erreichte Komponente. Der Slot eines Sockets wird auf jeder Verbindung gefüllt und niemals durch eine Anbindung, die aus einem breiteren Bereich herabkaskadiert.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Eine Credential auf einer Verbindung, die das Release verdrahtet, nennt ihr Secret in infra. Eine Verbindung, die das Release verdrahtet, hat keinen Eintrag im Aggregate, sodass dort nichts die values der Credential schreibt, und das Release schreibt nirgends values. Jedes Credential-Feature der Standardbibliothek, das den Lokator eines Aufrufers trägt — core/referenced-secret, core/referenced-secret-set, core/secret-value und core/secret-provided — akzeptiert ihn daher sowohl in infra als auch in values: origin oder entries für core/referenced-secret-set, mit derselben Form und derselben sensitive: true-Deklaration in beiden Säulen. Jede Realisierung liest die Säule, die ihn trägt.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Der Lokator wird in genau einer Säule pro Anbindung geschrieben. Eine Anbindung, die ihn in beiden trägt — den values des Aggregate und dem infra des Release für denselben Slot — oder in keiner, bricht an der eigenen Assertion des Feature ab (E0033) und nennt das Feature, die Anbindung und die Komponente sowie welcher der beiden Fälle vorlag. Die Regel gehört zu den Katalogentitäten dieser Features, nicht zum Compiler, der ihre Assertion so auswertet wie die jedes Feature. Andere Felder als der Lokator behalten ihre Säule: key bleibt ein values-Blatt, sodass eine Anbindung, die nur das Release vornimmt, den Standard-Datenschlüssel des Feature liest, value. Das values:-Verbot bleibt unverändert — der Lokator des Operators ist infra.

core/secret-provided ist dasjenige, das nicht zu einer Verbindung passt: Es veröffentlicht seinen Wert, damit der eigene inject:-Block der Anbindung ihn ausliefert, und die Anbindung einer Verbindung trägt in keinem der beiden Dokumente einen inject:-Block, sodass auf einer Verbindung kein inject:-Block ihn ausliefert. Verwenden Sie dort core/referenced-secret oder core/secret-value.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

Das aufgelöste infra pro Kante fließt in den Render-Kontext der konsumierenden Komponente unter .context.uses.<alias>.infra.<key>; es erscheint nie im Kontext der Zielkomponente, sodass die gerenderte Ausgabe eines Ziels invariant gegenüber den Konsumenten ist, die Kanten zu ihm konfigurieren. Eine Anbindung auf einer Verbindung landet ebenfalls auf der konsumierenden Komponente, als eine ihrer Anbindungen: Ihr infra wird mit den values des Aggregate für denselben Slot zusammengeführt, und ihr FeatureRecipe rendert gegen beide. Das Recipe der konsumierenden Komponente liest sie unter ihrer Verbindung, bei .context.uses.<alias>.features.<slot>, und ihre Workload liefert sie aus, indem sie die Verbindung neben dem Slot nennt — siehe Eine Credential ausliefern, die eine Verbindung trägt.

Das Feld aggregates: — verschachtelte Untermodule in Boundaries routen

Wenn das Aggregate über spec.aggregates: verschachtelte Untermodule deklariert, entscheidet das Release, in welcher Boundary die Komponenten jedes Untermoduls landen, indem es aggregates: neben components: innerhalb der Ziel-Boundary deklariert:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Platzieren Sie jedes unter Aggregate.spec.aggregates: aufgeführte Unter-Aggregat in genau einer Boundary.

Routing platziert Komponenten. Jede Komponente eines gerouteten Untermoduls landet in der Boundary, die es routet, und übernimmt deren directory, subDirectory, syncWave und Annotationskaskade — denselben Kontext, den eine direkt unter components: benannte Komponente erhält, einschließlich der Herkunftsangabe aggrega.ai/boundary-path, die auf die ausgegebenen Artefakte gestempelt wird. Ein Untermodul zu routen und jede seiner Komponenten über ihren qualifizierten Punktpfad mit leerem Rumpf zu adressieren, erzeugt daher identische Artefakte; Routing ist die kürzere Art, es auszudrücken, und die einzige, es auszudrücken, ohne den Inhalt des Untermoduls zu kennen.

Eine Komponente gehört zu genau einer Boundary, und der Build bricht ab, wenn ein Dokument eine Komponente zweimal platziert — dasselbe Untermodul in zwei Boundaries geroutet, ein Untermodul in eine Boundary geroutet, während eine seiner Komponenten in einer anderen benannt ist, oder eine Komponente sowohl direkt als auch über einen Routing-Eintrag benannt. Die Diagnose nennt beide Stellen, denn welche beibehalten wird, entscheidet der Autor. Ein Untermodul in eine Boundary zu routen und eine seiner Komponenten unter derselben Boundary zu benennen, ist kein Konflikt: Das Routing platziert die Komponente, und der benannte Eintrag konfiguriert sie.

Ein Unter-Aggregat, das das Release nirgends platziert, bricht den Build ab. Die Platzierung wird über beide Schreibweisen hinweg gelesen, daher bricht der Build nur ab, wenn keine von beiden das Untermodul erreicht: Keine Boundary routet es unter aggregates:, und keine Boundary benennt eine seiner Komponenten unter components: über den qualifizierten Punktpfad. Jede Schreibweise allein platziert es, und ein Untermodul, dessen Komponenten alle einzeln benannt sind, benötigt keinen Routing-Eintrag. Die Korrektur gehört in den aggregates:-Block des Aggregate, das das Untermodul importiert hat — das Aggregate, das das Release bereitstellt, für ein direkt importiertes Untermodul, und das eigene Dokument des importierenden Untermoduls für ein verschachteltes. Die Diagnose nennt diesen Eintrag mit dem Schlüssel, mit dem das importierende Dokument ihn schreibt, sodass er sich für ein verschachteltes Untermodul als lokaler Name und nicht als Punktpfad liest.

Zwei Fälle brechen bewusst nicht ab. Ein Untermodul, das keine Komponenten beisteuert, hat nichts zu platzieren. Ein Untermodul, dessen Schalter active: zu false aufgelöst wird, wurde nie zusammengesetzt, sodass keine seiner Komponenten existiert, die platziert werden könnte.

Eine teilweise Platzierung löst diese Regel nicht aus: Ein Untermodul gilt als platziert, sobald eine seiner Komponenten eine Boundary erreicht, daher genügt es dem Untermodul, eine von ihnen zu benennen. Daraus folgt nicht, dass die übrigen weggelassen werden dürfen. Jede Komponente, die die Boundary nicht benannt hat, wird dann von nichts platziert, und die Komponentenregel weiter unten meldet sie an ihrem eigenen Schlüssel — ein teilweise platziertes Untermodul bricht den Build also einmal pro zurückgelassener Komponente ab, nicht am Untermodul. Die beiden Schreibweisen, die ein ganzes Untermodul in einer Zeile platzieren, sind der Routing-Eintrag und das Benennen jeder Komponente; alles dazwischen platziert, was es benennt, und nicht mehr.

Auch eine Komponente, die das Release nirgends platziert, bricht den Build ab, eine Ebene tiefer. Die obige Regel fragt, ob ein Untermodul eine Boundary erreicht hat; diese fragt dasselbe für jede Komponente, die die Komposition enthält. Eine Komponente erreicht eine Boundary, indem sie unter components: dieser Boundary benannt wird oder sich in einem Untermodul befindet, das eine Boundary hineinroutet. Eine, die keines von beiden erreicht, wird außerhalb jeder vom Release deklarierten Boundary gerendert und bezieht ihr directory, subDirectory, syncWave, ihre Annotationskaskade und ihr komponentenspezifisches infra: von nirgendwo — daher stoppt der Build und nennt die Komponente, statt Artefakte auszugeben, die die Boundary-Konfiguration nie erreicht hat.

Die beiden Regeln teilen das Feld auf, indem sie nach dem Untermodul der Komponente fragen, nicht bloß danach, ob sie eines hat. Eine Komponente eines Untermoduls, das das Release nirgends platziert hat, bleibt der Untermodulregel überlassen, die diesen einen Autorenfehler einmal am aggregates:-Eintrag meldet statt einmal pro Komponente, die das Modul enthält. Eine Komponente eines Untermoduls, das das Release teilweise platziert hat, fällt unter diese Regel, weil die Untermodulregel ein solches Modul als platziert liest und nichts darüber sagt — daher wird jede Komponente, die die Boundary nicht benannt hat, hier gemeldet, an ihrem eigenen Schlüssel innerhalb des Dokuments, das sie deklariert. Ein Untermodul teilweise zu platzieren benennt daher genau das, was Sie benennen wollten, und meldet Ihnen jede Komponente, die Sie nicht benannt haben.

Und ein Boundary-Eintrag, der eine Komponente benennt, die das bereitgestellte Aggregate nicht enthält, bricht den Build ab. Die beiden obigen Regeln lesen die Platzierung von der Seite der Komponente — hat irgendetwas sie platziert? Diese liest sie von der Seite des Release: Wird der Name aufgelöst? Ein Eintrag, der zu nichts aufgelöst wird, platziert nichts, sodass sein subDirectory, seine Annotationen, sein komponentenspezifisches infra: und sein uses: eine Komponente konfigurieren, die nicht vorhanden ist, und der Build stoppt, statt eine Bereitstellung auszugeben, die der Eintrag nie erreicht hat. Beide Schreibweisen werden geprüft: Ein Name unter components: einer Boundary wird als die ID gelesen, die die Komponente nach abgeschlossener Komposition trägt, und ein Name unter components: eines Routing-Eintrags als der lokale Name, den sie innerhalb dieses Untermoduls trägt. Die Diagnose meldet die ID, die der Eintrag adressiert hat, und diese ist bei der gerouteten Schreibweise nicht der Name in der Datei — die Datei schreibt die lokale Hälfte, und das Untermodul liefert ihr Präfix.

Ein Name wird abgelehnt, weil er zu nichts aufgelöst wird, und nie wegen seiner Form: Ein Name mit Punkt ist gewöhnlich, denn eine Komponente eine Modulebene tiefer trägt das Präfix dieses Moduls. Eine Komponente, deren Schalter active: zu false aufgelöst wird, bleibt benennbar — eine Komponente abzuschalten erfordert keine Änderung des Release, das sie konfiguriert.

Ein Subsystem trägt nichts zum qualifizierten Pfad bei, daher adressiert eine Boundary eine Komponente mit ihrem bloßen Namen, wie auch immer das Aggregate sie gruppiert. Nur die Komposition von Untermodulen qualifiziert eine ID. Eine Komponente des bereitgestellten Aggregate heißt store, ob der Autor sie auf oberster Ebene oder innerhalb eines Subsystems namens data geschrieben hat; eine Komponente eine Modulebene tiefer heißt data.store, und data ist dort das Präfix des Moduls und nicht das eines Subsystems. Ein Boundary-Eintrag, der data.store für eine Komponente in einem Subsystem namens data schreibt, adressiert also nichts: Der Eintrag selbst bricht nach der obigen Regel ab, und auch die Komponente, für die er gedacht war, erreicht keine Boundary. Den Eintrag auf store zu korrigieren, behebt beides.

Ein Untermodul zu platzieren erfordert daher boundaries:. Die Form mit einem einzigen Geltungsbereich hat keine Routing-Oberfläche — aggregates: ist ein Schlüssel einer Boundary, nicht von spec: — und die oberste components:-Map akzeptiert nur unqualifizierte Namen, daher deklariert ein Release, das ein Aggregate mit importierten Untermodulen bereitstellt, boundaries:.

Rekursives Routing. aggregates: ist rekursiv — jeder Eintrag unter aggregates: einer Boundary kann selbst eine verschachtelte aggregates:-Map für tief verschachtelte Modulkomposition deklarieren.

Routing-Block pro Aggregat. Ein Routing-Eintrag akzeptiert genau zwei Schlüssel und sonst nichts: components:, um einzelne Komponenten dieses Untermoduls zu konfigurieren, und ein verschachteltes aggregates: für tiefer verschachtelte Module. annotations: gehört zur Boundary, und komponentenspezifisches infra: gehört zu einem Eintrag unter dem eigenen components: des Routing-Eintrags.

Innerhalb eines Routing-Eintrags wird eine Komponente über den Namen geschlüsselt, den sie innerhalb ihres Untermoduls trägt — consumer, nicht data.consumer —, denn das ist der einzige Name, den sie dort hat. Der qualifizierte Punktpfad ist die Art, wie die components:-Map einer Boundary dieselbe Komponente adressiert; die beiden Schreibweisen sind nicht austauschbar, und ein Routing-Eintrag lehnt einen Schlüssel mit Punkt ab.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

Die eigenen Komponenten und Features des Unter-Aggregats werden im Release nicht erneut deklariert — das Release routet sie, statt sie zu wiederholen, und benennt eine nur, um sie zu konfigurieren.

Zeitliche Sequenzierung — syncWave pro Boundary

Jede Boundary im Release deklariert optional ein ganzzahliges Feld syncWave: und gibt dem Operator damit explizite Kontrolle über die Bereitstellungsreihenfolge, ohne das Aggregate des Entwicklers anzutasten. Die Wellennummer ist eine Eigenschaft der Boundary selbst; jede Komponente im Teilbaum der Boundary erbt beim Ausgeben der Artefakte den Wellenwert ihrer Boundary.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Semantik des Wellenwerts. syncWave: ist eine vorzeichenbehaftete Ganzzahl (positiv, null oder negativ). Der Standardwert bei weggelassenem Feld ist 0. Wellenwerte werden nicht von einer übergeordneten Boundary geerbt — jede Boundary, die eine vom Standard abweichende Welle möchte, deklariert sie explizit. Components können die Welle ihrer Boundary nicht überschreiben (die Welle ist eine Eigenschaft der räumlichen Einheit, nicht einzelner Komponenten).

Ausgabe pro Provider. Der Compiler gibt den Wellenwert der Boundary in der nativen Form des Providers in die gerenderte Ausgabe aus. Drei der Formen werden unten durchgegangen; was die Welle bei jedem Provider der Standardbibliothek bewirkt, terraform eingeschlossen, ist in providers/reference-matrix.md „Was die syncWave einer Boundary bei jedem Provider bewirkt“ tabellarisch aufgeführt.

  • Kubernetes (Provider helm / helm-chart). Wo die Welle nicht 0 ist, trägt jede Kubernetes-Ressource, die der helm-Provider für die Boundary rendert, die GitOps-übliche Annotation argocd.argoproj.io/sync-wave: "<N>"; Helm-Hooks tragen zusätzlich die Annotation helm.sh/hook-weight: "<N>", sodass derselbe Wellenwert Helms eigene pre/post-install-Reihenfolge steuert. ArgoCD liest die sync-wave-Annotation und Helm das Gewicht eines Hooks, und beide ordnen die Anwendung der Ressourcen entsprechend. Der helm-chart-Provider kopiert die Templates eines Quell-Charts so, wie ihr Autor sie geschrieben hat, sodass die eigenen Ressourcen eines Sub-Charts die Welle nur dort tragen, wo diese Templates sie schreiben; ein über $import: geladenes Artefakt, das er hinzufügt, trägt argocd.argoproj.io/sync-wave und kein helm.sh/hook-weight (siehe providers/helm-chart.md).
  • Compose. Jeder Dienst in der Compose-Datei, in die eine Boundary gerendert wird, wartet über depends_on auf die Dienste der unmittelbar vorhergehenden Welle, die zu derselben Datei beigetragen haben — abhängig vom Gesundheitszustand des Ziels, wo das Ziel einen healthcheck deklariert, und von seinem Start, wo es das nicht tut. Die Welle ordnet also die Dienste einer Datei und nichts außerhalb davon: Boundaries, die in separate docker-compose.yaml-Dateien gerendert werden, sind separate Compose-Projekte, und deren Sequenzierung ist Sache des Operators. uses:-Kanten drücken neben der Welle weiterhin eine Reihenfolge pro Kante aus. Siehe providers/compose.md.
  • CloudFormation. Jede Ressource im zusammengesetzten Stack-Template hängt über DependsOn von den Ressourcen der unmittelbar vorhergehenden Welle ab, die zu demselben Stack beigetragen haben — die Welle legt also die Reihenfolge fest, in der Ressourcen erstellt werden, und umgekehrt die Reihenfolge, in der sie gelöscht werden. Es handelt sich nicht um eine Bereitschaftsreihenfolge: Ein Stack-Template kennt keinen Begriff davon, dass eine Ressource einsatzbereit ist. Das eigene DependsOn eines Fragments wird erweitert statt ersetzt. Components, die in einen anderen Stack zusammengesetzt werden, liegen außerhalb der Reichweite, und die Sequenzierung zweier Stacks ist Sache des Operators. Siehe providers/cloudformation.md.

Einheit der Wellenerstellung vs. bereitstellbare Einheit. Die Boundary ist die Einheit, in der Wellen geschrieben werden. Die bereitstellbare Einheit ist der Assemblierungspfad, in den die Komponenten ausgegeben werden — standardmäßig 1:1 mit der Boundary, doch zwei Geschwister-Boundaries, die sich ein directory: teilen, fallen zu einer zusammengesetzten Ausgabe zusammen (ein Chart.yaml, ein docker-compose.yaml). In diesem Fall kann die zusammengesetzte Ausgabe Ressourcen aus mehreren Wellen enthalten; eine ArgoCD-Application, die sie liest, ordnet innerhalb der Application jede Ressource nach der sync-wave-Annotation, die diese Ressource trägt — bei helm jede für eine Welle ungleich null gerenderte Ressource, und bei helm-chart nur ein über $import: geladenes Artefakt, während die eigenen Templates eines Sub-Charts tragen, was ihr Autor geschrieben hat. Die Sequenzierung über Applications und Pfade hinweg ist Sache der CI des Operators.

Anwendungsfälle. Die Reihenfolge der Wellen ist immer dann wichtig, wenn der Start einer Boundary vom vorherigen Abschluss einer anderen abhängt. Kanonisches Muster: eine infra-Boundary in Welle 0 (VPC + Datenbank), eine migrations-Boundary in Welle 1 (Schema-Migrationsjob) und eine apps-Boundary in Welle 2 (die Anwendung, die das migrierte Schema nutzt). Ohne explizite Wellen werden alle drei gleichzeitig bereitgestellt, und die Anwendung gerät in eine Crash-Schleife, während sie auf den Abschluss der Migration wartet.

Für die vollständige architektonische Einordnung — das DAG-Ausführungsmodell, die Begründung, warum die zeitliche Sequenzierung im Release statt im Aggregate liegt, und die Unterscheidung zwischen Einheit der Wellenerstellung und bereitstellbarer Einheit — siehe architecture/12-day-two-lifecycles.md §1.

Feature-Anbindung

Das Release kann Features sowohl auf Boundary-Ebene (breite Richtlinie) als auch komponentenspezifisch (präzise Zielauswahl) anbinden, wobei die Ausführung dem in architecture/10-compilation-pipeline.md definierten 5-stufigen Zwiebelmodell folgt. Im Release deklarierte Features steuern type, infra und uses bei; sie können keine values deklarieren (siehe Einschränkungen auf Schemaebene oben).

Ein an einer Boundary angebundenes Feature wird über einen Instanznamen geschlüsselt, den Sie wählen, und dieser Name darf nicht . oder .. sein. Bei einem Provider, der jedem Beitragenden ein eigenes Verzeichnis gibt — terraform unter modules/ und helm-chart unter charts/ —, werden die Dateien, die ein Feature auf Boundary-Ebene erzeugt, in ein Verzeichnis geschrieben, das allein nach der Instanz benannt ist, und keiner dieser beiden Namen ist ein eigenes Verzeichnis: Der Build stoppt und nennt das Release, die Boundary und die Instanz. Ein Name, der lediglich Punkte enthält, wie audit.v2, ist ein gewöhnlicher Name.

features: ist die einzige Anbindungsoberfläche des Release, auf beiden Ebenen — so wie beim Aggregate. Ein Zugangsnachweis ist ein Feature mit dem Label feature.aggrega.ai/kind: secret, daher wird ein vom Operator angebundener Zugangsnachweis wie jedes andere Feature unter features: angebunden und nennt sein Secret in infra genau so, wie es einer auf einer Verbindung tut (siehe Verbindungskonfiguration pro Kante) — an einer Komponente, die das Aggregate ohne einen gelassen hat, oder als Dimensionierung einer Anbindung, die das Aggregate deklariert hat, ohne ein Secret zu nennen. Es gibt auf keiner Ebene ein zweites Anbindungsschlüsselwort; ein Dokument, das eines deklariert, wird beim Laden mit einem Envelope-Fehler abgelehnt, der die unerwartete Eigenschaft nennt.

Ein Boundary-weit angebundenes Feature kann einen uses:-Block tragen, und dieser Block wird auf jede in die Boundary geroutete Komponente projiziert: Jede Komponente erhält eine Abhängigkeitskante zu den Zielen, die das Feature benennt, und bekommt die provides dieser Ziele injiziert. So wird eine gemeinsame Abhängigkeit einmal an der Boundary ausgedrückt — „jede Komponente in dieser Boundary kommuniziert mit dem gemeinsamen Cache / Collector / Message-Bus“ —, statt dieselbe uses:-Kante an jeder Komponente zu wiederholen. Eine Feature-Anbindung auf Subsystemebene im Aggregate projiziert ihr uses: auf dieselbe Weise über die Komponenten des Subsystems. uses ist eine Deklaration der Topologieverdrahtung, kein Wert, und ist daher im Release erlaubt. Die Projektion ist unabhängig vom Ausführungsbereich des angebundenen Feature: Ein Feature, dessen FeatureRecipe einmal pro Boundary rendert, projiziert sein uses: dennoch pro Komponente, während die gemeinsame Ressource selbst einmal gerendert wird.

Ein an eine einzelne Komponente angebundenes Feature trägt denselben uses:-Block und verdrahtet dieselbe Kante von dieser einen Komponente aus: Die Komponente erhält eine Abhängigkeitskante zu jedem benannten Ziel, bekommt die provides dieser Ziele injiziert, und die Kante verzeichnet die Anbindung als ihren Ursprung, genau wie es die Boundary-weite Form tut. Die beiden sind eine Deklaration in zwei Breiten — an der Boundary anbinden, um jede Komponente darin zu verdrahten, an einer Komponente anbinden, um diese eine zu verdrahten —, und die Wahl zwischen ihnen ist eine Frage der Reichweite, nie dessen, was die Verdrahtung tut. Keine von beiden erzeugt Rechenressourcen: Das Ziel muss bereits eine Komponente benennen, die das Aggregate deklariert hat, und eines, das das nicht tut, bricht den Build ab. Eine Verbindung, die ein Feature zieht, trägt keine eigenen Anbindungen: Ihr Eintrag nimmt target und inject an, und ein features:-Schlüssel dort wird beim Laden des Release abgelehnt.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Wie ein Ziel geschrieben wird. Ein Kantenziel benennt eine Komponente des zusammengesetzten Graphen, daher wird es mit dem qualifizierten Punktpfad geschrieben — data.store, nicht store —, wann immer das Ziel zu einem gerouteten Untermodul gehört. Das gilt selbst dort, wo die Anbindung selbst unter einem Routing-Eintrag sitzt, dessen components:-Schlüssel modullokal sind: Der Schlüssel sagt, an welcher Komponente die Anbindung hängt, und das Ziel sagt, welche Komponente die Kante erreicht, und nur Letzteres ist ein graphweiter Name. Ein mit einem modullokalen Namen geschriebenes Ziel passt zu keiner Komponente und bricht mit derselben Diagnose ab, die jede hängende Kante erzeugt.

Zusammengesetztes Release und Vererbung über extends:

Ein Release kann spec.extends: deklarieren und damit auf ein Basis-Release verweisen, dessen Authoring-Oberfläche es erbt.

Die Referenz ist ein Pfad zu einer Datei neben dem deklarierenden Release — ./base-release.yaml oder ../shared/base-release.yaml. Ein Release gehört zur Bereitstellungsseite und wird nicht im Katalog indiziert, daher wird eine extends:-Referenz nie über den Katalog aufgelöst. Der relative Pfad ist die einzige Form, die sie akzeptiert: Eine als Registry-Koordinate geschriebene Referenz wird abgelehnt, ebenso ein bloßer Name, jeweils mit der Form des relativen Pfads in der Diagnose genannt. Das extends: in einem Manifest ist der nahe Verwandte, der anders gelesen wird — es akzeptiert einen relativen Pfad oder den bloßen metadata.name eines neben dem Release liegenden Manifest —, daher sind die beiden Formen nicht austauschbar, und ein bloßer Name, der bei einem Manifest aufgelöst würde, wird hier nicht aufgelöst. Jedes Glied einer Kette wird gleich gelesen: Ein Eltern-Release, das in einem anderen Verzeichnis liegt, benennt sein eigenes Eltern-Release über einen Pfad neben sich selbst, wo auch immer das von Ihnen angegebene Release liegt, genau so, wie sein Parameter-$import: neben ihm aufgelöst wird. Der Pfad muss zu einem Release innerhalb des Workspace führen, wie es jeder Pfad muss, den ein Release schreibt — oder, bei einem außerhalb des Workspace angegebenen Release, innerhalb des Verzeichnisses, das dieses Release enthält, woran jedes Glied seiner Kette gebunden ist: Ein Pfad, der hinausführt oder den ein Glied hinausträgt, wird abgelehnt, bevor die von ihm benannte Datei gelesen wird.

Der Compiler folgt der Kette, wenn das Release geladen wird — und lehnt dabei eine Kette ab, die zu einer bereits in ihr enthaltenen Datei zurückkehrt, eine, die die Tiefengrenze überschreitet, sowie eine Referenz, die nichts benennt —, und fasst die Kette anschließend zu einem einzigen aufgelösten Release zusammen.

Was Sie erben, dürfen Sie Schlüssel für Schlüssel ersetzen. Ihr Wert gewinnt, bis ganz nach unten, bis Sie einen Wert erreichen, der ein unteilbares Ganzes ist — ein Skalar, eine Liste, ein Template —, den Sie ganz übernehmen oder ganz ersetzen. Etwas Geerbtes entfernen Sie, indem Sie es als null schreiben. Das ist dieselbe Regel, der eine erweiternde Component, ein erweiterndes Feature und ein erweiterndes Manifest folgen, sodass ein Autor, der eines davon kennt, alle kennt.

Auf ein Release angewendet: boundaries werden pro Boundary-Name und eine Boundary pro Schlüssel zusammengesetzt, components pro Komponentenname, infra tief, features pro Instanzname und dann pro Säule; die uses einer Komponente pro Socket und dann pro Verbindung, wobei ein vom Kind geschriebenes target das geerbte ersetzt, das infra der Verbindung Schlüssel für Schlüssel zusammengesetzt wird und ihre features pro Slot und dann pro Säule nach derselben Regel zusammengesetzt werden, der die eigenen features einer Komponente folgen; directory, subDirectory, syncWave sowie die Aggregate- und Manifest-Zeiger sind Skalare, die ersetzen.

Zwei Dinge werden nicht übertragen:

  • Identität und Herkunft. Kein metadata-Feld wird geerbt. metadata.environment ist dasjenige, das man kennen sollte: Es ist für jedes Release erforderlich und naturgemäß jedem Release eigen, daher rendert ein Kind mit seiner eigenen Umgebung in seinen Herkunfts-Labels statt mit der seines Elternteils.
  • Der Aggregate-Zeiger wird geerbt, statt überschreibbar zu sein. Das Kind kann aggregate: nicht deklarieren — das Schema lehnt extends: und aggregate: in einem Dokument ab —, daher stellt ein Kind dieselbe Entwicklerabsicht bereit wie seine Basis.

Das Kind kann manifest: weglassen und das seiner Basis erben oder es für Late Binding überschreiben.

Eine Routing-Form entlang der Kette. boundaries: und components: schließen sich innerhalb eines einzelnen Release gegenseitig aus, und das gilt auch entlang einer Kette: Eine Basis, die benannte Boundaries deklariert, zusammen mit einem Kind, das Komponenten auf oberster Ebene deklariert, wird abgelehnt, und die Diagnose nennt beide Dateien und beide Schlüssel. Wählen Sie eine Routing-Form und verwenden Sie sie bis ganz nach unten.

Das Brückenmuster für die lokale Entwicklung. Der kanonische Anwendungsfall ist ein Entwickler, der das Produktions-Aggregate seines Teams lokal ausführt, ohne das Aggregate zu forken oder die Boundary-Topologie zu duplizieren. Das Team veröffentlicht ein Produktions-Release; ein lokales Release erweitert es per extends: und überschreibt nur den Manifest-Zeiger, wobei es Cloud-orientierte Recipes gegen lokale Entsprechungen austauscht:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release erbt von seiner Basis die Boundary-Topologie, die Feature-Anbindungen und die Komponenten-Überschreibungen; der Entwickler pflegt eine einzige local-release.yaml und führt aggrega build --release local-release.yaml aus, ohne Produktionskonfiguration zu duplizieren.

Schreiben Sie directory: anhand eines Parameters. Da ein Verzeichnis wie jeder andere Skalar geerbt wird, rendert ein Kind, das ein Verzeichnis ohne Template-Variable erbt, in denselben Pfad wie seine Basis, und keine Befehlszeilenoption leitet es um. Das ist legitim, wenn es Ihre Absicht ist — etwa nur die Recipes auszutauschen, um ihre Ausgabe zu vergleichen —, daher meldet der Build es und fährt fort, statt abzulehnen. Das Verzeichnis anhand eines Parameters zu schreiben, wie oben, hält die Topologie an einer Stelle und sendet die Ausgabe jedes Release dennoch an einen eigenen Ort.

Parameter-Schichtung über mehrere Dateien. Die Release-Vererbung ist der Ort für die Schichtung von Parametern über mehrere Dateien. Ein Basis-Release liefert den gemeinsamen Parametersatz; umgebungsspezifische Kinder erweitern die Basis per extends: und überschreiben die Slots, die sich unterscheiden:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Jedes Kind sieht die geerbten Parameter seiner Basis mit seinen eigenen zusammengeführt. Map-wertige Parameter werden tief zusammengeführt, wobei der Schlüssel des Kindes gewinnt; skalarwertige Parameter werden vom Kind ersetzt; ein Schlüssel, den ein Kind als null schreibt, wird entfernt, statt auf nichts gesetzt zu werden.

Eine Basis kann ihre Parameter importieren, und ein Kind kann dennoch einzelne Schlüssel überschreiben. Die beiden oben unter parameters: beschriebenen Authoring-Modi — inline oder ein einzelnes $import: — sind eine Regel über ein Dokument, nicht über eine Kette: Jedes Release entlang der Kette deklariert den einen oder den anderen Modus, und der Import jedes einzelnen wird relativ zu dem Verzeichnis aufgelöst, das dieses Release enthält, bevor die Kette zusammengefasst wird. Eine Basis, die eine gemeinsame Datei importiert, und ein Kind, das einige Schlüssel inline schreibt, werden daher pro Schlüssel zusammengesetzt, genau wie zwei Inline-Blöcke es würden:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Fehlermodi. Zyklische extends:-Ketten, fehlende Eltern-Zeiger und kindseitige aggregate:-Deklarationen halten das Laden des Workspace mit expliziten Diagnosen an, die das betreffende Release und den Verstoß auf Schemaebene benennen. Siehe errors/fatal-halts.md für die Meldungsformen der einzelnen Fehler.