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.yaml | Kubernetes 目标的运维记录。按模块作用域 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 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example ferretdb-stack然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd ferretdb-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 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `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: 27017readinessProbe: exec: command: - /ferretdb - ping后端渲染为一个 StatefulSet,带有挂载在
/var/lib/postgresql/data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。