Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Stack de Keycloak — un servidor de identidad respaldado por una base de datos compuesto como módulo

Este ejemplo compila un stack pequeño y real — un servidor de identidad respaldado por una base de datos — a manifiestos de Kubernetes sintetizados a partir de un único Aggregate escrito por el desarrollador.

El servidor de identidad no es un componente único. Es un módulo: un subagregado reutilizable que compone dos componentes de una sola carga de trabajo —

  • un servidor que sirve la consola de cuenta y los endpoints de tokens en su puerto HTTP y no guarda estado local, y
  • un backend, PostgreSQL, que guarda los realms, los clientes y los usuarios del servidor y los persiste en un volumen.

El módulo conecta su propia arista interna del servidor al backend y exporta el servidor como su endpoint público http. El Aggregate de nivel superior importa el módulo por nombre y renderiza el stack compuesto; el operador dimensiona los componentes internos del módulo en la Release.

Archivos

ArchivoRol
aggregate.yamlIntención del desarrollador: importa el módulo de servidor de identidad (core/keycloak).
manifest-helm-synth.yamlAsigna los tipos servidor y backend a sus Recipes helm synth, y la Feature de credencial que vincula el módulo, a la realización que emite un Secret a partir de los parámetros de credencial del módulo.
release-helm-synth.yamlDocumento del operador para el destino Kubernetes. Dimensiona los componentes internos del módulo por sus ID con ámbito de módulo; todo lo que queda en los valores predeterminados del esquema se renderiza de forma autónoma.

Lo que demuestra

  • Composición como módulo. Una capacidad de varias cargas de trabajo — un servidor de identidad que en realidad es un servidor más una base de datos de configuración — se empaqueta como un subagregado que compone dos componentes de una sola carga de trabajo, no como un único componente monolítico. El módulo se importa por nombre y se reutiliza dondequiera que se necesite un servidor de identidad.
  • Una arista interna dentro del módulo. El servidor declara un uso del backend; el host, el puerto, el usuario y la base de datos de los provides de la Recipe del backend se canalizan al servidor y se componen en su conexión a la base de datos. El compilador enruta las cadenas sin interpretarlas.
  • Un endpoint público. El módulo exporta su servidor como http, el nombre público estable al que se conecta un consumidor — desacoplado de los nombres de los componentes internos del módulo.
  • Dimensionamiento de los componentes internos por parte del operador. La Release se dirige a los componentes internos del módulo por sus ID con ámbito de módulo (server.backend, server.server) para establecer el cómputo, sin que el Aggregate del desarrollador repita el dimensionamiento físico.
  • Esquema con migración propia. Al arrancar, el servidor aprovisiona y migra su propio esquema contra el backend, así que arranca con un esquema listo sin ningún paso de migración aparte.
  • Una credencial compartida, tomada por referencia. El servidor se autentica ante su backend PostgreSQL, así que los dos comparten una única contraseña. El módulo la toma como parámetro, db_password, y vincula con ella dos veces la Feature de credencial core/referenced-secret: al slot de credencial propio del backend, y como credential de la conexión del servidor al backend, la conexión en la que el servidor la presenta. Cada carga de trabajo lee la contraseña de un Secret en lugar de llevarla en línea; la contraseña de la cuenta de administrador de arranque es un segundo parámetro, admin_password. Como el módulo vincula esa Feature, el Manifest la asigna. Este ejemplo deja ambos parámetros en los valores predeterminados de desarrollo del módulo y asigna la Feature a k8s-secret-from-parameter, que emite un Secret que lleva cada valor, así que el stack se ejecuta de forma autónoma. Para una Release que lleva tráfico real, el Aggregate declara parámetros propios y los transmite hacia abajo mediante aggregates.server.parameters, la Release los cumple, y el Manifest asigna la Feature a k8s-existing-secret, que lee cada parámetro como el nombre de un Secret que ya existe en el namespace.
  • Imágenes reproducibles. Tanto el servidor como el backend fijan tags de imagen explícitos, así que los manifiestos renderizados hacen referencia a imágenes estables.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example keycloak-stack

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd keycloak-stack

Compilación

Este workspace no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo; --auto-pull escribe durante la compilación el lockfile que le falta a un clon recién creado:

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

Los artefactos renderizados quedan en dist/. El destino Kubernetes renderiza manifiestos simples sin conexión — no se requiere ningún pull de chart.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `keycloak-stack`, llama una vez a la herramienta `scaffold` con `example` establecido en `keycloak-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `keycloak-stack`. Después llama a la herramienta `build` con `workspace_root` establecido en `keycloak-stack`, `release` establecido en `release-helm-synth.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `keycloak-stack/dist/`.

Cómo es el stack compuesto

El servidor se renderiza como un Deployment sin estado más un Service ClusterIP en el puerto HTTP. Su contenedor lleva la conexión compuesta a partir de la arista hacia el backend — el nombre del Service interno del clúster del backend, el usuario y la base de datos — además de la configuración HTTP para el funcionamiento autónomo, los endpoints de salud activados y servidos en el puerto de administración, y la cuenta de administrador de arranque, con ambas contraseñas leídas de 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: admin

El contenedor declara el puerto de administración, 9000, junto al puerto HTTP, y el Deployment sondea el servidor allí: una sonda de startup en /health/started retiene las demás mientras el servidor arranca, una sonda de readiness en /health/ready mantiene el tráfico alejado hasta que responde, y una sonda de liveness en /health/live lo reinicia si se detiene. El Service sigue reenviando solo el puerto HTTP.

El backend se renderiza como un StatefulSet con un volumen persistente montado en /var/lib/postgresql/data, más un Service ClusterIP y un Service headless. Su POSTGRES_PASSWORD lee la misma contraseña de la base de datos de un Secret propio, server-zdbackend-password. Los tres Secrets se emiten junto a las cargas de trabajo, uno por cada credencial que vincula el módulo, y cada uno lleva el valor predeterminado de desarrollo del módulo.