Gateway NGINX — enrutamiento de proxy inverso hacia un upstream, dos destinos
Este ejemplo compila un stack pequeño y real — un gateway de proxy inverso NGINX delante de un backend web — a partir de un único Aggregate escrito por el desarrollador para dos destinos:
- Docker Compose para el desarrollo local, y
- manifiestos de Kubernetes sintetizados para un clúster.
El mismo aggregate.yaml impulsa ambos. Solo cambia por destino la capa de Recipe que selecciona el Manifest.
Archivos
| Archivo | Rol |
|---|---|
aggregate.yaml | Intención del desarrollador: un backend web (core/devtool/adminer) y un gateway proxy (core/gateway/nginx) que declara un uso upstream del backend. |
manifest-compose.yaml | Asigna el tipo del gateway a la Recipe de Compose (compose/nginx) y el backend a la Recipe de Compose de Adminer. |
manifest-helm-synth.yaml | Asigna el tipo del gateway a la Recipe helm synth (helm/nginx) y el backend a la Recipe helm sin conexión de Adminer. |
release-compose.yaml / release-helm-synth.yaml | Documentos del operador para los dos destinos. |
Lo que demuestra
- Una única superficie de autoría, muchos destinos. Un único Aggregate es la fuente de verdad sobre qué es el stack. Cada Manifest dice cómo realizarlo.
- Enrutamiento upstream a través del String Pipe. El gateway declara un uso
upstreamdel backend; losprovides.hostyprovides.portde la Recipe del backend se canalizan al gateway y se renderizan en el destino de suproxy_pass. El compilador enruta las cadenas sin interpretarlas — así, la compilación de Compose conecta un nombre de servicio de compose y la compilación de Kubernetes conecta un nombre de Service, a partir de la misma arista. - Configuración idiomática del Provider. En ambos destinos el gateway escribe, al iniciarse el contenedor, un bloque server mínimo de NGINX cuyo
proxy_passreenvía al upstream inyectado, y luego inicia nginx en primer plano. El destino Kubernetes lo realiza como un Deployment sin estado más un Service ClusterIP, sin ningún chart de Helm externo. - Imágenes reproducibles. El destino Kubernetes ejecuta la imagen upstream oficial de nginx fijada a un tag explícito, así que el Deployment renderizado hace referencia a una imagen estable.
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 nginx-gatewayDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd nginx-gatewayCompilació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:
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)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 ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `nginx-gateway`, llama una vez a la herramienta `scaffold` con `example` establecido en `nginx-gateway` y sin `dir`: escribe el ejemplo en una nueva carpeta `nginx-gateway`. Luego llama a la herramienta `build` una vez por cada Release, en este orden — `release-compose.yaml` y `release-helm-synth.yaml` — cada vez con `workspace_root` establecido en `nginx-gateway`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `nginx-gateway/dist/`.Cómo es el upstream inyectado
En Compose, el servicio del gateway ejecuta NGINX con un bloque server que apunta al nombre de servicio de compose y al puerto del backend:
server { listen 8000; location / { proxy_pass http://web:8080; } }En Kubernetes, el mismo enrutamiento llega en el comando del contenedor que escribe la configuración del servidor antes de iniciar nginx, apuntando al Service del backend — el proveedor helm lo nombra a partir del backend y de su clave de servicio default:
server { listen 8080; location / { proxy_pass http://web-default:8080; } }Ambos se derivan de la misma arista del Aggregate — el host y el puerto del backend viajan a través del uso upstream, y cada destino los renderiza en su propio idioma.
Ejecutarlo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dAbre http://localhost:8000 — NGINX reenvía la solicitud al backend. Para desmontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down.