Stack Kong — um gateway de API apoiado em banco de dados composto como módulo
Este exemplo compila um stack pequeno e real — um gateway de API apoiado em banco de dados — para manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo desenvolvedor.
O gateway não é um único componente. É um módulo: um subagregado reutilizável que compõe dois componentes de carga de trabalho única —
- um gateway que termina o tráfego dos clientes na sua porta de proxy e não mantém estado local, e
- um backend, PostgreSQL, que guarda a configuração do gateway e a persiste em um volume.
O módulo liga a sua própria aresta interna do gateway ao backend e exporta o gateway como o seu endpoint público proxy. O Aggregate de nível mais alto importa o módulo pelo nome e renderiza o stack composto; o operador dimensiona os componentes internos do módulo na Release.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: importa o módulo de gateway de API (core/kong). |
manifest-helm-synth.yaml | Mapeia os tipos gateway e backend para as suas Recipes helm synth. |
release-helm-synth.yaml | Documento do operador para o destino Kubernetes. Dimensiona os componentes internos do módulo pelos seus IDs com escopo de módulo; tudo o que fica com os valores padrão do esquema é renderizado de forma autônoma. |
O que ele demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um gateway de API que na verdade é um proxy mais um banco de dados de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que um gateway seja necessário.
- Uma aresta interna dentro do módulo. O gateway declara um uso do backend; o host, a porta, o usuário e o banco de dados dos
providesda Recipe do backend são canalizados para o gateway e compostos na sua conexão com o PostgreSQL. O compilador roteia as strings sem interpretá-las. - Um endpoint público. O módulo exporta o seu gateway como
proxy, o nome público estável ao qual um consumidor se conecta — desacoplado dos nomes dos componentes internos do módulo. - Dimensionamento dos componentes internos pelo operador. A Release endereça os componentes internos do módulo pelos seus IDs com escopo de módulo (
gateway.backend,gateway.gateway) para definir os recursos de computação, sem que o Aggregate do desenvolvedor repita o dimensionamento físico. - Uma etapa de migrações executada antes de servir. O gateway provisiona o esquema do seu banco de dados por meio de um contêiner de inicialização que é executado até a conclusão antes que o contêiner principal do gateway inicie, então o gateway serve com um esquema pronto. O bootstrap é idempotente, então uma nova execução em um banco de dados já provisionado não tem efeito.
- Uma credencial compartilhada. O gateway se autentica no seu backend PostgreSQL, então os dois compartilham uma única senha. Este exemplo usa um valor padrão de desenvolvimento compartilhado e escrito inline, então o stack é executado de forma autônoma, sem nenhum segredo externo.
- Imagens reproduzíveis. Tanto o gateway quanto o backend fixam tags de imagem explícitas, então os manifestos renderizados referenciam imagens estáveis.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example kong-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd kong-stackBuild
Este workspace não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária; --auto-pull escreve durante o build o lockfile que falta a um clone novo:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefatos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — nenhum pull de chart é necessário.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `kong-stack`, chame a ferramenta `scaffold` uma vez com `example` definido como `kong-stack` e sem `dir`: ela grava o exemplo em uma nova pasta `kong-stack`. Depois chame a ferramenta `build` com `workspace_root` definido como `kong-stack`, `release` definido como `release-helm-synth.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `kong-stack/dist/`.Como fica o stack composto
O gateway é renderizado como um Deployment sem estado mais um Service ClusterIP na porta de proxy e um ConfigMap que traz a lista de permissões de requisições da sua Status API. O seu Pod traz um contêiner de inicialização de migrações que é executado antes do contêiner principal; ambos trazem a conexão composta a partir da aresta para o backend — o nome do Service interno ao cluster do backend, o usuário e o banco de dados:
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: apppassAs probes de readiness e de liveness do gateway consultam a Status API do Kong — GET /status/ready e GET /status — na porta de contêiner status, então esse listener escuta no endereço do Pod. O Kong inclui a lista de permissões do ConfigMap no próprio bloco server da Status API: a partir de qualquer endereço que não seja o de loopback do Pod, ele responde a um GET de /status, /status/ready ou /metrics, e recusa qualquer outra requisição com 403 — entre elas POST /status/ready, que de outra forma marcaria o gateway como em drenagem e o tiraria do seu Service até que ele reinicie.
O backend é renderizado como um StatefulSet com um volume persistente montado em /var/lib/postgresql/data, mais um Service ClusterIP e um Service headless.