NGINX 网关——到上游的反向代理路由,两个目标
本示例将一个小型的真实栈——一个位于 web 后端前面的 NGINX 反向代理网关——从一个由 Developer 编写的 Aggregate 编译到两个目标:
- 用于本地开发的 Docker Compose,以及
- 用于集群的合成 Kubernetes manifest。
同一个 aggregate.yaml 驱动两者。每个目标之间唯一变化的是
Manifest 所选的 Recipe 层。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | Developer 意图:一个 web 后端(core/devtool/adminer)和一个 proxy 网关(core/gateway/nginx),后者声明对该后端的 upstream 使用。 |
manifest-compose.yaml | 将网关类型映射到 Compose Recipe(compose/nginx),将后端映射到 Compose Adminer Recipe。 |
manifest-helm-synth.yaml | 将网关类型映射到合成 helm Recipe(helm/nginx),将后端映射到离线 Adminer helm Recipe。 |
release-compose.yaml / release-helm-synth.yaml | 两个目标的 Operator 记录。 |
演示内容
- 一个编写界面,多个目标。 单个 Aggregate 是栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- 通过 String Pipe 进行上游路由。 网关声明对后端的
upstream使用;后端 Recipe 的provides.host和provides.port通过管道传入网关,并渲染到其proxy_pass目标中。编译器路由这些字符串而不解释它们——因此 基于同一条边,Compose 构建连接的是 compose 服务名,Kubernetes 构建连接的是 Service 名。 - 符合 Provider 惯用方式的配置。 在两个目标上,网关都会在容器启动时写入一个最小的 NGINX server 块,其
proxy_pass转发到注入的上游,然后在前台启动 nginx。Kubernetes 目标将其实现为一个无状态 Deployment 加一个 ClusterIP Service, 无需外部 Helm chart。 - 可复现的镜像。 Kubernetes 目标运行官方上游 nginx 镜像,并固定到显式标签,因此渲染出的 Deployment 引用 的是稳定的镜像。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example nginx-gateway然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd nginx-gateway构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)aggrega build --release release-helm-synth.yaml --auto-pull渲染产物输出到 dist/ 下。Kubernetes 目标离线渲染普通
manifest——无需拉取 chart。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `nginx-gateway` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `nginx-gateway`,不设 `dir`:它会把示例写入新的 `nginx-gateway` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-compose.yaml` 和 `release-helm-synth.yaml`——每次都将 `workspace_root` 设为 `nginx-gateway`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `nginx-gateway/dist/` 下。注入的上游是什么样子
在 Compose 上,网关服务运行 NGINX,其 server 块指向 后端的 compose 服务名和端口:
server { listen 8000; location / { proxy_pass http://web:8080; } }在 Kubernetes 上,同样的路由出现在容器命令中,该命令在启动 nginx 之前写入
server 配置,指向后端的 Service——
helm provider 按后端及其 default 服务键为其命名:
server { listen 8080; location / { proxy_pass http://web-default:8080; } }两者都从同一条 Aggregate 边解析而来——后端主机和端口
通过 upstream 使用传递,每个目标以各自的惯用方式渲染它们。
运行(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -d打开 http://localhost:8000——NGINX 将请求转发到后端。使用 docker compose -f dist/app/compose/docker-compose.yaml down 拆除。