PostgreSQL 引导脚本与自定义配置——合成 helm
core/datastore/postgres 公开两个可选的开发者值,用于决定数据库首次启动时的形态:init_scripts(在初始化时运行一次的 SQL 或 shell)和 custom_config(一个 postgresql.conf 片段)。在合成 helm 目标上,Recipe 将它们以挂载的 ConfigMap 形式带入容器。本示例表明该功能是增量式的:两个值都不设置的 Aggregate,其渲染结果与最小数据库完全相同;设置了它们的 Aggregate 则获得 ConfigMap、卷和挂载,其他一切不受影响。
同一 Component、同一 Manifest 的两个 Releases,仅在开发者值上不同:
release-bare.yaml(aggregate-bare.yaml)——init_scripts和custom_config均未设置。release-config.yaml(aggregate-config.yaml)——两者均已设置。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example postgres-init-config然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd postgres-init-config构建
aggrega build --release release-bare.yaml --auto-pullaggrega build --release release-config.yaml --auto-pull目录从 .aggrega-config.yaml 中指定的 hub 注册表解析,因此无需 --catalog 标志,且 --auto-pull 会在构建期间写入全新克隆所缺少的锁文件。裸 release 在 dist/helm/helm/ 下写入三个文件;已配置的 release 写入这三个文件,并在 dist/helm/helm/db/ 下再写入两个。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `postgres-init-config` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `postgres-init-config`,不设 `dir`:它会把示例写入新的 `postgres-init-config` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-bare.yaml` 和 `release-config.yaml`——每次都将 `workspace_root` 设为 `postgres-init-config`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `postgres-init-config/dist/` 下。裸部署——增量式基线
aggregate-bare.yaml 不设置这两个值。渲染输出为一个
StatefulSet、一个 ClusterIP Service 和一个 Headless Service——没有 ConfigMap,没有
configmap 卷,没有挂载到初始化目录的卷挂载,容器上也没有配置文件
参数。这就是最小 PostgreSQL
数据库的常规形态:
dist/helm/helm/db-statefulset.yamldist/helm/helm/db-default-service.yamldist/helm/helm/db-headless-service.yaml由于两个值在 Recipe 中都有存在性守卫,未设置的值不会输出任何内容——ConfigMap 主体渲染为空并被跳过,卷、挂载和服务器参数行也被守卫排除。从不涉及这些值的 Aggregate 不会因它们的存在而改变。
已配置——挂载脚本与配置
aggregate-config.yaml 设置了两个值:
values: init_scripts: 01-schema.sql: | CREATE TABLE app_users ( ... ); 02-seed.sql: | INSERT INTO app_users (email) VALUES ('founder@example.com'); custom_config: | max_connections = 200 shared_buffers = 256MB构建现在会额外写入两个 ConfigMap,并将它们接入 StatefulSet:
dist/helm/helm/db/initdb-configmap.yamldist/helm/helm/db/config-configmap.yaml两者都位于 db/ 下,即该 component 自身的名称。Recipe 在其
artifacts: 块中为它们命名,而在那里命名的文件使用其作者所写的键,
而不是任何标识 component 的内容——因此构建会将其写在
声明它的 component 之下,共享同一 Recipe 的两个 component 不会落到
同一路径上。StatefulSet 和两个 Service 由目标根据其所属的
component 命名,因此它们保留在边界自身的目录中。
两个值放在各自独立的 ConfigMap 中,因为每个都会 整体挂载到不同的容器路径:
init_scripts→ ConfigMapdb-initdb,每个脚本一个数据键(01-schema.sql、02-seed.sql)。一个configmap卷将其挂载到/docker-entrypoint-initdb.d, PostgreSQL 在首次初始化时按键的字母顺序 运行其中的文件一次。custom_config→ ConfigMapdb-config,一个数据键postgresql.conf。 第二个configmap卷将其挂载到/etc/postgresql,容器的args:让服务器指向它:postgres -c config_file=/etc/postgresql/postgresql.conf。片段中未写的设置保留 其内置默认值。
# db-statefulset.yaml (container)containers: - name: main image: postgres:16 args: - postgres - -c - config_file=/etc/postgresql/postgresql.conf [… omitted: the container's port, environment and resources] volumeMounts: - name: data mountPath: /var/lib/postgresql/data - name: initdb mountPath: /docker-entrypoint-initdb.d - name: pgconf mountPath: /etc/postgresql [… omitted: the liveness and readiness probes]volumes: - name: initdb configMap: name: db-initdb - name: pgconf configMap: name: db-config这些服务器参数以 args: 而非 command: 的形式传入,而这一区别决定了数据库启动时是否已填充数据:args: 是向镜像的入口点提供参数,而 command: 会替换入口点。该入口点是一个启动脚本,它在空数据目录上创建数据库,读取 POSTGRES_* 环境变量,并运行 /docker-entrypoint-initdb.d 下的文件。替换它会让服务器基于挂载的 postgresql.conf 启动,并跳过初始化和引导脚本——Aggregate 设置的值会渲染进 manifest,却永远不会运行。
只设置两个值中的一个同样有效——另一个的 ConfigMap、
卷和挂载只是不存在,而配置文件参数仅在
设置了 custom_config 时出现。
Compose
core/datastore/postgres 的 Compose Recipe 读取同一个 Component,
并通过 compose 自身的原语实现这两个值:它渲染顶层
configs: 条目,服务将每个条目作为文件挂载。
init_scripts→ 每个键一个 config,各自以其文件名挂载到/docker-entrypoint-initdb.d下。镜像会按文件名顺序运行在那里找到的文件一次, 且仅在数据目录为空时运行——已有数据的数据库 不会被改动。custom_config→ 一个 config,挂载为单个文件/etc/postgresql/postgresql.conf,并使用同样的postgres -c config_file=…参数让服务器指向它。片段中未写的设置保留其 内置默认值。
这里每一半同样都有存在性守卫,因此未设置某个值的 Aggregate 渲染时就如同该键不存在。
为 compose 部署编写 custom_config 块时,有一个设置值得一提:
listen_addresses 默认只接受本地连接,因此
省略它的块会使数据库无法被 compose 网络上的
其他服务访问。
本示例中的 Manifest 将 core/datastore/postgres 路由到 helm Recipe。
在 compose 上构建同一个 Aggregate,意味着改用一个将其路由到
compose/postgres 的 Manifest;开发者值保持不变。