Stack Keycloak — un serveur d’identité adossé à une base de données composé comme un module
Cet exemple compile une petite stack réelle — un serveur d’identité adossé à une base de données — en manifestes Kubernetes synthétisés à partir d’un seul Aggregate écrit par le développeur.
Le serveur d’identité n’est pas un composant unique. C’est un module : un sous-agrégat réutilisable qui compose deux composants à charge de travail unique —
- un serveur qui sert la console de compte et les endpoints de jetons sur son port HTTP et ne conserve aucun état local, et
- un backend, PostgreSQL, qui contient les realms, les clients et les utilisateurs du serveur et les persiste sur un volume.
Le module câble sa propre arête interne du serveur vers le backend et exporte le serveur comme son endpoint public http. L’Aggregate de plus haut niveau importe le module par son nom et rend la stack composée ; l’opérateur dimensionne les composants internes du module dans la Release.
Fichiers
| Fichier | Rôle |
|---|---|
aggregate.yaml | Intention du développeur : importe le module de serveur d’identité (core/keycloak). |
manifest-helm-synth.yaml | Associe les types serveur et backend à leurs Recipes helm synth, et la Feature d’informations d’identification que le module rattache à la réalisation qui émet un Secret à partir des paramètres d’informations d’identification du module. |
release-helm-synth.yaml | Enregistrement de l’opérateur pour la cible Kubernetes. Dimensionne les composants internes du module par leurs ID à portée de module ; tout ce qui est laissé aux valeurs par défaut du schéma est rendu de manière autonome. |
Ce qu’il démontre
- Composition en module. Une capacité à plusieurs charges de travail — un serveur d’identité qui est en réalité un serveur plus une base de données de configuration — est empaquetée comme un sous-agrégat composant deux composants à charge de travail unique, et non comme un composant monolithique. Le module est importé par son nom et réutilisé partout où un serveur d’identité est nécessaire.
- Une arête interne au module. Le serveur déclare une utilisation du backend ; l’hôte, le port, l’utilisateur et la base de données des
providesde la Recipe du backend sont acheminés dans le serveur et composés en sa connexion à la base de données. Le compilateur achemine les chaînes sans les interpréter. - Un endpoint public. Le module exporte son serveur sous le nom
http, le nom public stable auquel un consommateur se connecte — découplé des noms des composants internes du module. - Dimensionnement des composants internes par l’opérateur. La Release adresse les composants internes du module par leurs ID à portée de module (
server.backend,server.server) pour définir les ressources de calcul, sans que l’Aggregate du développeur ne reprenne le dimensionnement physique. - Un schéma auto-migré. Au démarrage, le serveur provisionne et migre son propre schéma sur le backend, si bien qu’il démarre sur un schéma prêt, sans étape de migration distincte.
- Une information d’identification partagée, prise par référence. Le serveur s’authentifie auprès de son backend PostgreSQL, si bien que les deux partagent un seul mot de passe. Le module le reçoit comme paramètre,
db_password, et rattache avec lui deux fois la Feature d’informations d’identificationcore/referenced-secret: au slot d’informations d’identification propre au backend, et commecredentialde la connexion du serveur au backend, la connexion sur laquelle le serveur le présente. Chaque charge de travail lit le mot de passe depuis un Secret au lieu de le porter en ligne ; le mot de passe du compte administrateur d’amorçage est un second paramètre,admin_password. Comme le module rattache cette Feature, le Manifest la mappe. Cet exemple laisse les deux paramètres aux valeurs par défaut de développement du module et associe la Feature àk8s-secret-from-parameter, qui émet un Secret portant chaque valeur, si bien que la stack s’exécute de manière autonome. Pour une Release qui porte un trafic réel, l’Aggregate déclare des paramètres qui lui sont propres et les transmet vers le bas viaaggregates.server.parameters, la Release les remplit, et le Manifest associe la Feature àk8s-existing-secret, qui lit chaque paramètre comme le nom d’un Secret qui existe déjà dans le namespace. - Images reproductibles. Le serveur comme le backend épinglent des tags d’image explicites, si bien que les manifestes rendus référencent des images stables.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example keycloak-stackElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd keycloak-stackBuild
Ce workspace ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire ; --auto-pull écrit pendant le build le lockfile qui manque à un clone récent :
aggrega build --release release-helm-synth.yaml --auto-pullLes artefacts rendus atterrissent sous dist/. La cible Kubernetes rend des manifestes simples hors ligne — aucun pull de chart n’est requis.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `keycloak-stack`, appelez une fois l’outil `scaffold` avec `example` défini sur `keycloak-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `keycloak-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `keycloak-stack`, `release` défini sur `release-helm-synth.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `keycloak-stack/dist/`.À quoi ressemble la stack composée
Le serveur est rendu sous forme d’un Deployment sans état plus un Service ClusterIP sur le port HTTP. Son conteneur porte la connexion composée à partir de l’arête vers le backend — le nom du Service interne au cluster du backend, l’utilisateur et la base de données — ainsi que les paramètres HTTP pour un fonctionnement autonome, les endpoints de santé activés et servis sur le port de gestion, et le compte administrateur d’amorçage, les deux mots de passe étant lus depuis des Secrets :
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: adminLe conteneur déclare le port de gestion, 9000, à côté du port HTTP, et le Deployment sonde le serveur à cet endroit : une sonde de startup sur /health/started retient les autres pendant le démarrage du serveur, une sonde de readiness sur /health/ready tient le trafic à l’écart jusqu’à ce qu’il réponde, et une sonde de liveness sur /health/live le redémarre s’il s’arrête. Le Service ne transfère toujours que le port HTTP.
Le backend est rendu sous forme d’un StatefulSet avec un volume persistant monté sur /var/lib/postgresql/data, plus un Service ClusterIP et un Service headless. Son POSTGRES_PASSWORD lit le même mot de passe de base de données depuis un Secret qui lui est propre, server-zdbackend-password. Les trois Secrets sont émis à côté des charges de travail, un par information d’identification que rattache le module, chacun portant la valeur par défaut de développement du module.