Stack Kong — um gateway de API apoiado numa base de dados composto como módulo
Este exemplo compila uma stack pequena e real — um gateway de API apoiado numa base de dados — em manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo programador.
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 guarda estado local, e
- um backend, PostgreSQL, que guarda a configuração do gateway e a persiste num 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 superior importa o módulo pelo nome e renderiza a stack composta; o operador dimensiona os componentes internos do módulo na Release.
Ficheiros
| Ficheiro | Papel |
|---|---|
aggregate.yaml | Intenção do programador: 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 âmbito de módulo; tudo o que fica com as predefinições do esquema é renderizado de forma autónoma. |
O que demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um gateway de API que na realidade é um proxy mais uma base de dados de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, e não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que seja necessário um gateway.
- Uma aresta interna dentro do módulo. O gateway declara um uso do backend; o host, a porta, o utilizador e a base de dados dos
providesda Recipe do backend são encaminhados para o gateway e compostos na sua ligação ao PostgreSQL. O compilador encaminha as strings sem as interpretar. - Um endpoint público. O módulo exporta o seu gateway como
proxy, o nome público estável ao qual um consumidor se liga — 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 âmbito de módulo (
gateway.backend,gateway.gateway) para definir os recursos de computação, sem que o Aggregate do programador repita o dimensionamento físico. - Um passo de migrações executado antes de servir. O gateway aprovisiona o esquema da sua base de dados através de um contentor de inicialização que é executado até ao fim antes de o contentor principal do gateway arrancar, pelo que o gateway serve com um esquema pronto. O bootstrap é idempotente, pelo que uma nova execução sobre uma base de dados já aprovisionada não tem qualquer efeito.
- Uma credencial partilhada. O gateway autentica-se no seu backend PostgreSQL, pelo que os dois partilham uma única palavra-passe. Este exemplo usa um valor predefinido de desenvolvimento partilhado e escrito inline, pelo que a stack é executada de forma autónoma, sem nenhum segredo externo.
- Imagens reproduzíveis. Tanto o gateway como o backend fixam tags de imagem explícitas, pelo que os manifestos renderizados referenciam imagens estáveis.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example kong-stackDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd kong-stackCompilação
Este workspace não contém nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo; --auto-pull escreve durante a compilação o lockfile que falta a um clone acabado de criar:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefactos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — não é necessário nenhum pull de chart.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta da área de trabalho ainda não contiver uma pasta `kong-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `kong-stack` e sem `dir`: esta escreve o exemplo numa nova pasta `kong-stack`. Em seguida, 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. Indique quais os ficheiros que a compilação escreveu; encontram-se em `kong-stack/dist/`.Como é a stack composta
O gateway é renderizado como um Deployment sem estado mais um Service ClusterIP na porta de proxy e um ConfigMap que contém a lista de permissões de pedidos da sua Status API. O seu Pod contém um contentor de inicialização de migrações que é executado antes do contentor principal; ambos contêm a ligação composta a partir da aresta para o backend — o nome do Service interno ao cluster do backend, o utilizador e a base 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 contentor status, pelo que 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, responde a um GET de /status, /status/ready ou /metrics, e recusa qualquer outro pedido com 403 — entre eles POST /status/ready, que de outro modo marcaria o gateway como em drenagem e o retiraria do seu Service até que 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.