NGINX gateway — reverse-proxy routing to an upstream, two targets
This example compiles a small, real stack — an NGINX reverse-proxy gateway
fronting a web backend — from one Developer-authored Aggregate to two
targets:
- Docker Compose for local development, and
- synthesized Kubernetes manifests for a cluster.
The same aggregate.yaml drives both. Only the Recipe layer selected by the
Manifest changes per target.
Files
| File | Role |
|---|---|
aggregate.yaml | Developer intent: a web backend (core/devtool/adminer) and a proxy gateway (core/gateway/nginx) that declares an upstream use of the backend. |
manifest-compose.yaml | Maps the gateway type to the Compose Recipe (compose/nginx) and the backend to the Compose Adminer Recipe. |
manifest-helm-synth.yaml | Maps the gateway type to the synth helm Recipe (helm/nginx) and the backend to the offline Adminer helm Recipe. |
release-compose.yaml / release-helm-synth.yaml | Operator records for the two targets. |
What it demonstrates
- One authoring surface, many targets. A single Aggregate is the source of truth for what the stack is. Each Manifest says how to realize it.
- Upstream routing through the String Pipe. The gateway declares an
upstreamuse of the backend; the backend Recipe’sprovides.hostandprovides.portare piped into the gateway and rendered into itsproxy_passtarget. The compiler routes the strings without interpreting them — so the Compose build wires a compose service name and the Kubernetes build wires a Service name, from the same edge. - Provider-idiomatic configuration. On both targets the gateway writes a
minimal NGINX server block at container start whose
proxy_passforwards to the injected upstream, then starts nginx in the foreground. The Kubernetes target realizes this as a stateless Deployment plus a ClusterIP Service, with no external Helm chart. - Reproducible images. The Kubernetes target runs the official upstream nginx image pinned to an explicit tag, so the rendered Deployment references a stable image.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example nginx-gatewayIt then prints the commands to run next. The first changes into the new folder:
cd nginx-gatewayBuild
This workspace carries no .aggrega-config.yaml, so the standard-library
entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is
needed; --auto-pull writes the lockfile a fresh clone lacks during the build:
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)aggrega build --release release-helm-synth.yaml --auto-pullRendered artifacts land under dist/. The Kubernetes target renders plain
manifests offline — no chart pull is required.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `nginx-gateway` folder yet, call the `scaffold` tool once with `example` set to `nginx-gateway` and no `dir`: it writes the example into a new `nginx-gateway` folder. Then call the `build` tool once for each Release, in this order — `release-compose.yaml` and `release-helm-synth.yaml` — each time with `workspace_root` set to `nginx-gateway`, `release` set to that file, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `nginx-gateway/dist/`.What the injected upstream looks like
On Compose, the gateway service runs NGINX with a server block pointing at the backend’s compose service name and port:
server { listen 8000; location / { proxy_pass http://web:8080; } }On Kubernetes, the same routing arrives in the container command that writes
the server config before starting nginx, pointing at the backend’s Service —
the helm provider names it after the backend and its default service key:
server { listen 8080; location / { proxy_pass http://web-default:8080; } }Both resolve from the same Aggregate edge — the backend host and port travel
through the upstream use, and each target renders them in its own idiom.
Run it (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dOpen http://localhost:8000 — NGINX forwards the request to the backend.
Tear down with
docker compose -f dist/app/compose/docker-compose.yaml down.