Passerelle NGINX — routage reverse proxy vers un upstream, deux cibles
Cet exemple compile une petite stack réelle — une passerelle reverse proxy NGINX placée devant un backend web — à partir d’un seul Aggregate écrit par le développeur vers deux cibles :
- Docker Compose pour le développement local, et
- des manifestes Kubernetes synthétisés pour un cluster.
Le même aggregate.yaml pilote les deux. Seule la couche de Recipe sélectionnée par le Manifest change d’une cible à l’autre.
Fichiers
| Fichier | Rôle |
|---|---|
aggregate.yaml | Intention du développeur : un backend web (core/devtool/adminer) et une passerelle proxy (core/gateway/nginx) qui déclare une utilisation upstream du backend. |
manifest-compose.yaml | Associe le type de la passerelle à la Recipe Compose (compose/nginx) et le backend à la Recipe Compose d’Adminer. |
manifest-helm-synth.yaml | Associe le type de la passerelle à la Recipe helm synth (helm/nginx) et le backend à la Recipe helm hors ligne d’Adminer. |
release-compose.yaml / release-helm-synth.yaml | Documents de l’opérateur pour les deux cibles. |
Ce qu’il démontre
- Une seule surface de rédaction, plusieurs cibles. Un seul Aggregate est la source de vérité sur ce qu’est la stack. Chaque Manifest dit comment la réaliser.
- Routage upstream via le String Pipe. La passerelle déclare une utilisation
upstreamdu backend ; lesprovides.hostetprovides.portde la Recipe du backend sont acheminés dans la passerelle et rendus dans la cible de sonproxy_pass. Le compilateur achemine les chaînes sans les interpréter — ainsi le build Compose câble un nom de service compose et le build Kubernetes câble un nom de Service, à partir de la même arête. - Configuration idiomatique du Provider. Sur les deux cibles, la passerelle écrit au démarrage du conteneur un bloc server NGINX minimal dont le
proxy_passtransfère vers l’upstream injecté, puis démarre nginx au premier plan. La cible Kubernetes réalise cela sous forme d’un Deployment sans état plus un Service ClusterIP, sans aucun chart Helm externe. - Images reproductibles. La cible Kubernetes exécute l’image upstream officielle de nginx épinglée à un tag explicite, si bien que le Deployment rendu référence une image stable.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example nginx-gatewayElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd nginx-gatewayBuild
Ce workspace ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire ; --auto-pull écrit pendant le build le lockfile qui manque à un clone récent :
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)aggrega build --release release-helm-synth.yaml --auto-pullLes artefacts rendus atterrissent sous dist/. La cible Kubernetes rend des manifestes simples hors ligne — aucun pull de chart n’est requis.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `nginx-gateway`, appelez une fois l’outil `scaffold` avec `example` défini sur `nginx-gateway` et sans `dir` : il écrit l’exemple dans un nouveau dossier `nginx-gateway`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-compose.yaml` et `release-helm-synth.yaml` — en définissant à chaque fois `workspace_root` sur `nginx-gateway`, `release` sur ce fichier, `auto_pull` sur true et `write` sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `nginx-gateway/dist/`.À quoi ressemble l’upstream injecté
Sur Compose, le service de la passerelle exécute NGINX avec un bloc server qui pointe vers le nom de service compose et le port du backend :
server { listen 8000; location / { proxy_pass http://web:8080; } }Sur Kubernetes, le même routage arrive dans la commande du conteneur qui écrit la configuration du serveur avant de démarrer nginx, en pointant vers le Service du backend — le fournisseur helm le nomme d’après le backend et sa clé de service default :
server { listen 8080; location / { proxy_pass http://web-default:8080; } }Les deux découlent de la même arête de l’Aggregate — l’hôte et le port du backend transitent par l’utilisation upstream, et chaque cible les rend dans son propre idiome.
L’exécuter (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dOuvrez http://localhost:8000 — NGINX transfère la requête au backend. Pour tout arrêter, utilisez docker compose -f dist/app/compose/docker-compose.yaml down.