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

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.yamlKubernetes 目标的运维记录。指定保存 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 助手替你构建。

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

Terminal window
aggrega scaffold --example apisix-stack

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

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

在应用这些产物之前,请在目标命名空间中创建 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: 9080
deployment:
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: 30

Deployment 从 Secret 提供该变量,因此密钥不会出现在 任何渲染出的文件中:

env:
- name: APISIX_ADMIN_KEY
valueFrom:
secretKeyRef:
name: apisix-admin-key
key: admin-key

存储渲染为一个 StatefulSet,带有挂载在 /etcd-data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。