Stack Kong — un API gateway basato su database composto come modulo
Questo esempio compila uno stack piccolo e reale — un API gateway basato su database — in manifest Kubernetes sintetizzati a partire da un unico Aggregate scritto dallo sviluppatore.
Il gateway non è un singolo componente. È un modulo: un sotto-aggregato riutilizzabile che compone due componenti a carico di lavoro singolo —
- un gateway che termina il traffico dei client sulla sua porta proxy e non mantiene alcuno stato locale, e
- un backend, PostgreSQL, che contiene la configurazione del gateway e la rende persistente su un volume.
Il modulo cabla il proprio arco interno dal gateway al backend ed esporta il gateway come suo endpoint pubblico proxy. 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 API gateway (core/kong). |
manifest-helm-synth.yaml | Mappa i tipi gateway e backend alle rispettive Recipes helm synth. |
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 API gateway che in realtà è un proxy 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 gateway.
- Un arco interno al modulo. Il gateway dichiara un uso del backend; host, porta, utente e database dei
providesdella Recipe del backend vengono convogliati nel gateway e composti nella sua connessione PostgreSQL. Il compilatore instrada le stringhe senza interpretarle. - Un endpoint pubblico. Il modulo esporta il suo gateway come
proxy, 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 (
gateway.backend,gateway.gateway) per impostarne le risorse di calcolo, senza che l’Aggregate dello sviluppatore ripeta il dimensionamento fisico. - Uno step di migrazione eseguito prima di servire. Il gateway effettua il provisioning dello schema del proprio database tramite un init container che viene eseguito fino al completamento prima che si avvii il container principale del gateway, così il gateway serve su uno schema pronto. Il bootstrap è idempotente, quindi una nuova esecuzione su un database già predisposto non ha alcun effetto.
- Una credenziale condivisa. Il gateway si autentica presso il suo backend PostgreSQL, quindi i due condividono un’unica password. Questo esempio usa un valore predefinito di sviluppo condiviso e scritto inline, così lo stack funziona in modo autonomo senza alcun segreto esterno.
- Immagini riproducibili. Sia il gateway 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 kong-stackPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd kong-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 `kong-stack`, chiama una volta lo strumento `scaffold` con `example` impostato su `kong-stack` e senza `dir`: scrive l’esempio in una nuova cartella `kong-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato su `kong-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 `kong-stack/dist/`.Come appare lo stack composto
Il gateway viene renderizzato come un Deployment stateless più un Service ClusterIP sulla porta proxy e una ConfigMap che contiene la allowlist delle richieste della sua Status API. Il suo Pod contiene un init container di migrazione che viene eseguito prima del container principale; entrambi portano la connessione composta dall’arco verso il backend — il nome del Service interno al cluster del backend, l’utente e il database:
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: apppassLe probe di readiness e di liveness del gateway interrogano la Status API di Kong — GET /status/ready e GET /status — sulla porta del container status, quindi quel listener è in ascolto sull’indirizzo del Pod. Kong include la allowlist della ConfigMap nel blocco server proprio della Status API: da qualsiasi indirizzo diverso da quello di loopback del Pod risponde a una GET di /status, /status/ready o /metrics, e rifiuta ogni altra richiesta con 403 — tra cui POST /status/ready, che altrimenti segnerebbe il gateway come in fase di drenaggio e lo toglierebbe dal suo Service fino al riavvio.
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.