Gateway NGINX — instradamento reverse proxy verso un upstream, due target
Questo esempio compila uno stack piccolo e reale — un gateway reverse proxy NGINX davanti a un backend web — a partire da un unico Aggregate scritto dallo sviluppatore per due target:
- Docker Compose per lo sviluppo locale, e
- manifest Kubernetes sintetizzati per un cluster.
Lo stesso aggregate.yaml guida entrambi. Per ogni target cambia solo il livello di Recipe selezionato dal Manifest.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: un backend web (core/devtool/adminer) e un gateway proxy (core/gateway/nginx) che dichiara un uso upstream del backend. |
manifest-compose.yaml | Mappa il tipo del gateway sulla Recipe Compose (compose/nginx) e il backend sulla Recipe Compose di Adminer. |
manifest-helm-synth.yaml | Mappa il tipo del gateway sulla Recipe helm synth (helm/nginx) e il backend sulla Recipe helm offline di Adminer. |
release-compose.yaml / release-helm-synth.yaml | Documenti dell’operatore per i due target. |
Che cosa dimostra
- Un’unica superficie di authoring, molti target. Un unico Aggregate è la fonte di verità su che cosa è lo stack. Ogni Manifest dice come realizzarlo.
- Instradamento upstream attraverso lo String Pipe. Il gateway dichiara un uso
upstreamdel backend; iprovides.hosteprovides.portdella Recipe del backend vengono convogliati nel gateway e renderizzati nella destinazione del suoproxy_pass. Il compilatore instrada le stringhe senza interpretarle — così il build Compose cabla un nome di servizio compose e il build Kubernetes cabla un nome di Service, a partire dallo stesso arco. - Configurazione idiomatica del Provider. Su entrambi i target il gateway scrive, all’avvio del container, un blocco server NGINX minimale il cui
proxy_passinoltra all’upstream iniettato, quindi avvia nginx in primo piano. Il target Kubernetes lo realizza come un Deployment stateless più un Service ClusterIP, senza alcun chart Helm esterno. - Immagini riproducibili. Il target Kubernetes esegue l’immagine upstream ufficiale di nginx fissata a un tag esplicito, quindi il Deployment renderizzato fa riferimento a un’immagine stabile.
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 nginx-gatewayPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd nginx-gatewayBuild
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:
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)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 Workspace non contiene ancora una cartella `nginx-gateway`, chiama una volta lo strumento `scaffold` con `example` impostato a `nginx-gateway` e senza `dir`: scrive l’esempio in una nuova cartella `nginx-gateway`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-compose.yaml` e `release-helm-synth.yaml` — ogni volta con `workspace_root` impostato a `nginx-gateway`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `nginx-gateway/dist/`.Come appare l’upstream iniettato
Su Compose, il servizio del gateway esegue NGINX con un blocco server che punta al nome del servizio compose e alla porta del backend:
server { listen 8000; location / { proxy_pass http://web:8080; } }Su Kubernetes, lo stesso instradamento arriva nel comando del container che scrive la configurazione del server prima di avviare nginx, puntando al Service del backend — il provider helm gli dà il nome del backend e della sua chiave di servizio default:
server { listen 8080; location / { proxy_pass http://web-default:8080; } }Entrambi derivano dallo stesso arco dell’Aggregate — host e porta del backend viaggiano attraverso l’uso upstream, e ciascun target li renderizza nel proprio idioma.
Eseguirlo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dApri http://localhost:8000 — NGINX inoltra la richiesta al backend. Per smontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down.