Stack Keycloak — un server di identità basato su database composto come modulo
Questo esempio compila uno stack piccolo e reale — un server di identità basato su database — in manifest Kubernetes sintetizzati a partire da un unico Aggregate scritto dallo sviluppatore.
Il server di identità non è un singolo componente. È un modulo: un sotto-aggregato riutilizzabile che compone due componenti a carico di lavoro singolo —
- un server che serve la console dell’account e gli endpoint dei token sulla sua porta HTTP e non mantiene alcuno stato locale, e
- un backend, PostgreSQL, che contiene i realm, i client e gli utenti del server e li rende persistenti su un volume.
Il modulo cabla il proprio arco interno dal server al backend ed esporta il server come suo endpoint pubblico http. L’Aggregate di primo livello importa il modulo per nome e renderizza lo stack composto; l’operatore dimensiona i componenti interni del modulo nella Release.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: importa il modulo di server di identità (core/keycloak). |
manifest-helm-synth.yaml | Mappa i tipi server e backend alle rispettive Recipes helm synth, e la Feature di credenziale che il modulo associa alla realizzazione che emette un Secret dai parametri di credenziale del modulo. |
release-helm-synth.yaml | Documento dell’operatore per il target Kubernetes. Dimensiona i componenti interni del modulo tramite i loro ID con ambito di modulo; tutto ciò che è lasciato ai valori predefiniti dello schema viene renderizzato in modo autonomo. |
Che cosa dimostra
- Composizione come modulo. Una capacità a più carichi di lavoro — un server di identità che in realtà è un server più un database di configurazione — è confezionata come un sotto-aggregato che compone due componenti a carico di lavoro singolo, non come un unico componente monolitico. Il modulo viene importato per nome e riutilizzato ovunque serva un server di identità.
- Un arco interno al modulo. Il server dichiara un uso del backend; host, porta, utente e database dei
providesdella Recipe del backend vengono convogliati nel server e composti nella sua connessione al database. Il compilatore instrada le stringhe senza interpretarle. - Un endpoint pubblico. Il modulo esporta il suo server come
http, il nome pubblico stabile a cui si connette un consumatore — disaccoppiato dai nomi dei componenti interni del modulo. - Dimensionamento dei componenti interni da parte dell’operatore. La Release indirizza i componenti interni del modulo tramite i loro ID con ambito di modulo (
server.backend,server.server) per impostarne le risorse di calcolo, senza che l’Aggregate dello sviluppatore ripeta il dimensionamento fisico. - Schema con migrazione automatica. All’avvio il server effettua il provisioning e la migrazione del proprio schema sul backend, così parte su uno schema pronto senza alcuno step di migrazione separato.
- Una credenziale condivisa, presa per riferimento. Il server si autentica presso il suo backend PostgreSQL, quindi i due condividono un’unica password. Il modulo la riceve come parametro,
db_password, e con essa associa due volte la Feature di credenzialecore/referenced-secret: allo slot di credenziale del backend stesso, e comecredentialdella connessione del server al backend, la connessione su cui il server la presenta. Ogni carico di lavoro legge la password da un Secret anziché contenerla inline; la password dell’account amministratore di bootstrap è un secondo parametro,admin_password. Poiché il modulo associa quella Feature, il Manifest la mappa. Questo esempio lascia entrambi i parametri ai valori predefiniti di sviluppo del modulo e mappa la Feature suk8s-secret-from-parameter, che emette un Secret che contiene ciascun valore, così lo stack funziona in modo autonomo. Per una Release che gestisce traffico reale, l’Aggregate dichiara propri parametri e li passa verso il basso tramiteaggregates.server.parameters, la Release li soddisfa e il Manifest mappa la Feature suk8s-existing-secret, che legge ciascun parametro come il nome di un Secret che esiste già nel namespace. - Immagini riproducibili. Sia il server sia il backend fissano tag di immagine espliciti, quindi i manifest renderizzati fanno riferimento a immagini stabili.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example keycloak-stackPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd keycloak-stackBuild
Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard vengono risolte dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo; --auto-pull scrive durante il build il lockfile che manca a un clone appena creato:
aggrega build --release release-helm-synth.yaml --auto-pullGli artefatti renderizzati finiscono sotto dist/. Il target Kubernetes renderizza manifest semplici offline — non è richiesto alcun pull di chart.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `keycloak-stack`, chiama una volta lo strumento `scaffold` con `example` impostato su `keycloak-stack` e senza `dir`: scrive l’esempio in una nuova cartella `keycloak-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato su `keycloak-stack`, `release` impostato su `release-helm-synth.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `keycloak-stack/dist/`.Come appare lo stack composto
Il server viene renderizzato come un Deployment stateless più un Service ClusterIP sulla porta HTTP. Il suo container porta la connessione composta dall’arco verso il backend — il nome del Service interno al cluster del backend, l’utente e il database — più le impostazioni HTTP per il funzionamento autonomo, gli endpoint di health attivati e serviti sulla porta di gestione, e l’account amministratore di bootstrap, con entrambe le password lette da Secret:
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: adminIl container dichiara la porta di gestione, 9000, accanto alla porta HTTP, e il Deployment sonda il server lì: una startup probe su /health/started trattiene le altre mentre il server si avvia, una readiness probe su /health/ready tiene lontano il traffico finché non risponde, e una liveness probe su /health/live lo riavvia se si ferma. Il Service continua a inoltrare solo la porta HTTP.
Il backend viene renderizzato come uno StatefulSet con un volume persistente montato in /var/lib/postgresql/data, più un Service ClusterIP e un Service headless. Il suo POSTGRES_PASSWORD legge la stessa password del database da un proprio Secret, server-zdbackend-password. I tre Secret vengono emessi accanto ai carichi di lavoro, uno per ogni credenziale che il modulo associa, ciascuno con il valore predefinito di sviluppo del modulo.