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

FerretDB 栈——以模块形式组合的文档数据库

本示例将一个小型的真实栈——一个暴露 MongoDB 线协议的文档数据库——从一个由 开发者编写的 Aggregate 编译为合成的 Kubernetes manifest。

该文档数据库不是单个组件。它是一个模块:一个可复用的 子 aggregate,组合了两个单 workload 组件——

  • 一个使用 MongoDB 线协议通信、不保存本地状态的代理,以及
  • 一个后端,即带 DocumentDB 扩展的 PostgreSQL 17,它将 数据持久化到卷上。

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

文件

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

演示内容

  • 以模块形式组合。 一个多 workload 能力——一个实际上 由代理加存储后端构成的文档数据库——被打包为一个组合了两个 单 workload 组件的子 aggregate,而不是一个单体组件。该 模块按名称导入,并在任何需要文档数据库的地方复用。
  • 模块内部的边。 代理声明对后端的使用; 后端 Recipe 的 provides 中的主机、端口、用户和数据库被传入 代理,并组合成其 PostgreSQL 连接。编译器只路由这些 字符串,不解释它们。
  • 公共端点。 该模块将其代理导出为 mongo,这是 文档数据库使用方所连接的稳定公共名称——与模块的 内部组件名称解耦。
  • 运维人员为内部组件设定规格。 Release 按模块作用域 ID(database.backend、database.proxy)引用该模块的内部组件,以设置计算资源,而无需开发者的 Aggregate 重复声明物理规格。
  • 共享凭据。 代理将身份验证委托给其 PostgreSQL 后端,因此二者共享同一个密码。本示例使用共享的内联 开发默认值,因此该栈无需外部 secret 即可自包含运行。
  • 不含密码的连接字符串。 代理的 PostgreSQL 连接 URL 渲染时不嵌入密码;密码通过标准 libpq PGPASSWORD 环境变量 单独提供,驱动程序会将其合并到连接中。这样渲染后的 manifest 中,凭据不会出现在连接字符串里。
  • 可复现的镜像。 代理和后端都固定了明确的镜像标签, 因此渲染后的 manifest 引用稳定的镜像。

生成示例

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

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

Terminal window
aggrega scaffold --example ferretdb-stack

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

Terminal window
cd ferretdb-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 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `ferretdb-stack` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `ferretdb-stack`,且不设置 `dir`:它会把示例写入新的 `ferretdb-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `ferretdb-stack`,`release` 设为 `release-helm-synth.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我这次构建写入了哪些文件;它们位于 `ferretdb-stack/dist/` 下。

组合后的栈是什么样子

代理渲染为一个无状态 Deployment,外加一个位于线协议端口上的 ClusterIP Service。其容器环境携带由后端边组合而成的连接—— 后端的集群内 Service 名称、用户和数据库,URL 中不含 密码——并将 FerretDB 的调试监听器保留在 pod 的回环 地址上,其他 pod 无法访问:

env:
- name: FERRETDB_LISTEN_ADDR
value: :27017
- name: FERRETDB_DEBUG_ADDR
value: 127.0.0.1:8088
- name: FERRETDB_POSTGRESQL_URL
value: postgres://postgres@database-zdbackend-default:5432/postgres
- name: PGPASSWORD
value: apppass

两个探针都不需要该监听器。就绪探针在容器内运行 ferretdb ping, 它会 ping 线协议端口,因而也能证明后端 连接正常;存活探针只检查线协议端口是否接受 连接,因此后端故障会将代理从其 Service 中移出,而不会 重启它:

livenessProbe:
tcpSocket:
port: 27017
readinessProbe:
exec:
command:
- /ferretdb
- ping

后端渲染为一个 StatefulSet,带有挂载在 /var/lib/postgresql/data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。