跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Kong 栈——以模块形式组合的数据库支撑 API 网关

本示例从一个由开发者编写的 Aggregate 出发,将一个小型的真实栈——一个数据库支撑的 API 网关—— 编译为合成的 Kubernetes manifest。

该网关不是单个组件,而是一个模块:一个可复用的 子聚合,组合了两个单工作负载组件——

  • 一个网关,在其代理端口上终结客户端流量,且不保存 本地状态;以及
  • 一个后端,即 PostgreSQL,保存网关的配置并 将其持久化到卷上。

该模块自行连接从网关到后端的内部边,并 将网关导出为其公共端点 proxy。顶层 Aggregate 按名称导入该模块并渲染组合后的栈;运维人员在 Release 中 为模块的内部组件设定规格。

文件

文件角色
aggregate.yaml开发者意图:导入 API 网关模块(core/kong)。
manifest-helm-synth.yaml将网关和后端类型映射到各自的合成 helm Recipes。
release-helm-synth.yamlKubernetes 目标的运维记录。按模块作用域 ID 为该模块的内部组件设定规格;留给 schema 默认值的部分以自包含方式渲染。

演示内容

  • 以模块形式组合。 一个多工作负载能力——一个实际上 由代理加配置数据库构成的 API 网关——被打包为一个 组合了两个单工作负载组件的子聚合,而不是一个单体 组件。该模块按名称导入,并在任何需要网关的地方 复用。
  • 模块内部的边。 网关声明对 后端的使用;后端 Recipe 的 provides 中的主机、端口、用户和数据库被 传入网关,并组合成其 PostgreSQL 连接。 编译器只路由这些字符串,不对其进行解释。
  • 公共端点。 模块将其网关导出为 proxy,即消费方连接的 稳定公共名称——与模块的内部 组件名称解耦。
  • 由运维人员为内部组件设定规格。 Release 通过模块作用域 ID(gateway.backend、 gateway.gateway)定位模块的 内部组件以设置计算资源,开发者的 Aggregate 无需重复声明 物理规格。
  • 在提供服务前运行的迁移步骤。 网关通过一个 init 容器 初始化其数据库 schema,该容器在主网关容器启动前运行至完成, 因此网关基于已就绪的 schema 提供服务。 该引导过程是幂等的,因此针对已初始化的 数据库重新运行不会产生任何操作。
  • 共享凭据。 网关向其 PostgreSQL 后端进行认证, 因此两者共享同一个密码。本示例使用共享的内联开发 默认值,因此该栈无需外部 secret 即可自包含运行。
  • 可复现的镜像。 网关和后端都固定了显式的镜像 标签,因此渲染出的 manifest 引用稳定的镜像。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example kong-stack

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd kong-stack

构建

此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:

Terminal window
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。