通过Helm部署Keycloak：配置外部LDAP替代默认PostgreSQL及排错

报错内容翻译 #

WARNING: Kubernetes配置文件可被组读取，存在安全风险。位置：/home/kube-user/.kube/config
WARNING: Kubernetes配置文件可被全局读取，存在安全风险。位置：/home/kube-user/.kube/config
Pulled: registry-1.docker.io/bitnamicharts/keycloak:16.1.1
Digest: sha256:efaa12a0e3fb0e8fe32243c67cc8e24bf1854282d10c76c6d02ce0b5f0f1f02e
Error: INSTALLATION FAILED: execution error at (keycloak/templates/NOTES.txt:93:4):
VALUES VALIDATION:
keycloak: database
你禁用了PostgreSQL子Chart，但未指定外部PostgreSQL主机。
要么启用PostgreSQL子Chart（--set postgresql.enabled=true），
要么设置外部数据库主机（--set externalDatabase.host=FOO）
并设置外部数据库密码（--set externalDatabase.password=BAR）
或者指定已存在的密钥（--set externalDatabase.existingSecret=BAR）

可行性说明 #

LDAP是Keycloak的用户存储扩展，不能替代Keycloak自身的核心元数据存储（比如用户会话、客户端配置、角色等）。Keycloak必须依赖关系型数据库（PostgreSQL、MySQL等）存储核心数据，LDAP仅作为同步/管理用户身份信息的额外数据源。所以你不能完全去掉数据库，必须先配置外部数据库，再额外添加LDAP用户存储。

具体操作步骤 #

1. 配置外部数据库 #

先准备好可用的PostgreSQL（或其他Keycloak支持的数据库），再通过Helm参数指定外部数据库信息：

helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak \
  --set postgresql.enabled=false \
  --set externalDatabase.host=你的数据库主机地址 \
  --set externalDatabase.port=5432 \
  --set externalDatabase.database=keycloak \
  --set externalDatabase.user=数据库用户名 \
  --set externalDatabase.password=数据库密码

更安全的方式是用已存在的K8s Secret存储密码：

# 创建存储数据库密码的Secret
kubectl create secret generic keycloak-db-secret --from-literal=password=你的数据库密码

# 安装时指定Secret
helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak \
  --set postgresql.enabled=false \
  --set externalDatabase.host=你的数据库主机地址 \
  --set externalDatabase.port=5432 \
  --set externalDatabase.database=keycloak \
  --set externalDatabase.user=数据库用户名 \
  --set externalDatabase.existingSecret=keycloak-db-secret

2. 配置LDAP用户存储 #

方式一：通过控制台配置

• 访问Keycloak管理控制台（默认路径/admin），登录管理员账号
• 进入目标Realm，点击左侧菜单User Federation
• 选择ldap，填写LDAP服务器连接信息（主机、端口、绑定DN、绑定密码等）
• 配置用户映射规则，测试连接后保存

方式二：通过Helm预配置（批量部署场景）

编辑自定义values.yaml文件，添加LDAP配置：

keycloak:
  extraEnvVars:
    - name: KEYCLOAK_IMPORT
      value: "/opt/keycloak/data/import/ldap-config.json"
  extraVolumeMounts:
    - name: ldap-config
      mountPath: /opt/keycloak/data/import
  extraVolumes:
    - name: ldap-config
      configMap:
        name: keycloak-ldap-config

先创建包含LDAP导入配置的ConfigMap（配置文件为Keycloak Realm导出的JSON，包含LDAP用户存储配置），再执行Helm安装命令。

注意事项 #

• 核心元数据必须存在关系型数据库中，LDAP仅用于用户身份管理，不要混淆两者作用
• 确保外部数据库已提前创建对应库和用户，且Keycloak Pod能访问数据库端口
• 生产环境优先用Secret存储敏感信息，避免明文配置

内容的提问来源于stack exchange，提问作者Tisighe Livinstone