Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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

FileRuolo
aggregate.yamlIntento dello sviluppatore: importa il modulo di server di identità (core/keycloak).
manifest-helm-synth.yamlMappa 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.yamlDocumento 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 provides della 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 credenziale core/referenced-secret: allo slot di credenziale del backend stesso, e come credential della 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 su k8s-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 tramite aggregates.server.parameters, la Release li soddisfa e il Manifest mappa la Feature su k8s-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:

Terminal window
aggrega scaffold --example keycloak-stack

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd keycloak-stack

Build

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:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

Gli 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: admin

Il 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.