Bitnami MariaDB Helm Chart 版本演进全解析：从 7.x 到 23.x 的安全加固与核心功能路线图

Bitnami MariaDB Helm Chart（仓库路径 bitnami/mariadb）是 Kubernetes 上部署 MariaDB 复制集群的事实标准方案之一。本文以该 Chart 自 7.3.13 到 23.0.1 的完整 CHANGELOG.md 为主线，系统梳理版本演进脉络，并结合仓库内的 values.yaml 与模板实现，逐项讲解认证凭据管理、TLS、透明数据加密（TDE）、网络策略、资源预置等关键能力。读完本文，你将掌握该 Chart 各版本的能力边界、破坏性变更的迁移要点，以及生产级参数配置的完整实操方法。

版本演进总览：1217 行 Changelog 背后的发布节奏

截至当前仓库，Bitnami MariaDB Chart 最新版本为 23.0.1（2025-11-17），镜像版本为 mariadb:12.0.2-debian-12-r0（见 Chart.yaml）。从 CHANGELOG 可观察到两个显著规律：

• 依赖引用更新是发布主体：CHANGELOG 中大量条目（如 21.0.8、21.0.7、21.0.6、21.0.5、20.5.x 等）均为“Update dependency references”，属于跟随上游镜像与 bitnami/common 依赖例行升级的补丁版本，语义化版本号稳定递增。
• 主版本号（Major）对应破坏性变更：8.0.0、9.0.0、10.0.0、11.0.0、17.0.0、20.0.0 等主版本均带有明确的 breaking 语义（详见下文“破坏性版本升级要点”）。

部署架构基线：standalone 与 replication 两种模式

Chart 通过 architecture 参数控制部署形态（默认 standalone，见 values.yaml）：

architecture: standalone   # 可选 standalone / replication

• standalone：仅部署 primary 一个 StatefulSet；
• replication：同时部署 primary 与 secondary，primary 负责写入，secondary 复制数据并提供读能力。

从模板结构可以印证这一设计：仓库在 templates/primary/ 与 templates/secondary/ 下分别维护了两套 StatefulSet、ConfigMap、Service 与 PDB，并通过 templates/headless-svc.yaml 提供无头服务供集群内部节点发现。primary StatefulSet 中 spec.replicas 固定为 1，serviceName 指向 <release-name>-headless，这正是复制集群拓扑的底层实现细节。

最低环境要求（见 README.md）：

• Kubernetes 1.23+
• Helm 3.8.0+
• 底层基础设施提供 PV 供给能力（默认使用动态卷供给）

认证与凭据管理：从环境变量到密码文件与更新 Job

凭据安全是 CHANGELOG 反复打磨的主题，大致经历了三个阶段。

阶段一：默认生成与 Secret 化管理（12.2.2 / 10.4.0）

• 12.2.2（2023-05-11）：为 MariaDB 用户创建随机密码，避免空密码默认值；
• 10.4.0（2022-03-08）：不再覆盖已存在的 Secret（Don't overwrite existing secrets）；
• 7.9.0 / 7.9.1（2020-08）：要求 Secret 资源必须包含密码，并支持自定义 Secret 文件。

阶段二：usePasswordFiles 默认开启（20.4.0 / 20.4.1）

20.4.0（2025-02-24） 将 auth.usePasswordFiles=true 设为默认值，随后 20.4.1 修复了未设置 auth.username 时 usePasswordFiles=true 场景下的问题。这意味着默认情况下，root 与普通用户的密码不再通过环境变量注入，而是以密码文件方式挂载，降低密码泄露到环境变量审计面之外的风险。

对应 values.yaml 中的完整配置：

auth:
  usePasswordFiles: true
  # 使用自定义密码文件时，按 key 指定路径
  customPasswordFiles:
    root: /vault/secrets/mariadb-root
    user: /vault/secrets/mariadb-user
    replicator: /vault/secrets/mariadb-replicator

customPasswordFiles 的出现与 9.1.1（Support Vault secrets）一脉相承——它允许从外部密钥管理系统（如 HashiCorp Vault）直接以文件形式注入凭据，不依赖 Kubernetes Secret。

阶段三：密码更新 Job（20.0.0）

20.0.0（2024-11-08） 是一个重要破坏性版本：修正 serviceName 并引入 Password Update Job。在此之前，修改密码需要手工执行 SQL；在此之后，可以声明式地通过 helm upgrade 自动完成密码轮换。

README.md 给出了带复制架构的完整升级示例：

architecture: "replication"
auth:
  user: "user"
  rootPassword: "newRootPassword123"
  password: "newUserPassword123"
  replicationPassword: "newReplicationPassword123"

passwordUpdateJob:
  enabled: true

使用两个既有 Secret（新密码 Secret 与旧密码 Secret）的写法：

auth:
  existingSecret: new-password-secret

passwordUpdateJob:
  enabled: true
  previousPasswords:
    existingSecret: previous-password-secret

从模板可以看到 Job 的实际构成：templates/update-password/job.yaml 负责执行密码变更，templates/update-password/new-secret.yaml 与 templates/update-password/previous-secret.yaml 分别管理新旧凭据的注入。passwordUpdateJob.previousPasswords 系列参数（rootPassword / password / replicationPassword / existingSecret）用于在 Secret 已被外部修改、无法从既有 Secret 自动读取旧密码时显式指定旧值；passwordUpdateJob.extraCommands 还允许追加额外更新命令。密码更新后，primary StatefulSet 会通过注解 charts.bitnami.com/password-last-update 记录更新时间（见 templates/primary/statefulset.yaml）。

安全上下文加固：从禁止特权容器到 PSA restricted 与 OpenShift 适配

CHANGELOG 中安全相关的 Major 版本密集，构成了该 Chart 的安全加固主线：

版本	日期	核心变更
11.4.5	2023-01-31	默认禁止特权容器
14.1.0	2023-10-24	支持 Pod Security Admission（PSA）restricted 策略
15.1.0	2024-01-17	完善 podSecurityContext 与 containerSecurityContext 的默认安全参数
16.1.0	2024-02-16	新增 readOnlyRootFilesystem 支持
16.2.0	2024-02-20	新增资源预置（resource preset）支持
16.5.0	2024-03-05	自动适配 OpenShift restricted-v2 SCC
17.0.0	2024-03-18	全面改进安全默认值（Improve security defaults，破坏性）

这些能力的最终落点可以在 values.yaml 中验证，例如 metrics exporter 容器的安全上下文默认即配置为 runAsNonRoot: true、runAsUser: 1001、drop: ["ALL"]、readOnlyRootFilesystem: true、seccompProfile: RuntimeDefault（见 metrics 段）。

对 OpenShift 的兼容则由 global.compatibility.openshift.adaptSecurityContext 控制，支持 auto（检测到 OpenShift 时自动适配）、force、disabled 三种取值；同时模板中通过 common.compatibility.renderSecurityContext 统一渲染安全上下文，该机制同样作用于 23.0.1 新增的 initContainerSecurityContext 参数（针对 primary 的 initContainer，见 23.0.1 变更说明与 templates/primary/statefulset.yaml）。

资源管理方面，17.0.1 与 20.2.4 两次“Increase primary resources”表明默认资源档位随版本持续上调；resourcesPreset（取值 none/nano/micro/small/medium/large/xlarge/2xlarge）允许用一行参数套用标准资源档，生产环境则建议显式设置 resources。

网络与流量治理：NetworkPolicy、PDB 与拓扑分布

• 9.8.0（2021-11-10）：首次支持网络策略（NetworkPolicy）；
• 16.0.0（2024-02-06）：默认启用 networkPolicy（破坏性变更，意味着升级后默认按最小开放原则收紧流量）；
• 10.3.6（2022-02-21）：不再硬编码 PDB 的 apiVersion，兼容新旧 Kubernetes；
• 18.2.0（2024-05-24）：PDB 全面审查（PDB review），配合多副本 secondary 提升可用性；
• 9.5.0（2021-09-07）：新增拓扑分布约束（topologySpreadConstraints），使 secondary 副本跨拓扑域分布；
• 9.2.0（2020-12-28）：支持为 primary/secondary Pod 设置优先级类（priorityClassName）；
• 11.4.0（2022-11-17）：支持 RuntimeClass（如 Kata 等安全运行时）。

网络策略的完整可调项集中在 values.yaml 的 networkPolicy 段：allowExternal（流量模型）、allowExternalEgress、extraIngress、extraEgress、ingressNSMatchLabels、ingressNSPodMatchLabels 等，渲染逻辑见 templates/networkpolicy.yaml。此外 9.6.0 为 LoadBalancer 类型 Service 增加了 externalTrafficPolicy 支持。

传输加密与静态加密：TLS 与 TDE

TLS（20.1.0 / 20.1.1）

20.1.0（2024-11-27） 为 Chart 引入 TLS 支持，20.1.1 随即修正了 TLS 的挂载路径（mountPath）。启用方式（见 README.md）：

tls:
  enabled: true
  existingSecret: tls-secret

创建含证书的 Secret：

kubectl create secret generic tls-secret --from-file=./tls.crt --from-file=./tls.key --from-file=./ca.crt

TLS 证书的供给有两种自动生成引擎（values.yaml）：

• tls.autoGenerated.engine=helm：利用 Helm 模板能力自签证书（默认引擎，autoGenerated.enabled 默认为 true），对应 templates/cert.yaml 与 templates/tls-secret.yaml；
• tls.autoGenerated.engine=cert-manager：依赖集群内已安装的 cert-manager，可通过 tls.autoGenerated.certManager.existingIssuer / existingIssuerKind 指定既有 Issuer，并配置 keySize、keyAlgorithm、duration、renewBefore。

Transparent Data Encryption（20.3.0）

20.3.0（2025-02-19） 引入透明数据加密（TDE），基于 MariaDB 的 File Key Management Encryption Plugin 对静态数据（表空间、日志、binlog 等）进行透明加密。默认参数全部预置（见 values.yaml）：

参数	默认值	说明
tde.enabled	false	总开关
tde.randomKeyFilename	keyfile.key	随机密钥文件名
tde.encryptedKeyFilename	keyfile.enc	加密密钥文件名
tde.fileKeyManagementEncryptionAlgorithm	AES_CTR	加密算法（AES_CTR / AES_CBC）
tde.innodbEncryptTables	FORCE	InnoDB 表空间自动加密（FORCE/ON/OFF）
tde.innodbEncryptLog	ON	InnoDB redo log 加密
tde.innodbEncryptTemporaryTables	ON	临时表空间加密
tde.innodbEncryptionThreads	4	加密线程数
tde.encryptTmpDiskTables	ON	查询执行中的磁盘临时表加密
tde.encryptTmpTiles	ON	filesort、binlog cache 等临时文件加密
tde.encryptBINLOG	ON	二进制日志（含 relay log）加密
tde.ariaEncryptTables	ON	Aria 表空间加密

TDE 密钥有两种存储方式：

方式一：Kubernetes Secret

kubectl create secret generic mariadb-tde-secret --namespace=mariadb \
  --from-file=./mariadb/encryption/keyfile.key \
  --from-file=./mariadb/encryption/keyfile.enc

配置 tde.enabled=true 且 tde.existingSecret=mariadb-tde-secret，密钥文件由 Secret 挂载（逻辑见 templates/secrets.yaml）。

方式二：Secrets Store CSI Driver + HashiCorp Vault

tde:
  enabled: true
  secretsStoreProvider:
    enabled: true
    provider: vault
    vault:
      roleName: "my-role"
      address: "https://vault.example.com"
      authMountPath: "kubernetes"
      randomKeySecretPath: "secrets-kv/keyfile"
      randomKeySecretKey: "key"
      encryptedKeySecretPath: "secrets-kv/keyfile"
      encryptedKeySecretKey: "enc"

Vault 中密钥需以 base64 形式存储：

export KEYFILE_KEY=$(cat ./mariadb/encryption/keyfile.key|base64)
export KEYFILE_ENC=$(cat ./mariadb/encryption/keyfile.enc|base64)

vault kv put secrets-kv/keyfile key="$KEYFILE_KEY" enc="$KEYFILE_ENC"

对应的 SecretProviderClass 渲染逻辑位于 templates/secretstoreproviderclass-tde.yaml。

⚠️ 数据可恢复性警告（源自 README.md）：开启 TDE 后，若加密密钥丢失，MariaDB 数据将无法恢复。务必在集群外安全位置备份并妥善保管加密密钥。

可观测性：mysqld-exporter、ServiceMonitor 与 PrometheusRules

• 9.4.0（2021-07-27）：为 Chart 引入诊断模式（diagnosticMode），便于排障；
• 10.1.0（2021-12-01）：为 metrics 容器补充安全上下文；
• 10.2.0（2021-12-29）：支持 PrometheusRules；
• 11.3.0（2022-09-02）：Service 的 metrics 端口可配置；
• 13.0.1（2023-08-04）：修复 mysqld-exporter 0.15.0 的参数问题。

启用指标只需一行（见 values.yaml）：

metrics:
  enabled: true

此时所有 Pod 内会以 sidecar 方式部署 bitnami/mysqld-exporter 容器（默认端口 9104），Service 自动附加 prometheus.io/scrape: "true"、prometheus.io/port: "9104" 注解；若集群装有 Prometheus Operator，可再开启 metrics.serviceMonitor.enabled=true 生成 ServiceMonitor（见 templates/servicemonitor.yaml），并通过 templates/prometheusrules.yaml 下发告警规则。exporter 支持按 primary/secondary 分别配置 extraArgs 与 extraVolumeMounts，官方注释中提供了 --collect.auto_increment.columns、--collect.binlog_size、--collect.slave_status、--collect.info_schema.innodb_metrics 等一整套采集器参数清单，可直接参考。

初始化与定制：initdbScripts、sidecars 与 initContainers

Chart 支持通过脚本初始化全新实例，允许的扩展名为 .sh、.sql、.sql.gz，两种形式的执行语义不同：

• .sh 脚本在所有节点执行（可结合 hostname 判断节点角色）；
• .sql / .sql.gz 脚本仅在 primary 节点执行。

README.md 中的典型用法：

initdbScripts:
  my_init_script.sh: |
    #!/bin/sh
    if [[ $(hostname) == *primary* ]]; then
      echo "Primary node"
      mysql -P 3306 -uroot -prandompassword -e "create database new_database";
    else
      echo "No primary node"
    fi

初始化脚本渲染见 templates/primary/initialization-configmap.yaml，也可用 initdbScriptsConfigMap 引用外部 ConfigMap（会覆盖 initdbScripts）。自定义 sidecar 与 initContainer 则分别通过 sidecars、initContainers 参数注入，扩展端口通过 service.extraPorts 暴露。

破坏性版本升级要点（Major 版本迁移指南）

结合 CHANGELOG，以下 Major 版本升级时需要重点评估：

主版本	日期	破坏性/关键变更
9.0.0	2020-11-10	Chart 适配 apiVersion: v2（Helm 3 标准）
10.0.0	2021-11-16	Chart 全面标准化（Chart standarized），模板与参数结构重构
11.0.0	2022-04-20	MariaDB 版本升级到 10.6
12.0.0	2023-04-21	依赖与参数调整
17.0.0	2024-03-18	安全默认值全面收紧（影响既有部署的安全上下文）
18.0.0	2024-04-02	组件版本更新
19.0.0	2024-07-11	组件版本更新
20.0.0	2024-11-08	修正 serviceName + 引入 Password Update Job
21.0.0 / 22.0.0	2025-06-25 / 2025-08-18	依赖引用大版本更新

从 20.4.0（2025-02-24） 起 usePasswordFiles 默认开启，从 16.0.0 起 networkPolicy 默认启用——这两项是升级到较新版本时最容易被忽略的行为变化。若使用 auth.existingSecret，其密钥键名需为 mariadb-root-password、mariadb-password、mariadb-replication-password（见 values.yaml 注释）。

从 CHANGELOG 之外继续跟踪 Chart 动态

除了 CHANGELOG.md，以下仓库文件可以交叉验证当前版本能力：

• Chart.yaml：当前 chart 版本（23.0.1）与 appVersion（12.0.2），依赖 bitnami/common 2.x；
• values.yaml：全部可调参数与默认值，本文涉及的参数均可在其中找到完整注释；
• values.schema.json：参数校验 Schema，用于 Helm 安装时的值校验；
• templates/_helpers.tpl：命名模板与标签约定；
• templates/primary/configmap.yaml 与 templates/secondary/configmap.yaml：主从节点自定义 my.cnf 配置注入。

安装最新版：

helm install my-release oci://registry-1.docker.io/bitnamicharts/mariadb

小结

Bitnami MariaDB Helm Chart 的演进路径清晰地指向三个方向：默认安全（禁特权、PSA restricted、安全上下文、密码文件化、NetworkPolicy 默认启用）、数据加密（TLS 传输加密 + TDE 静态加密）、运维自动化（随机密码、密码更新 Job、诊断模式、资源预置、Prometheus 集成）。在将业务迁移到新版本时，建议以本文梳理的 Major 变更清单为准，重点核对 usePasswordFiles、networkPolicy、安全上下文与密码更新流程四类行为差异，并始终为 TDE 密钥与数据库凭据保留集群外的安全备份。