Netzwerke über Boundaries hinweg — eine Absicht, zwei Bereitstellungen
Ein Stack aus zwei Komponenten — eine Datenbank-Oberfläche Adminer und eine Datenbank PostgreSQL — aufgeteilt auf zwei Boundaries, wobei Adminer die Datenbank über die Boundary-Nahtstelle hinweg erreichen muss. Dieselbe Entwicklerabsicht wird auf zwei Arten bereitgestellt, und der Kontrast ist die Lektion:
- Lokal (Docker Compose): Jede Boundary ist ein eigenes Compose-Netzwerk, und ein Dienst in der einen kann einen Dienst in der anderen nicht über den Namen erreichen. Das Compose-FeatureRecipe des Feature
core/compose-bridgeder Standardbibliothek erzeugt ein Gatewayaggrega-gw, um diese Nahtstelle zu überqueren. - Kubernetes (Helm): Jede Boundary ist ein eigener Namespace, und ein Pod in einem erreicht einen Service in einem anderen über natives namespaceübergreifendes DNS (
db-default.backend) — keine Brücke. Die Datenbank veröffentlicht einen bloßen Dienstnamen; die Routing-Funktioncore/k8s-dns-resolverdes Konsumenten qualifiziert ihn mit dem Ziel-Namespace.
Was die compose-bridge leistet, geben Ihnen Kubernetes-Namespaces + namespaceübergreifendes DNS nativ. Das Überqueren der Nahtstelle ist ein Anliegen von Ops/Operator, das sich je nach Ziel unterscheidet; die Entwicklerabsicht ändert sich nicht. Dieselbe Boundary-Annotation aggrega.ai/namespace steuert in der einen Variante die Platzierung im Compose-Netzwerk und in der anderen die Platzierung im Kubernetes-Namespace.
Die gemeinsame Entwicklerabsicht
aggregate.yaml ist für beide Varianten identisch:
components: adminer: type: core/devtool/adminer uses: databases: primary: target: db inject: env: - in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant from: host # ← the target db's provides.host db: type: core/datastore/postgresDie eine uses-Kante injiziert den host der Datenbank in ADMINER_DEFAULT_SERVER. Worauf dieser Host aufgelöst wird, ist ein Anliegen von Ops, das unterhalb des Aggregate entschieden wird — daher ergibt dieselbe Kante unter compose aggrega-gw:5432 und unter helm db-default.backend, ohne Änderung an der Entwicklerabsicht.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example cross-boundary-networkingDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd cross-boundary-networkingBuild
Jede Variante ist ein Release, gebaut gegen ihr eigenes Katalogverzeichnis, ein Release pro Lauf:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Arbeitsbereichsordner noch keinen Ordner `cross-boundary-networking` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `cross-boundary-networking` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `cross-boundary-networking`. Rufen Sie dann das Tool `build` mit `workspace_root` auf `cross-boundary-networking`, `release` auf `release-compose.yaml`, `catalog_dirs` auf eine Liste mit `catalog-compose`, `auto_pull` auf true und `write` auf true gesetzt auf. Rufen Sie dann das Tool `build` auf dieselbe Weise mit `release` auf `release-helm.yaml` und `catalog_dirs` auf eine Liste mit `catalog-helm` gesetzt auf. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `cross-boundary-networking/dist/`.Variante A — lokal (Docker Compose): die Brücke
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeEine übergeordnete Boundary bridge enthält zwei untergeordnete, frontend (adminer) und backend (db), die sich ein Verzeichnis teilen und so zu einer einzigen dist/bridge/compose/docker-compose.yaml zusammengeführt werden. Die Annotation aggrega.ai/namespace jeder untergeordneten Boundary wird zu einem Compose-Netzwerk. core/compose-bridge, an der übergeordneten Boundary angebunden (Boundary-Geltungsbereich), leitet aus der netzwerkübergreifenden uses-Kante ein Gateway aggrega-gw ab. Sein FeatureRecipe aus der Standardbibliothek berechnet einmal für die Boundary eine Tabelle der zu überbrückenden Kanten — beide Enden in dieser einen Compose-Datei, in verschiedenen Netzwerken —, und alles Folgende wird von seinen eigenen Vorlagen aus dieser Tabelle gelesen:
- sein
valuesMappingschreibt die nginx-Konfigurationstreamdes Gateways, zugestellt als eingehängte Compose-config (configs:auf oberster Ebene, eingehängt unter/etc/nginx/nginx.conf); sie trägt einenresolverund einenproxy_passmit Variable pro Kante, sodass der Upstream zum Verbindungszeitpunkt aufgelöst wird (das$wird zu$$maskiert, damit die Interpolation von Compose es für nginx unverändert lässt); - dasselbe
valuesMappingnennt beide Enden unterx-aggrega-networks-ofdes Gateways, das der Provider compose auflöst, sodass das Gateway beiden überbrückten Netzwerken beitritt; - sein
injectMapping, für adminer ausgeführt, schreibtADMINER_DEFAULT_SERVERdes Konsumenten aufaggrega-gw:5432um. Die Umschreibung ersetzt, was die eigene Verbindungdatabasesvon adminer zugestellt hat; hätte ein anderes an adminer angebundenes Feature diese Variable zugestellt, würde der Build abbrechen und beide nennen, statt sie zu ersetzen.
Der Datenverkehr fließt also adminer → aggrega-gw:5432 → proxy_pass db:5432 und überquert die Netzwerk-Nahtstelle über das Gateway.
Ausführen
cd dist/bridge/composedocker compose upÖffnen Sie http://localhost:8080 (Server mit aggrega-gw:5432 vorausgefüllt) und melden Sie sich an:
| Feld | Wert |
|---|---|
| System | PostgreSQL |
| Server | aggrega-gw:5432 (vorausgefüllt) |
| Benutzername | appuser |
| Passwort | apppass |
| Datenbank | appdb |
Die Zugangsdaten sind nur für Demozwecke (inline im db-Recipe gesetzt, damit der Stack sofort läuft); eine echte Bereitstellung verwendet das Zugangsdaten-Subsystem.
Variante B — Kubernetes (Helm): Namespaces + namespaceübergreifendes DNS
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmDasselbe Aggregate, auf Kubernetes bereitgestellt. Zwei gleichrangige Boundaries, jede mit einer eigenen Annotation aggrega.ai/namespace, die sich als metadata.namespace auf jede Ressource überträgt:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendEs gibt kein aggrega-gw. Das helm-Recipe db veröffentlicht in provides.host einen bloßen Dienstnamen — der Provider helm benennt den synthetisierten Service <rendered_name>-<service-key> (db-default), ohne Namespace. Der Konsument bindet die Routing-Funktion core/k8s-dns-resolver an (das Release richtet sie auf ADMINER_DEFAULT_SERVER), und die Funktion qualifiziert diesen bloßen Host auf der eigenen Seite des Konsumenten mit dem Namespace des Ziels — wodurch der namespaceübergreifende DNS-Name db-default.backend entsteht, bevor Adminer gerendert wird. Der Host ist abgeleitet, nicht von Hand in den Produzenten geschrieben:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>Dieser Wert ist byteidentisch mit metadata.name + metadata.namespace des gerenderten db-Service, und das ist der ganze Beweis: Namespaceübergreifendes DNS von Kubernetes ist ein deterministischer Vertrag, wenn also der gerenderte Host der gerenderten Service-Identität entspricht, wird er zur Laufzeit aufgelöst — kein Gateway, kein laufender Cluster nötig, um die Verdrahtung zu prüfen.
Die Dualität
| compose (Variante A) | helm (Variante B) | |
|---|---|---|
| Boundary-Nahtstelle | getrennte Compose-Netzwerke | getrennte Namespaces |
| Überquerungsmechanismus | Gateway von core/compose-bridge (aggrega-gw) | natives namespaceübergreifendes DNS |
ADMINER_DEFAULT_SERVER wird aufgelöst zu | aggrega-gw:5432 (umgeschrieben) | db-default.backend (auf der Aufruferseite qualifiziert) |
| zusätzliche Ressource | der Dienst aggrega-gw + seine Konfiguration | keine |
dasselbe aggrega.ai/namespace steuert | die Platzierung im Compose-Netzwerk | die Platzierung im k8s-Namespace |
Eine Entwicklerabsicht; das Überqueren der Nahtstelle ist providerspezifische Mechanik von Ops/Operator. Die Compose-Brücke existiert, weil ein flaches Compose-Netzwerk kein namespacebezogenes DNS hat; Kubernetes gibt Ihnen das nativ.
Wenn die beiden Enden unter verschiedenen Providern gerendert werden
Beide Varianten oben behalten eine Entwicklerabsicht bei und lassen das Überqueren auf einem deterministischen Zeiger-String beruhen: provides.host der Datenbank fließt als stabiler Zeiger über die Boundary-Nahtstelle, und jedes Ziel löst diesen Zeiger auf seine eigene Weise auf — eine Compose-Gateway-Adresse oder ein namespaceübergreifender DNS-Name. Der Zeiger überquert immer, weil der Compiler Strings zwischen einem Produzenten und einem Konsumenten weiterleitet, ohne sie zu interpretieren.
Ein Provider kann weiter gehen und eine native Querreferenz zwischen zwei seiner eigenen zusammengesetzten Artefakte auf beiden Seiten der Nahtstelle verdrahten — eine Referenz im eigenen Vokabular dieses Providers, die die Zielplattform zum Zeitpunkt der Bereitstellung auflöst. Der CloudFormation-Provider tut dies für eine uses-Kante, die Stacks überquert: Der Produzenten-Stack veröffentlicht einen Export, und der Konsumenten-Stack liest ihn mit Fn::ImportValue (siehe providers/cloudformation.md). Eine native Querreferenz ist eine Verbesserung innerhalb desselben Providers — sie funktioniert, weil beide Enden dasselbe Artefaktvokabular sprechen, sodass eine Seite eine Referenz veröffentlichen kann, die die andere Seite aufzulösen weiß.
Wenn eine uses-Kante eine Boundary zwischen zwei verschiedenen Providern überquert — der Produzent wird unter einem Provider zusammengesetzt und der Konsument unter einem anderen —, ist keine native Querreferenz möglich. Eine im Vokabular eines Providers geprägte Referenz bedeutet dem anderen nichts, und der Compiler übersetzt nicht zwischen ihnen: Er leitet Strings weiter, er leitet keine Bedeutung ab und schreibt nicht die Referenz eines Providers in die Form eines anderen um. Daher überquert der deterministische Zeiger des Produzenten die Nahtstelle unverändert; wo einer der beiden Provider eigene native Querreferenzen verdrahtet, wie CloudFormation es tut, gibt der Compiler eine Warnung aus, die beide Endpunkte, beide Providernamen und den Socket nennt; und der Build wird auf diesem Zeiger abgeschlossen. Der Compiler vertraut dem Autor und bricht nicht ab: Ein deterministischer Zeiger, den der Autor geliefert hat, kann durchaus über die Nahtstelle hinweg auflösbar sein — ein stabiler DNS-Name oder ein Interpolationsstring der Infrastruktur —, und nur der Autor kennt die Zieltopologie.
So bleibt das Überqueren der Nahtstelle dort, wo es hingehört. Ob ein providerübergreifender Zeiger verwendbar ist, ist eine Frage der Bereitstellung, die dem Autor gehört; die native Referenz eines Providers in die Konsumentenform eines anderen Providers zu übersetzen, ist meinungsbehaftete, providerspezifische Arbeit, die außerhalb des neutralen Kerns liegt.
Aufbau
cross-boundary-networking/├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry├── aggregate.yaml # SHARED developer intent (both variants)├── release-compose.yaml # Variant A: parent bridge boundary + two networks├── manifest-compose.yaml├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)├── release-helm.yaml # Variant B: two namespace boundaries, no bridge├── manifest-helm.yaml└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)Dieses Beispiel konsumiert die Standardbibliothek. Jede Variante baut mit --catalog catalog-<variant>, ihrem eigenen lokalen Verzeichnis, und löst, was dieses Verzeichnis nicht deklariert, aus hub.aggrega.ai auf, der Standard-Registry, die .aggrega-config.yaml nennt, sodass lokale Entitäten vor den gemeinsamen aufgelöst werden. core/datastore/postgres, die gemeinsame UI-Komponente core/devtool/adminer, die Features core/compose-bridge und core/k8s-dns-resolver mit ihren FeatureRecipes für compose und helm sowie die Provider compose/helm stammen aus dem Standardkatalog. Lokal bleibt der beispielspezifische Lehrinhalt: die Adminer-Recipes pro Ziel. Das helm-Recipe db ist helm/postgres der Standardbibliothek, dessen provides.host ein bloßer, in sich geschlossener Dienstname ist. Der Konsument qualifiziert ihn auf der Aufruferseite über die Routing-Funktion core/k8s-dns-resolver der Standardbibliothek mit dem Ziel-Namespace, sodass das Recipe keinen Boundary-Namespace fest codiert.
In einer gebauten Variante treffen zwei Kategorien von Dateien aufeinander: verfasste Eingaben (alles oben) und vom Compiler erzeugte Ausgabe unter dist/ (die zusammengeführte docker-compose.yaml oder die helm-Manifeste pro Namespace) — Letztere verfassen Sie nicht. dist/ wird von aggrega build neu erzeugt und von git ignoriert.