Kong 栈——以模块形式组合的数据库支撑 API 网关
本示例从一个由开发者编写的 Aggregate 出发,将一个小型的真实栈——一个数据库支撑的 API 网关——
编译为合成的 Kubernetes manifest。
该网关不是单个组件,而是一个模块:一个可复用的 子聚合,组合了两个单工作负载组件——
- 一个网关,在其代理端口上终结客户端流量,且不保存 本地状态;以及
- 一个后端,即 PostgreSQL,保存网关的配置并 将其持久化到卷上。
该模块自行连接从网关到后端的内部边,并
将网关导出为其公共端点 proxy。顶层 Aggregate
按名称导入该模块并渲染组合后的栈;运维人员在 Release 中
为模块的内部组件设定规格。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:导入 API 网关模块(core/kong)。 |
manifest-helm-synth.yaml | 将网关和后端类型映射到各自的合成 helm Recipes。 |
release-helm-synth.yaml | Kubernetes 目标的运维记录。按模块作用域 ID 为该模块的内部组件设定规格;留给 schema 默认值的部分以自包含方式渲染。 |
演示内容
- 以模块形式组合。 一个多工作负载能力——一个实际上 由代理加配置数据库构成的 API 网关——被打包为一个 组合了两个单工作负载组件的子聚合,而不是一个单体 组件。该模块按名称导入,并在任何需要网关的地方 复用。
- 模块内部的边。 网关声明对
后端的使用;后端 Recipe 的
provides中的主机、端口、用户和数据库被 传入网关,并组合成其 PostgreSQL 连接。 编译器只路由这些字符串,不对其进行解释。 - 公共端点。 模块将其网关导出为
proxy,即消费方连接的 稳定公共名称——与模块的内部 组件名称解耦。 - 由运维人员为内部组件设定规格。 Release 通过模块作用域 ID(
gateway.backend、gateway.gateway)定位模块的 内部组件以设置计算资源,开发者的 Aggregate 无需重复声明 物理规格。 - 在提供服务前运行的迁移步骤。 网关通过一个 init 容器 初始化其数据库 schema,该容器在主网关容器启动前运行至完成, 因此网关基于已就绪的 schema 提供服务。 该引导过程是幂等的,因此针对已初始化的 数据库重新运行不会产生任何操作。
- 共享凭据。 网关向其 PostgreSQL 后端进行认证, 因此两者共享同一个密码。本示例使用共享的内联开发 默认值,因此该栈无需外部 secret 即可自包含运行。
- 可复现的镜像。 网关和后端都固定了显式的镜像 标签,因此渲染出的 manifest 引用稳定的镜像。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example kong-stack然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd kong-stack构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
aggrega build --release release-helm-synth.yaml --auto-pull渲染产物输出到 dist/ 下。Kubernetes 目标离线渲染普通
manifest——无需拉取 chart。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `kong-stack` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `kong-stack`,不设 `dir`:它会把示例写入一个新的 `kong-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `kong-stack`、`release` 设为 `release-helm-synth.yaml`、`auto_pull` 设为 true、`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `kong-stack/dist/` 下。组合后的栈是什么样子
网关渲染为一个无状态 Deployment,加上一个位于代理端口上的 ClusterIP Service,以及一个承载其 Status API 请求允许列表的 ConfigMap。其 Pod 带有一个在主容器之前运行的迁移 init 容器;两者都 带有由后端边组合而成的连接——后端的集群内 Service 名称、用户和数据库:
env: - name: KONG_DATABASE value: postgres - name: KONG_PG_HOST value: gateway-zdbackend-default - name: KONG_PG_PORT value: "5432" - name: KONG_PG_USER value: kong - name: KONG_PG_DATABASE value: kong [… omitted: the gateway's own proxy, admin and status listen addresses, and the allowlist file its Status API includes] - name: KONG_PG_PASSWORD value: apppass网关的就绪探针和存活探针通过容器端口 status 请求 Kong 的 Status API——
GET /status/ready 和 GET /status——因此该
监听器绑定在 Pod 的地址上。Kong 将 ConfigMap 中的允许列表包含在
Status API 自身的 server 块中:对于来自 Pod 回环地址以外任何地址的请求,它会响应对 /status、/status/ready 或 /metrics 的 GET,并
以 403 拒绝其他所有请求——其中包括 POST /status/ready,
否则该请求会将网关标记为排空状态,并将其移出所属 Service,直到
其重启。
后端渲染为一个 StatefulSet,带有挂载在
/var/lib/postgresql/data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。