Skip to content
AggregaAggrega
Select language: English

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

FileRole
aggregate.yamlDeveloper intent: a web backend (core/devtool/adminer) and a proxy gateway (core/gateway/nginx) that declares an upstream use of the backend.
manifest-compose.yamlMaps the gateway type to the Compose Recipe (compose/nginx) and the backend to the Compose Adminer Recipe.
manifest-helm-synth.yamlMaps 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.yamlOperator 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 upstream use of the backend; the backend Recipe’s provides.host and provides.port are piped into the gateway and rendered into its proxy_pass target. 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_pass forwards 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:

Terminal window
aggrega scaffold --example nginx-gateway

It then prints the commands to run next. The first changes into the new folder:

Terminal window
cd nginx-gateway

Build

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:

Terminal window
# Local development (Docker Compose)
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)
aggrega build --release release-helm-synth.yaml --auto-pull

Rendered 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)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

Open http://localhost:8000 — NGINX forwards the request to the backend. Tear down with docker compose -f dist/app/compose/docker-compose.yaml down.