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

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-bridge der Standardbibliothek erzeugt ein Gateway aggrega-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-Funktion core/k8s-dns-resolver des 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/postgres

Die 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:

Terminal window
aggrega scaffold --example cross-boundary-networking

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd cross-boundary-networking

Build

Jede Variante ist ein Release, gebaut gegen ihr eigenes Katalogverzeichnis, ein Release pro Lauf:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Mit 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

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

Eine ü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 valuesMapping schreibt die nginx-Konfiguration stream des Gateways, zugestellt als eingehängte Compose-config (configs: auf oberster Ebene, eingehängt unter /etc/nginx/nginx.conf); sie trägt einen resolver und einen proxy_pass mit 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 valuesMapping nennt beide Enden unter x-aggrega-networks-of des Gateways, das der Provider compose auflöst, sodass das Gateway beiden überbrückten Netzwerken beitritt;
  • sein injectMapping, für adminer ausgeführt, schreibt ADMINER_DEFAULT_SERVER des Konsumenten auf aggrega-gw:5432 um. Die Umschreibung ersetzt, was die eigene Verbindung databases von 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

Terminal window
cd dist/bridge/compose
docker compose up

Öffnen Sie http://localhost:8080 (Server mit aggrega-gw:5432 vorausgefüllt) und melden Sie sich an:

FeldWert
SystemPostgreSQL
Serveraggrega-gw:5432 (vorausgefüllt)
Benutzernameappuser
Passwortapppass
Datenbankappdb

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

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Dasselbe 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: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

Es 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:

dist/frontend/helm/adminer-deployment.yaml
- 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-Nahtstellegetrennte Compose-Netzwerkegetrennte Namespaces
ÜberquerungsmechanismusGateway von core/compose-bridge (aggrega-gw)natives namespaceübergreifendes DNS
ADMINER_DEFAULT_SERVER wird aufgelöst zuaggrega-gw:5432 (umgeschrieben)db-default.backend (auf der Aufruferseite qualifiziert)
zusätzliche Ressourceder Dienst aggrega-gw + seine Konfigurationkeine
dasselbe aggrega.ai/namespace steuertdie Platzierung im Compose-Netzwerkdie 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.