Stack de Kong — un gateway de API respaldado por una base de datos compuesto como módulo
Este ejemplo compila un stack pequeño y real — un gateway de API respaldado por una base de datos — a manifiestos de Kubernetes sintetizados a partir de un único Aggregate escrito por el desarrollador.
El gateway no es un componente único. Es un módulo: un subagregado reutilizable que compone dos componentes de una sola carga de trabajo —
- un gateway que termina el tráfico de los clientes en su puerto de proxy y no guarda estado local, y
- un backend, PostgreSQL, que guarda la configuración del gateway y la persiste en un volumen.
El módulo conecta su propia arista interna del gateway al backend y exporta el gateway como su endpoint público proxy. 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
| Archivo | Rol |
|---|---|
aggregate.yaml | Intención del desarrollador: importa el módulo de gateway de API (core/kong). |
manifest-helm-synth.yaml | Asigna los tipos gateway y backend a sus Recipes helm synth. |
release-helm-synth.yaml | Documento 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 gateway de API que en realidad es un proxy 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 gateway.
- Una arista interna dentro del módulo. El gateway declara un uso del backend; el host, el puerto, el usuario y la base de datos de los
providesde la Recipe del backend se canalizan al gateway y se componen en su conexión a PostgreSQL. El compilador enruta las cadenas sin interpretarlas. - Un endpoint público. El módulo exporta su gateway como
proxy, 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 (
gateway.backend,gateway.gateway) para establecer el cómputo, sin que el Aggregate del desarrollador repita el dimensionamiento físico. - Un paso de migraciones que se ejecuta antes de servir. El gateway aprovisiona el esquema de su base de datos mediante un contenedor de inicialización que se ejecuta hasta completarse antes de que arranque el contenedor principal del gateway, así que el gateway sirve con un esquema listo. El bootstrap es idempotente, así que volver a ejecutarlo contra una base de datos ya aprovisionada no tiene ningún efecto.
- Una credencial compartida. El gateway se autentica ante su backend PostgreSQL, así que los dos comparten una única contraseña. Este ejemplo usa un valor predeterminado de desarrollo compartido y escrito en línea, así que el stack se ejecuta de forma autónoma sin ningún secreto externo.
- Imágenes reproducibles. Tanto el gateway 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:
aggrega scaffold --example kong-stackDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd kong-stackCompilació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:
aggrega build --release release-helm-synth.yaml --auto-pullLos 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 `kong-stack`, llama una vez a la herramienta `scaffold` con `example` establecido en `kong-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `kong-stack`. Después llama a la herramienta `build` con `workspace_root` establecido en `kong-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 `kong-stack/dist/`.Cómo es el stack compuesto
El gateway se renderiza como un Deployment sin estado más un Service ClusterIP en el puerto de proxy y un ConfigMap que lleva la lista de permitidos de solicitudes de su Status API. Su Pod lleva un contenedor de inicialización de migraciones que se ejecuta antes del contenedor principal; ambos llevan 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:
env: - name: KONG_DATABASE value: postgres - name: KONG_PG_HOST value: gateway-zdbackend-default - name: KONG_PG_PORT value: "5432" - name: KONG_PG_USER value: kong - name: KONG_PG_DATABASE value: kong [… omitted: the gateway's own proxy, admin and status listen addresses, and the allowlist file its Status API includes] - name: KONG_PG_PASSWORD value: apppassLas sondas de readiness y de liveness del gateway consultan la Status API de Kong — GET /status/ready y GET /status — en el puerto de contenedor status, así que ese listener escucha en la dirección del Pod. Kong incluye la lista de permitidos del ConfigMap en el propio bloque server de la Status API: desde cualquier dirección salvo la de loopback del Pod responde a un GET de /status, /status/ready o /metrics, y rechaza cualquier otra solicitud con 403 — entre ellas POST /status/ready, que de lo contrario marcaría el gateway como en drenaje y lo sacaría de su Service hasta que se reinicie.
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.