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

Keycloak-Stack — ein datenbankgestützter Identitätsserver, als Modul zusammengesetzt

Dieses Beispiel kompiliert einen kleinen, realen Stack — einen datenbankgestützten Identitätsserver — aus einem einzigen vom Entwickler verfassten Aggregate zu synthetisierten Kubernetes-Manifesten.

Der Identitätsserver ist keine einzelne Komponente. Er ist ein Modul: ein wiederverwendbares Sub-Aggregat, das zwei Komponenten mit je einer einzigen Arbeitslast zusammensetzt —

  • ein Server, der die Account-Konsole und die Token-Endpunkte auf seinem HTTP-Port bereitstellt und keinen lokalen Zustand hält, und
  • ein Backend, PostgreSQL, das die Realms, Clients und Benutzer des Servers hält und sie auf einem Volume persistiert.

Das Modul verdrahtet seine eigene interne Kante vom Server zum Backend und exportiert den Server als seinen öffentlichen Endpunkt http. 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 Identitätsserver-Modul (core/keycloak).
manifest-helm-synth.yamlOrdnet die Typen Server und Backend ihren synth-helm-Recipes zu und das Zugangsdaten-Feature, das das Modul anbindet, der Realisierung, die aus den Zugangsdaten-Parametern des Moduls ein Secret ausgibt.
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 Identitätsserver, der eigentlich ein Server 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 Identitätsserver gebraucht wird.
  • Eine interne Kante innerhalb des Moduls. Der Server deklariert eine Nutzung des Backends; Host, Port, Benutzer und Datenbank aus den provides des Backend-Recipe werden in den Server durchgereicht und zu seiner Datenbankverbindung zusammengesetzt. Der Compiler leitet die Strings weiter, ohne sie zu interpretieren.
  • Ein öffentlicher Endpunkt. Das Modul exportiert seinen Server als http, 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 (server.backend, server.server), um Rechenressourcen festzulegen, ohne dass das Aggregate des Entwicklers die physische Dimensionierung wiederholt.
  • Selbstmigrierendes Schema. Der Server richtet beim Start sein eigenes Schema auf dem Backend ein und migriert es, sodass er gegen ein fertiges Schema startet, ohne separaten Migrationsschritt.
  • Gemeinsame Zugangsdaten, per Referenz übernommen. Der Server authentifiziert sich bei seinem PostgreSQL-Backend, daher teilen sich beide ein Passwort. Das Modul nimmt es als Parameter entgegen, db_password, und bindet damit das Zugangsdaten-Feature core/referenced-secret zweimal an: an den eigenen Zugangsdaten-Slot des Backends und als credential der Verbindung des Servers zum Backend, der Verbindung, über die der Server es vorlegt. Jede Arbeitslast liest das Passwort aus einem Secret, statt es inline zu tragen; das Passwort des Bootstrap-Administratorkontos ist ein zweiter Parameter, admin_password. Da das Modul dieses Feature anbindet, ordnet das Manifest es zu. Dieses Beispiel belässt beide Parameter auf den Entwicklungs-Voreinstellungen des Moduls und ordnet das Feature k8s-secret-from-parameter zu, das ein Secret mit jedem Wert ausgibt, sodass der Stack in sich geschlossen läuft. Für ein Release mit echtem Datenverkehr deklariert das Aggregate eigene Parameter und reicht sie über aggregates.server.parameters nach unten weiter, das Release erfüllt sie, und das Manifest ordnet das Feature k8s-existing-secret zu, das jeden Parameter als Namen eines Secret liest, das bereits im Namespace existiert.
  • Reproduzierbare Images. Sowohl der Server 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 keycloak-stack

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

Terminal window
cd keycloak-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 `keycloak-stack` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `keycloak-stack` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `keycloak-stack`. Rufen Sie anschließend das Tool `build` mit `workspace_root` auf `keycloak-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 `keycloak-stack/dist/`.

Wie der zusammengesetzte Stack aussieht

Der Server wird als zustandsloses Deployment plus ein ClusterIP-Service auf dem HTTP-Port gerendert. Sein Container trägt die aus der Backend-Kante zusammengesetzte Verbindung — den clusterinternen Service-Namen des Backends, Benutzer und Datenbank — sowie die HTTP-Einstellungen für den in sich geschlossenen Betrieb, die eingeschalteten und auf dem Management-Port bereitgestellten Health-Endpunkte und das Bootstrap-Administratorkonto, wobei beide Passwörter aus Secrets gelesen werden:

env:
- name: KC_DB_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-db.credential
key: db-password
- name: KC_BOOTSTRAP_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-admin-password
key: admin-password
- name: KC_DB
value: postgres
- name: KC_DB_URL_HOST
value: server-zdbackend-default
- name: KC_DB_URL_PORT
value: "5432"
- name: KC_DB_URL_DATABASE
value: keycloak
- name: KC_DB_USERNAME
value: keycloak
- name: KC_HTTP_ENABLED
value: "true"
- name: KC_HOSTNAME_STRICT
value: "false"
- name: KC_HEALTH_ENABLED
value: "true"
- name: KC_HTTP_MANAGEMENT_PORT
value: "9000"
- name: KC_BOOTSTRAP_ADMIN_USERNAME
value: admin

Der Container deklariert den Management-Port 9000 neben dem HTTP-Port, und das Deployment prüft den Server dort: Eine Startup-Probe auf /health/started hält die anderen zurück, während der Server hochfährt, eine Readiness-Probe auf /health/ready hält Datenverkehr fern, bis er antwortet, und eine Liveness-Probe auf /health/live startet ihn neu, wenn er anhält. Der Service leitet weiterhin nur den HTTP-Port weiter.

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. Sein POSTGRES_PASSWORD liest dasselbe Datenbankpasswort aus einem eigenen Secret, server-zdbackend-password. Die drei Secrets werden neben den Arbeitslasten ausgegeben, eines pro Zugangsdaten-Anbindung des Moduls, jedes mit der Entwicklungs-Voreinstellung des Moduls.