APISIX-Stack — ein dynamisches API-Gateway, als Modul zusammengesetzt
Dieses Beispiel kompiliert einen kleinen, realen Stack — ein dynamisches 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
- einen Store, etcd, der die Konfiguration des Gateways hält und sie auf einem Volume persistiert.
Das Modul verdrahtet seine eigene interne Kante vom Gateway zum Store 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
| Datei | Rolle |
|---|---|
aggregate.yaml | Entwicklerabsicht: importiert das API-Gateway-Modul (core/apisix) und übergibt ihm den Admin-API-Schlüssel des Gateways aus einem eigenen Parameter. |
manifest-helm-synth.yaml | Ordnet die Typen Gateway und Store ihren synth-helm-Recipes zu und das Zugangsdaten-Feature, das das Modul anbindet, der Realisierung, die ein bereits im Namespace vorhandenes Secret liest. |
release-helm-synth.yaml | Betreiber-Datensatz für das Kubernetes-Ziel. Nennt das Secret, das den Admin-API-Schlüssel enthält, und dimensioniert die internen Komponenten des Moduls über ihre modulbezogenen IDs; alles andere bleibt den Schema-Voreinstellungen überlassen. |
Was es zeigt
- Komposition als Modul. Eine Fähigkeit aus mehreren Arbeitslasten — ein API-Gateway, das eigentlich ein Proxy plus ein Konfigurations-Store 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 Store; Host und Port aus den
providesdes Store-Recipe werden in das Gateway durchgereicht und zu seiner etcd-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.store,gateway.gateway), um Rechenressourcen festzulegen, ohne dass das Aggregate des Entwicklers die physische Dimensionierung wiederholt. - Eine Konfigurationsdatei, eingehängt neben zur Laufzeit geschriebenen Dateien. Das Gateway liest seine Konfiguration aus einer Datei in einem Verzeichnis, in das es beim Start auch schreibt. Das Recipe gibt diese Konfiguration als ConfigMap aus und hängt sie als einzelne Datei ein, sodass sie das Gateway konfiguriert, ohne die Dateien zu verdecken, die das Gateway dort schreibt.
- Ein Admin-API-Schlüssel, aus einem Secret gelesen. Das Gateway verwaltet seine Routen über eine Admin API, und sein Schlüssel kommt über einen Zugangsdaten-Slot am Gateway an, den das Gateway verlangt, solange nichts mit seinem Modell-Socket verdrahtet ist, wie hier, sodass kein Standardschlüssel existiert. Das Modul nimmt den Schlüssel als Parameter entgegen,
admin_key, und bindet damit das Zugangsdaten-Featurecore/referenced-secretan den Slot an; dieses Aggregate deklariert einen eigenen Parameter und reicht ihn nach unten weiter, und das Release erfüllt ihn. Das Manifest ordnet das Featurek8s-existing-secretzu, daher ist der Wert der Name eines Secret, das bereits im Namespace existiert: Der Build liest keinen Schlüssel und rendert keinen, und das Gateway liest den Schlüssel beim Start aus diesem Secret. Ein Release, das keinen Wert liefert, bricht den Build ab und nennt dabei den Parameter. - Reproduzierbare Images. Sowohl das Gateway als auch der Store 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:
aggrega scaffold --example apisix-stackDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd apisix-stackBuild
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:
aggrega build --release release-helm-synth.yaml --auto-pullGerenderte Artefakte landen unter dist/. Das Kubernetes-Ziel rendert einfache Manifeste offline — es ist kein Chart-Pull erforderlich.
Bevor Sie sie anwenden, legen Sie im Ziel-Namespace das Secret an, das das Release nennt, apisix-admin-key, mit einem eigenen Schlüssel unter dem Datenschlüssel admin-key. Der Schlüssel darf nicht leer sein, was das Gateway beim Start anhält, und darf kein Wert sein, den APISIX als Zahl oder als wahr oder falsch liest, etwa ein Schlüssel nur aus Ziffern, denn APISIX gleicht ihn dann nie mit dem Schlüssel ab, den eine Anfrage vorlegt.
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 nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `apisix-stack` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `apisix-stack` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `apisix-stack`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `apisix-stack`, `release` auf `release-helm-synth.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `apisix-stack/dist/`.Wie der zusammengesetzte Stack aussieht
Das Gateway wird als zustandsloses Deployment plus ein ClusterIP-Service auf dem Proxy-Port gerendert. Seine Konfiguration wird als ConfigMap geliefert, die als einzelne Datei in das conf-Verzeichnis des Containers eingehängt wird; die Konfiguration trägt den clusterinternen Service-Namen des Store und, dort wo der Admin-API-Schlüssel hingehört, den Namen der Umgebungsvariablen, aus der APISIX den Schlüssel liest, wenn es die Datei lädt:
apisix: node_listen: 9080deployment: role: traditional role_traditional: config_provider: etcd admin: [… omitted: the client range the Admin API accepts] admin_key: - name: admin key: ${{APISIX_ADMIN_KEY}} role: admin admin_listen: ip: 0.0.0.0 port: 9180 etcd: host: - "http://gateway-zdstore-default:2379" prefix: "/apisix" timeout: 30Das Deployment liefert diese Variable aus dem Secret, daher erscheint der Schlüssel in keiner gerenderten Datei:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-keyDer Store wird als StatefulSet mit einem persistenten Volume gerendert, das unter /etcd-data eingehängt ist, plus ein ClusterIP-Service und ein Headless-Service.