APISIX 栈——以模块形式组合的动态 API 网关
本示例将一个小型的真实栈——一个动态 API 网关——从一个由开发者编写的 Aggregate
编译为合成的 Kubernetes manifest。
该网关不是单个组件,而是一个模块:一个可复用的 子聚合,组合了两个单工作负载组件——
- 一个网关,在其代理端口上终结客户端流量,且不保存 本地状态;以及
- 一个存储,即 etcd,保存网关的配置并将其持久化到 一个卷上。
该模块自行连接从网关到存储的内部边,并将网关导出
为其公共端点 proxy。顶层 Aggregate 按名称导入该
模块并渲染组合后的栈;运维人员在 Release 中为模块的
内部组件设定规格。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:导入 API 网关模块(core/apisix),并将其自身某个参数中的网关 Admin API 密钥传给该模块。 |
manifest-helm-synth.yaml | 将网关和存储类型映射到对应的 synth helm Recipes,并将模块附加的凭据 Feature 映射到读取命名空间中已有 Secret 的实现。 |
release-helm-synth.yaml | Kubernetes 目标的运维记录。指定保存 Admin API 密钥的 Secret,并按模块作用域 ID 为模块的内部组件设定规格;其余均使用 schema 默认值。 |
演示内容
- 以模块形式组合。 一个多工作负载能力——实际上由代理加 配置存储构成的 API 网关——被打包为组合两个单工作负载组件的 子聚合,而不是一个单体组件。该 模块按名称导入,可在任何需要网关的地方复用。
- 模块内部的边。 网关声明对存储的使用;
存储 Recipe 的
provides主机和端口被传入网关, 并组合成其 etcd 连接。编译器只路由这些字符串, 不解释其含义。 - 公共端点。 模块将其网关导出为
proxy,即消费方连接的 稳定公共名称——与模块的内部 组件名称解耦。 - 由运维人员设定内部组件规格。 Release 通过模块作用域 ID(
gateway.store、gateway.gateway)引用模块的内部组件来设置计算资源, 无需在开发者的 Aggregate 中重复声明 物理规格。 - 与运行时写入的文件并存挂载的配置文件。 网关 从某个目录中的文件读取配置,并在启动时也向该目录写入文件。 Recipe 将该配置生成为 ConfigMap 并以 单个文件的方式挂载,从而在配置网关的同时不会遮蔽网关 在该目录中写入的文件。
- 从 Secret 读取 Admin API 密钥。 网关通过 Admin API
管理其路由,其密钥经由网关上的一个凭据槽传入;
只要网关的 models 套接字未连接任何内容(如本例),
网关就要求该凭据,因此不存在默认密钥。模块将密钥作为
参数
admin_key接收,并用它将core/referenced-secret凭据 Feature 附加到该槽;本 Aggregate 声明自己的一个参数 并向下传递,由 Release 填充。Manifest 将该 Feature 映射到k8s-existing-secret,因此该值是命名空间中 已存在的某个 Secret 的名称:构建不读取也不渲染任何密钥, 网关在启动时从该 Secret 读取密钥。未提供该值的 Release 会使构建中止,并指出该参数。 - 可复现的镜像。 网关和存储都固定了明确的镜像 标签,因此渲染出的 manifest 引用的是稳定的镜像。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example apisix-stack然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd apisix-stack构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
aggrega build --release release-helm-synth.yaml --auto-pull渲染产物输出到 dist/ 下。Kubernetes 目标离线渲染普通
manifest——无需拉取 chart。
在应用这些产物之前,请在目标命名空间中创建 Release 指定的 Secret apisix-admin-key,
并在数据键 admin-key 下存放你自己的密钥。
该密钥不得为空(为空会导致网关在启动时停止),
也不得是 APISIX 会解析为数字或 true/false 的值,例如
全数字的密钥,因为那样 APISIX 永远不会将其与请求
提供的密钥匹配。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `apisix-stack` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `apisix-stack`,且不提供 `dir`:它会把示例写入一个新的 `apisix-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `apisix-stack`,`release` 设为 `release-helm-synth.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `apisix-stack/dist/` 下。组合后的栈是什么样子
网关渲染为一个无状态 Deployment,外加一个位于 代理端口上的 ClusterIP Service。其配置以 ConfigMap 形式交付,作为单个 文件挂载到容器的 conf 目录中;该配置包含存储的 集群内 Service 名称,并在 Admin API 密钥的位置写入 APISIX 加载该文件时用于读取密钥的环境变量名称:
apisix: node_listen: 9080deployment: role: traditional role_traditional: config_provider: etcd admin: [… omitted: the client range the Admin API accepts] admin_key: - name: admin key: ${{APISIX_ADMIN_KEY}} role: admin admin_listen: ip: 0.0.0.0 port: 9180 etcd: host: - "http://gateway-zdstore-default:2379" prefix: "/apisix" timeout: 30Deployment 从 Secret 提供该变量,因此密钥不会出现在 任何渲染出的文件中:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-key存储渲染为一个 StatefulSet,带有挂载在
/etcd-data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。