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

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

DateiRolle
aggregate.yamlEntwicklerabsicht: importiert das API-Gateway-Modul (core/apisix) und übergibt ihm den Admin-API-Schlüssel des Gateways aus einem eigenen Parameter.
manifest-helm-synth.yamlOrdnet 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.yamlBetreiber-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 provides des 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-Feature core/referenced-secret an 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 Feature k8s-existing-secret zu, 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:

Terminal window
aggrega scaffold --example apisix-stack

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

Terminal window
cd apisix-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.

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: 9080
deployment:
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: 30

Das 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-key

Der Store wird als StatefulSet mit einem persistenten Volume gerendert, das unter /etcd-data eingehängt ist, plus ein ClusterIP-Service und ein Headless-Service.