Gateway NGINX — roteamento de proxy reverso para um upstream, dois destinos
Este exemplo compila um stack pequeno e real — um gateway de proxy reverso NGINX na frente de um backend web — a partir de um único Aggregate escrito pelo desenvolvedor para dois destinos:
- Docker Compose para o desenvolvimento local, e
- manifestos do Kubernetes sintetizados para um cluster.
O mesmo aggregate.yaml conduz ambos. Só muda por destino a camada de Recipe selecionada pelo Manifest.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: um backend web (core/devtool/adminer) e um gateway proxy (core/gateway/nginx) que declara um uso upstream do backend. |
manifest-compose.yaml | Mapeia o tipo do gateway para a Recipe do Compose (compose/nginx) e o backend para a Recipe do Compose do Adminer. |
manifest-helm-synth.yaml | Mapeia o tipo do gateway para a Recipe helm synth (helm/nginx) e o backend para a Recipe helm offline do Adminer. |
release-compose.yaml / release-helm-synth.yaml | Documentos do operador para os dois destinos. |
O que ele demonstra
- Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte da verdade sobre o que o stack é. Cada Manifest diz como realizá-lo.
- Roteamento upstream através do String Pipe. O gateway declara um uso
upstreamdo backend; osprovides.hosteprovides.portda Recipe do backend são canalizados para o gateway e renderizados no destino do seuproxy_pass. O compilador roteia as strings sem interpretá-las — assim, o build do Compose liga um nome de serviço do compose e o build do Kubernetes liga um nome de Service, a partir da mesma aresta. - Configuração idiomática do Provider. Nos dois destinos, o gateway escreve, na inicialização do contêiner, um bloco server mínimo do NGINX cujo
proxy_passencaminha para o upstream injetado e, em seguida, inicia o nginx em primeiro plano. O destino Kubernetes realiza isso como um Deployment sem estado mais um Service ClusterIP, sem nenhum chart Helm externo. - Imagens reproduzíveis. O destino Kubernetes executa a imagem upstream oficial do nginx fixada em uma tag explícita, então o Deployment renderizado referencia uma imagem estável.
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 nginx-gatewayEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd nginx-gatewayBuild
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:
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)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 apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `nginx-gateway`, chame uma vez a ferramenta `scaffold` com `example` definido como `nginx-gateway` e sem `dir`: ela grava o exemplo em uma nova pasta `nginx-gateway`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-compose.yaml` e `release-helm-synth.yaml` — cada vez com `workspace_root` definido como `nginx-gateway`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `nginx-gateway/dist/`.Como fica o upstream injetado
No Compose, o serviço do gateway executa o NGINX com um bloco server que aponta para o nome de serviço do compose e para a porta do backend:
server { listen 8000; location / { proxy_pass http://web:8080; } }No Kubernetes, o mesmo roteamento chega no comando do contêiner que escreve a configuração do servidor antes de iniciar o nginx, apontando para o Service do backend — o provedor helm o nomeia a partir do backend e da sua chave de serviço default:
server { listen 8080; location / { proxy_pass http://web-default:8080; } }Ambos derivam da mesma aresta do Aggregate — o host e a porta do backend trafegam pelo uso upstream, e cada destino os renderiza no seu próprio idioma.
Executá-lo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dAbra http://localhost:8000 — o NGINX encaminha a requisição para o backend. Para desmontar, use docker compose -f dist/app/compose/docker-compose.yaml down.