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

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 助手替你构建。

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

Terminal window
aggrega scaffold --example postgres-init-config

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

Terminal window
cd postgres-init-config

构建

Terminal window
aggrega build --release release-bare.yaml --auto-pull
aggrega 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.yaml
dist/helm/helm/db-default-service.yaml
dist/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.yaml
dist/helm/helm/db/config-configmap.yaml

两者都位于 db/ 下,即该 component 自身的名称。Recipe 在其 artifacts: 块中为它们命名,而在那里命名的文件使用其作者所写的键, 而不是任何标识 component 的内容——因此构建会将其写在 声明它的 component 之下,共享同一 Recipe 的两个 component 不会落到 同一路径上。StatefulSet 和两个 Service 由目标根据其所属的 component 命名,因此它们保留在边界自身的目录中。

两个值放在各自独立的 ConfigMap 中,因为每个都会 整体挂载到不同的容器路径:

  • init_scripts → ConfigMap db-initdb,每个脚本一个数据键(01-schema.sql、 02-seed.sql)。一个 configmap 卷将其挂载到 /docker-entrypoint-initdb.d, PostgreSQL 在首次初始化时按键的字母顺序 运行其中的文件一次。
  • custom_config → ConfigMap db-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;开发者值保持不变。