【免费下载链接】charts⚠️(OBSOLETE) Curated applications for Kubernetes项目地址https://gitcode.com/gh_mirrors/chart/charts点击查看免费下载本指南聚焦 charts 仓库中 stable/postgresql 这一 Helm Chart 的files/目录机制把postgresql.conf、pg_hba.conf、conf.d/*.conf扩展配置以及docker-entrypoint-initdb.d/下的初始化脚本放入 Chart 包目录即可在安装时自动打包为 ConfigMap 并挂载进容器实现配置文件即代码的运维方式。读完本文你将掌握三种配置注入路径的适用场景、底层模板实现原理.Files.Glob/.AsConfig的用法、与postgresqlConfiguration等 values 参数的优先级关系以及在主从架构StatefulSet 从节点下配置挂载的完整行为。一、files/目录的定位与整体结构在 stable/postgresql Chart 中files/目录是约定俗成的用户配置落盘区Chart 模板不会打包预置配置而是通过 Helm 的.Files对象在渲染时读取该目录下的文件将其内容写入 ConfigMap再挂载到 PostgreSQL 容器内。整个机制由三个子目录分工完成子目录承载文件生成资源挂载路径files/postgresql.conf完整主配置release-postgresql-configurationConfigMap/bitnami/postgresql/conffiles/pg_hba.conf客户端认证配置同上同一 ConfigMap/bitnami/postgresql/conffiles/conf.d/*.conf追加式扩展配置release-postgresql-extended-configurationConfigMap/bitnami/postgresql/conf/conf.d/files/docker-entrypoint-initdb.d/*.{sh,sql,sql.gz}首次启动初始化脚本release-postgresql-init-scriptsConfigMap/docker-entrypoint-initdb.d/其中 files/README.md 即是对该目录用途的权威说明将postgresql.conf和/或pg_hba.conf放在这里即可将其作为 ConfigMap 使用files/conf.d/README.md 补充说明扩展配置通过 PostgreSQL 的include_dir指令生效files/docker-entrypoint-initdb.d/README.md 则规定.sh、.sql、.sql.gz脚本会在镜像首次启动时被执行。值得说明的是实际使用时这三个目录应放置在你的工作目录chart 目录下由 Helm 打包时一并携带。二、完整主配置注入postgresql.conf与pg_hba.conf2.1 使用方式在 chart 工作目录即stable/postgresql/下创建files/postgresql.conf文件写入完整的 PostgreSQL 服务端配置例如# files/postgresql.conf shared_buffers 512MB max_connections 200 effective_cache_size 1536MB work_mem 4MB安装时该文件会被自动读取并渲染进 ConfigMap随后挂载到/bitnami/postgresql/conf目录Bitnami PostgreSQL 镜像的启动脚本会将其作为主配置加载。同理在files/下放入pg_hba.conf客户端认证配置文件也会被一并打包进同一个ConfigMap 并挂载。2.2 底层实现configmap.yaml 模板对应的渲染逻辑位于 templates/configmap.yaml其核心片段如下{{ if and (or (.Files.Glob files/postgresql.conf) (.Files.Glob files/pg_hba.conf) .Values.postgresqlConfiguration .Values.pgHbaConfiguration) (not .Values.configurationConfigMap) }} apiVersion: v1 kind: ConfigMap metadata: name: {{ template postgresql.fullname . }}-configuration data: {{- if (.Files.Glob files/postgresql.conf) }} {{ (.Files.Glob files/postgresql.conf).AsConfig | indent 2 }} {{- else if .Values.postgresqlConfiguration }} postgresql.conf: | {{- range $key, $value : default dict .Values.postgresqlConfiguration }} {{ $key | snakecase }}{{ $value }} {{- end }} {{- end }} {{- if (.Files.Glob files/pg_hba.conf) }} {{ (.Files.Glob files/pg_hba.conf).AsConfig | indent 2 }} {{- else if .Values.pgHbaConfiguration }} pg_hba.conf: | {{ .Values.pgHbaConfiguration | indent 4 }} {{- end }} {{ end }}这段模板揭示了三个关键行为文件优先于 valuesif分支先检查.Files.Glob files/postgresql.conf只有文件不存在时才回退到postgresqlConfiguration字典同样的逻辑适用于pg_hba.conf与pgHbaConfiguration。.AsConfig的魔法{{ (.Files.Glob files/postgresql.conf).AsConfig | indent 2 }}是 Helm 内置函数它把匹配到的每个文件自动展开为data:下的文件名: 内容键值对。Glob 模式匹配到postgresql.conf与pg_hba.conf两个文件时二者都会被渲染进同一个-configurationConfigMap。外部 ConfigMap 覆盖开关当设置了configurationConfigMap参数时整个 if 条件为假Chart 不会自建 ConfigMap而是直接引用你提供的外部 ConfigMap见第四节优先级说明。2.3 从节点同样生效该机制并非主节点专属。templates/statefulset-slaves.yaml 中存在与主 StatefulSet 完全相同的postgresql-config卷声明与/bitnami/postgresql/conf挂载因此从节点的postgresql.conf与pg_hba.conf会与主节点保持一致的配置来源无需额外重复配置。三、增量扩展配置files/conf.d/*.conf与 include_dir3.1 适用场景整份postgresql.conf往往有数百行大部分参数保持默认即可。如果只想覆盖个别参数推荐使用扩展配置方式在files/conf.d/下放入任意*.conf文件。按照 files/conf.d/README.md 的说明这些文件会以 ConfigMap 形式注入并借助 PostgreSQL 的include_dir指令在主配置之外追加或覆盖默认配置——这正是 Bitnami 镜像对include_dir的典型用法。# files/conf.d/performance.conf work_mem 16MB maintenance_work_mem 128MB wal_level replica max_wal_senders 103.2 底层实现extended-config-configmap.yaml 模板对应渲染逻辑位于 templates/extended-config-configmap.yaml{{- if and (or (.Files.Glob files/conf.d/*.conf) .Values.postgresqlExtendedConf) (not .Values.extendedConfConfigMap)}} apiVersion: v1 kind: ConfigMap metadata: name: {{ template postgresql.fullname . }}-extended-configuration data: {{- with .Files.Glob files/conf.d/*.conf }} {{ .AsConfig | indent 2 }} {{- end }} {{ with .Values.postgresqlExtendedConf }} override.conf: | {{- range $key, $value : . }} {{ $key | snakecase }}{{ $value }} {{- end }} {{- end }} {{- end }}两点值得注意Glob 支持多文件.Files.Glob files/conf.d/*.conf会匹配目录下所有.conf文件.AsConfig将它们全部转为 ConfigMap 的 data 键值对因此可以在conf.d/下按模块拆分多个配置文件如memory.conf、replication.conf、logging.conf便于管理。与 values 的合流files/conf.d/下的文件与postgresqlExtendedConf字典可以同时存在后者被渲染为override.conf键二者合并进同一个扩展配置 ConfigMap。3.3 挂载路径验证在 templates/statefulset.yaml 中可以看到- name: postgresql-extended-config mountPath: /bitnami/postgresql/conf/conf.d/即扩展配置被挂载到/bitnami/postgresql/conf/conf.d/与 PostgreSQL 主配置目录的conf.d子目录对应。Bitnami 镜像在此处通过include_dir conf.d之类的机制加载全部追加配置从而实现只覆盖指定参数、不动主配置的效果。四、首次启动初始化脚本files/docker-entrypoint-initdb.d/4.1 支持的文件类型与执行时机按照 files/docker-entrypoint-initdb.d/README.md*.sh、*.sql、*.sql.gz三种格式的脚本会被放入/docker-entrypoint-initdb.d/并在数据卷为空即首次启动全新实例时按文件名顺序执行。典型用途包括建库建表、导入种子数据、创建扩展插件等。-- files/docker-entrypoint-initdb.d/01-create-extensions.sql CREATE EXTENSION IF NOT EXISTS pgcrypto; CREATE EXTENSION IF NOT EXISTS uuid-ossp;#!/bin/sh # files/docker-entrypoint-initdb.d/02-seed.sh psql -v ON_ERROR_STOP1 --username $POSTGRES_USER --dbname $POSTGRES_DB -EOSQL INSERT INTO app.users (name) VALUES (bootstrap-user); EOSQL4.2 底层实现initialization-configmap.yaml 模板渲染逻辑位于 templates/initialization-configmap.yaml它针对不同文件类型做了差异化处理{{- with .Files.Glob files/docker-entrypoint-initdb.d/*.sql.gz }} binaryData: {{- range $path, $bytes : . }} {{ base $path }}: {{ $.Files.Get $path | b64enc | quote }} {{- end }} {{- end }} data: {{- with .Files.Glob files/docker-entrypoint-initdb.d/*.{sh,sql} }} {{ .AsConfig | indent 2 }} {{- end }}这段模板是理解该机制的精华.sql.gz走binaryDatagzip 压缩包是二进制内容无法放入 ConfigMap 的data只能存 UTF-8 文本因此模板用$.Files.Get $path | b64enc将其 base64 编码后写入binaryDataKubernetes 在挂载时会自动解码回原文件.sh/.sql走普通data文本脚本直接经.AsConfig渲染所有脚本最终通过custom-init-scripts卷以 ConfigMap 形式挂载到/docker-entrypoint-initdb.d/见 templates/statefulset.yaml由镜像启动流程依次执行。4.3 敏感脚本的 Secret 通道如果初始化脚本中包含密码、Token 等敏感信息不要直接放进 ConfigMap。模板在custom-init-scripts-secret卷中支持initdbScriptsSecret参数见 templates/statefulset.yaml可将敏感脚本以 Secret 形式挂载到/docker-entrypoint-initdb.d/secret子目录实现与普通脚本的隔离存放。五、文件注入与 values 参数的优先级files/目录并非唯一配置入口values.yaml 同时暴露了多组等效参数。理解它们的优先级有助于避免改了 values 却不生效的困惑配置主题files/ 目录方式values 等效参数外部资源覆盖参数主配置files/postgresql.confpostgresqlConfigurationcamelCase 字典configurationConfigMap认证配置files/pg_hba.confpgHbaConfiguration多行字符串configurationConfigMap扩展配置files/conf.d/*.confpostgresqlExtendedConfcamelCase 字典extendedConfConfigMap初始化脚本files/docker-entrypoint-initdb.d/initdbScripts脚本字典initdbScriptsConfigMap、initdbScriptsSecret优先级规则由模板的if条件可明确推断files/文件优先于 values 字典例如同时存在files/postgresql.conf与postgresqlConfiguration时模板只会渲染文件参见 templates/configmap.yaml 的if ... else if结构外部 ConfigMap 覆盖内置渲染configurationConfigMap、extendedConfConfigMap、initdbScriptsConfigMap一旦设置Chart 便不再自动生成对应 ConfigMap而是直接引用外部资源initdbScriptsSecret是唯一例外它不与文件/ConfigMap 互斥而是作为补充挂载可与initdbScripts或initdbScriptsConfigMap同时使用values.yaml 明确注释 This can work along initdbScripts or initdbScriptsConfigMap。关于postgresqlConfiguration/postgresqlExtendedConf的写法values.yaml 给出了明确约定以 camelCase 字典形式传入模板中的{{ $key | snakecase }}会自动转换为 PostgreSQL 期望的 snake_case 参数名例如{sharedBuffers: 500MB}最终渲染为shared_buffers500MB。六、完整实战示例一套生产级配置组合将以上机制组合使用即可在不修改 Chart 任何模板的前提下实现主配置 增量调优 初始化脚本的完整交付。目录结构如下stable/postgresql/ # chart 工作目录 ├── files/ │ ├── postgresql.conf # 完整主配置 │ ├── pg_hba.conf # 客户端认证规则 │ ├── conf.d/ │ │ ├── memory.conf # 内存类参数 │ │ └── replication.conf # 复制类参数 │ └── docker-entrypoint-initdb.d/ │ ├── 01-extensions.sql # 安装扩展 │ ├── 02-schema.sql.gz # 压缩的建表脚本 │ └── 03-seed.sh # 种子数据 └── values.yaml安装命令与校验步骤# 1. 进入 chart 目录安装files/ 下的文件会被自动打包 cd stable/postgresql helm install my-postgres . -f values-production.yaml # 2. 确认自动生成的三个 ConfigMap kubectl get configmap my-postgres-postgresql-configuration kubectl get configmap my-postgres-postgresql-extended-configuration kubectl get configmap my-postgres-postgresql-init-scripts # 3. 进入容器验证配置是否生效 kubectl exec -it my-postgres-0 -- bash psql -U postgres -c SHOW work_mem; # 应输出 conf.d 中覆盖后的值 ls /docker-entrypoint-initdb.d/ # 应看到所有初始化脚本七、注意事项与最佳实践首次启动才执行脚本docker-entrypoint-initdb.d的脚本只在数据目录为空全新实例时执行已初始化的数据库不会重复运行因此不适合用于持续性的 schema 变更保持配置一致性主从节点的配置来源于同一组模板生成逻辑statefulset.yaml 与 statefulset-slaves.yaml修改配置后需重建 Pod 才能生效建议在滚动窗口执行不要混用文件与字典若files/下存在同名配置且 values 中也配置了字典文件会静默胜出排查问题时先确认files/目录内容二进制脚本注意编码.sql.gz是唯一需要走binaryData的类型其余脚本必须为文本格式否则渲染会失败敏感信息走 Secret涉及凭据的初始化脚本优先使用initdbScriptsSecret避免在 ConfigMap 中明文存储外部 ConfigMap 是覆盖式开关一旦使用*ConfigMap类参数指向外部资源Chart 内部的文件/字典配置将整体失效务必确认外部 ConfigMap 的 data 键名与镜像期望的文件名一致。通过files/目录注入配置是 charts 仓库中 stable/postgresql Chart 提供给用户的最直接、最免模板开发的定制通道。理解其背后的.Files.Glob/.AsConfig渲染原理与优先级规则你就能在生产环境中自信地把 PostgreSQL 的每一份配置、每一个初始化脚本都纳入 Git 版本管理实现可审计、可复现的数据库交付。赞分享【免费下载链接】charts⚠️(OBSOLETE) Curated applications for Kubernetes项目地址https://gitcode.com/gh_mirrors/chart/charts点击查看免费下载相关推荐Bitnami Apache Helm Chart 虚拟主机挂载指南通过 files/vhosts 目录将 *.conf 配置注入为 ConfigMapBitnami Apache Helm Chart 虚拟主机挂载指南通过 files/vhosts 目录将 .conf 配置注入为 ConfigMap 导读云原生容器编排Pachyderm Helm Chart 的 PostgreSQL 配置文件注入指南postgresql.conf 与 pg_hba.conf 的 ConfigMap 机制Pachyderm Helm Chart 的 PostgreSQL 配置文件注入指南postgresql.conf 与 pg_hba.conf 的 Confi数据工程后端云原生任务调度微服务Bitnami MariaDB Galera Helm Chart 初始化脚本指南docker-entrypoint-initdb.d 目录的完整用法Bitnami MariaDB Galera Helm Chart 初始化脚本指南docker entrypoint initdb.d 目录的完整用法 导读云原生容器编排上一篇RedwoodJS 基于角色的访问控制RBAC实战指南从认证到授权的完整实现下一篇PaddleSpeech 服务端工具包源码解析paddlespeech.server.utils 模块全景指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考