keycloak Helm Chart替换postgresql-ha依赖后安装失败

数据老陈

2026-9-2

问题根因

报错本质是直接修改原有依赖名称的适配方式完全不成立：codecentric/keycloak 18.1.1版本的所有模板逻辑，都是针对Bitnami单实例PostgreSQL Chart的模板命名规则、值结构编写的，和PostgreSQL-HA Chart的模板体系、配置结构完全不兼容，简单替换字段名覆盖不了所有差异。
你遇到的no template "postgresql.primary.fullname"报错，就是因为：

单实例PostgreSQL Chart对外暴露的模板命名以postgresql.为前缀，主节点配置直接放在postgresql根值字段下
PostgreSQL-HA Chart的所有模板命名以postgresql-ha.为前缀，同时它的服务名、密钥键名、主从节点配置层级和单实例版完全不同，全局替换postgresql字符串既改不全所有引用点，还可能误改非依赖相关的逻辑。

正确解决步骤

回退之前修改过的所有文件，或者重新拉取原始干净的Chart包：

rm -rf ./keycloak
helm pull codecentric/keycloak --version 18.1.1 --untar

不要修改原有PostgreSQL依赖条目，通过「禁用内置PostgreSQL + 新增PostgreSQL-HA依赖 + 配置Keycloak数据库连接指向HA实例」的方式适配：

编辑Chart.yaml，保留原有PostgreSQL依赖，新增PostgreSQL-HA依赖项，通过condition字段控制启停：

dependencies:
  - name: postgresql
    version: 10.3.13
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
  - name: postgresql-ha
    version: 9.1.0
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql-ha.enabled

编辑values.yaml，关闭内置单实例PostgreSQL，开启PostgreSQL-HA，同时配置Keycloak的数据库连接参数：

# 关闭内置postgresql
postgresql:
  enabled: false
# 开启postgresql-ha，按需求配置账号密码、持久化等参数
postgresql-ha:
  enabled: true
  auth:
    postgresPassword: "your-root-db-password"
    database: "keycloak"
    username: "keycloak"
    password: "your-keycloak-db-password"
  pgpool:
    service:
      type: ClusterIP
# 配置keycloak连接postgresql-ha的pgpool代理服务
externalDatabase:
  enabled: true
  host: "{{ .Release.Name }}-postgresql-ha-pgpool"
  port: 5432
  database: keycloak
  user: keycloak
  password: "your-keycloak-db-password"

清除旧的依赖缓存，重新拉取依赖：

rm -rf ./keycloak/charts ./keycloak/Chart.lock
helm dependency update ./keycloak

正常执行安装命令即可，不会再出现模板不存在的报错。

额外说明

不要尝试手动修改Keycloak Chart里的_helpers.tpl、statefulset.yaml等内置模板来适配PostgreSQL-HA，除了全量名引用，模板里还有大量针对单实例PostgreSQL的硬编码逻辑：比如密钥键名读取、服务端口引用、就绪检查路径配置，这些逻辑和PostgreSQL-HA的匹配点非常多，手动改漏任何一处都会导致安装失败或者运行时连不上数据库，用Chart自带的externalDatabase配置项对接外部/HA版数据库是官方支持的最稳妥方案。

内容的提问来源于stack exchange，提问作者rakesh kotian