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

Kong-Stack — ein datenbankgestütztes API-Gateway, als Modul zusammengesetzt

Dieses Beispiel kompiliert einen kleinen, realen Stack — ein datenbankgestütztes API-Gateway — aus einem einzigen vom Entwickler verfassten Aggregate zu synthetisierten Kubernetes-Manifesten.

Das Gateway ist keine einzelne Komponente. Es ist ein Modul: ein wiederverwendbares Sub-Aggregat, das zwei Komponenten mit je einer einzigen Arbeitslast zusammensetzt —

  • ein Gateway, das den Client-Datenverkehr an seinem Proxy-Port terminiert und keinen lokalen Zustand hält, und
  • ein Backend, PostgreSQL, das die Konfiguration des Gateways hält und sie auf einem Volume persistiert.

Das Modul verdrahtet seine eigene interne Kante vom Gateway zum Backend und exportiert das Gateway als seinen öffentlichen Endpunkt proxy. Das Aggregate der obersten Ebene importiert das Modul über seinen Namen und rendert den zusammengesetzten Stack; der Betreiber dimensioniert die internen Komponenten des Moduls im Release.

Dateien

DateiRolle
aggregate.yamlEntwicklerabsicht: importiert das API-Gateway-Modul (core/kong).
manifest-helm-synth.yamlOrdnet die Typen Gateway und Backend ihren synth-helm-Recipes zu.
release-helm-synth.yamlBetreiber-Datensatz für das Kubernetes-Ziel. Dimensioniert die internen Komponenten des Moduls über ihre modulbezogenen IDs; alles, was den Schema-Voreinstellungen überlassen bleibt, wird in sich geschlossen gerendert.

Was es zeigt

  • Komposition als Modul. Eine Fähigkeit aus mehreren Arbeitslasten — ein API-Gateway, das eigentlich ein Proxy plus eine Konfigurationsdatenbank ist — wird als Sub-Aggregat verpackt, das zwei Komponenten mit je einer einzigen Arbeitslast zusammensetzt, nicht als eine monolithische Komponente. Das Modul wird über seinen Namen importiert und überall wiederverwendet, wo ein Gateway gebraucht wird.
  • Eine interne Kante innerhalb des Moduls. Das Gateway deklariert eine Nutzung des Backends; Host, Port, Benutzer und Datenbank aus den provides des Backend-Recipe werden in das Gateway durchgereicht und zu seiner PostgreSQL-Verbindung zusammengesetzt. Der Compiler leitet die Strings weiter, ohne sie zu interpretieren.
  • Ein öffentlicher Endpunkt. Das Modul exportiert sein Gateway als proxy, den stabilen öffentlichen Namen, mit dem sich ein Konsument verbindet — entkoppelt von den internen Komponentennamen des Moduls.
  • Dimensionierung interner Komponenten durch den Betreiber. Das Release adressiert die internen Komponenten des Moduls über ihre modulbezogenen IDs (gateway.backend, gateway.gateway), um Rechenressourcen festzulegen, ohne dass das Aggregate des Entwicklers die physische Dimensionierung wiederholt.
  • Ein Migrationsschritt, der läuft, bevor Anfragen bedient werden. Das Gateway richtet sein Datenbankschema über einen Init-Container ein, der vollständig durchläuft, bevor der Haupt-Container des Gateways startet, sodass das Gateway Anfragen gegen ein fertiges Schema bedient. Der Bootstrap ist idempotent, sodass ein erneuter Lauf gegen eine bereits eingerichtete Datenbank keine Wirkung hat.
  • Gemeinsame Zugangsdaten. Das Gateway authentifiziert sich bei seinem PostgreSQL-Backend, daher teilen sich beide ein Passwort. Dieses Beispiel verwendet einen gemeinsamen, inline angegebenen Entwicklungs-Standardwert, sodass der Stack in sich geschlossen ohne externes Secret läuft.
  • Reproduzierbare Images. Sowohl das Gateway als auch das Backend heften explizite Image-Tags an, daher verweisen die gerenderten Manifeste auf stabile Images.

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 kong-stack

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

Terminal window
cd kong-stack

Build

Dieser Workspace enthält kein .aggrega-config.yaml, daher werden die Entitäten der Standardbibliothek aus der Hub-Registry hub.aggrega.ai aufgelöst, und es ist kein Katalog-Flag nötig; --auto-pull schreibt während des Builds das Lockfile, das einem frischen Klon fehlt:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

Gerenderte Artefakte landen unter dist/. Das Kubernetes-Ziel rendert einfache Manifeste offline — es ist kein Chart-Pull erforderlich.

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 Workspace-Ordner noch keinen Ordner `kong-stack` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `kong-stack` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `kong-stack`. Rufen Sie anschließend das Tool `build` mit `workspace_root` auf `kong-stack`, `release` auf `release-helm-synth.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Nennen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `kong-stack/dist/`.

Wie der zusammengesetzte Stack aussieht

Das Gateway wird als zustandsloses Deployment plus ein ClusterIP-Service auf dem Proxy-Port und eine ConfigMap gerendert, die die Request-Allowlist seiner Status API trägt. Sein Pod trägt einen Migrations-Init-Container, der vor dem Hauptcontainer läuft; beide tragen die aus der Backend-Kante zusammengesetzte Verbindung — den clusterinternen Service-Namen des Backends, Benutzer und Datenbank:

env:
- name: KONG_DATABASE
value: postgres
- name: KONG_PG_HOST
value: gateway-zdbackend-default
- name: KONG_PG_PORT
value: "5432"
- name: KONG_PG_USER
value: kong
- name: KONG_PG_DATABASE
value: kong
[… omitted: the gateway's own proxy, admin and status listen addresses, and
the allowlist file its Status API includes]
- name: KONG_PG_PASSWORD
value: apppass

Die Readiness- und die Liveness-Probe des Gateways fragen die Status API von Kong ab — GET /status/ready und GET /status — auf dem Container-Port status, daher lauscht dieser Listener auf der Adresse des Pods. Kong bindet die Allowlist aus der ConfigMap in den eigenen Server-Block der Status API ein: Von jeder Adresse außer der Loopback-Adresse des Pods beantwortet es ein GET auf /status, /status/ready oder /metrics und weist jede andere Anfrage mit 403 zurück — darunter POST /status/ready, das das Gateway andernfalls in den Drain-Zustand versetzen und es bis zu seinem Neustart aus seinem Service nehmen würde.

Das Backend wird als StatefulSet mit einem persistenten Volume gerendert, das unter /var/lib/postgresql/data eingehängt ist, plus ein ClusterIP-Service und ein Headless-Service.