bitnamicharts/keycloak

Bitnami Keycloak 镜像文档

镜像概述和主要用途

Keycloak 是一个高性能的基于Java的身份和访问管理解决方案。它允许开发人员以最小的工作量为其应用程序添加身份验证层。Bitnami Keycloak 镜像提供了一种简单、可靠的方式来部署和运行Keycloak，适用于开发和生产环境。

https://www.keycloak.org/

商标声明：本软件列表由 Bitnami 打包。产品中提到的各个商标分别归各自公司所有，使用这些商标并不意味着任何关联或认可。

核心功能和特性

• 完整的身份验证和授权功能
• 支持多种身份验证机制（用户名/密码、OAuth 2.0、OpenID Connect等）
• 可自定义的用户界面主题
• 内置用户管理和角色权限控制
• 支持多租户（Realm）架构
• 与各种应用程序和服务的集成能力
• 可扩展性和高可用性配置选项
• 监控和指标收集功能
• 支持数据库外部化和高可用性部署

使用场景和适用范围

Keycloak 适用于需要强大身份验证和授权功能的各种场景：

• 企业级Web应用程序的单点登录(SSO)解决方案
• API和微服务的安全访问控制
• 多租户应用程序的身份管理
• 移动应用程序的身份验证后端
• 需要支持社交登录的应用程序
• 企业内部系统的统一身份管理平台

快速开始

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

如需在生产环境中使用Keycloak，建议尝试https://bitnami.com/enterprise%EF%BC%8C%E8%BF%99%E6%98%AFBitnami%E7%9B%AE%E5%BD%95%E7%9A%84%E5%95%86%E4%B8%9A%E7%89%88%E6%9C%AC%E3%80%82

⚠️ 重要通知：Bitnami目录即将发生的变化

自2025年8月28日起，Bitnami将改进其公共目录，在新的https://news.broadcom.com/app-dev/broadcom-introduces-bitnami-secure-images-for-production-ready-containerized-applications%E4%B8%8B%E6%8F%90%E4%BE%9B%E7%B2%BE%E9%80%89%E7%9A%84%E5%BC%BA%E5%8C%96%E3%80%81%E5%AE%89%E5%85%A8%E8%81%9A%E7%84%A6%E7%9A%84%E9%95%9C%E5%83%8F%E3%80%82%E4%BD%9C%E4%B8%BA%E6%AD%A4%E8%BF%87%E6%B8%A1%E7%9A%84%E4%B8%80%E9%83%A8%E5%88%86%EF%BC%9A

• 首次向社区用户提供流行容器镜像的安全优化版本
• Bitnami将开始在其免费层中弃用对非强化的基于Debian的软件镜像的支持，并将逐步从公共目录中删除非最新标签。因此，社区用户将只能访问数量减少的强化镜像，这些镜像仅以"latest"标签发布，仅供开发目的使用
• 从8月28日开始，在两周内，所有现有容器镜像（包括旧版本或特定版本标签，例如2.50.0、10.6）将从公共目录(docker.io/bitnami)迁移到"Bitnami Legacy"仓库(docker.io/bitnamilegacy)，并且不再接收更新
• 对于生产工作负载和长期支持，建议用户采用Bitnami Secure Images，其中包括强化容器、更小的***面、CVE透明度（通过VEX/KEV）、SBOM和企业支持

这些变更旨在通过推广软件供应链完整性和最新部署的最佳实践，提高所有Bitnami用户的安全态势。有关更多详细信息，请访问https://github.com/bitnami/containers/issues/83267%E3%80%82

前提条件

• Kubernetes 1.23+
• Helm 3.8.0+

安装方法

使用 Helm 安装

要安装名为my-release的Chart:

console
helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/keycloak

注意: 您需要将占位符REGISTRY_NAME和REPOSITORY_NAME替换为Helm Chart仓库的引用。例如，对于Bitnami，您需要使用REGISTRY_NAME=registry-1.docker.io和REPOSITORY_NAME=bitnamicharts。

这些命令使用默认配置在Kubernetes集群上部署Keycloak应用程序。

提示: 使用helm list命令列出所有发布版本

Docker Compose 部署示例

yaml
version: '3'

services:
  keycloak:
    image: docker.xuanyuan.run/bitnami/keycloak:latest
    ports:
      - '8080:8080'
    environment:
      - KEYCLOAK_ADMIN_USER=admin
      - KEYCLOAK_ADMIN_PASSWORD=password
      - KEYCLOAK_EXTRA_ARGS=--import-realm
    volumes:
      - ./realms:/opt/bitnami/keycloak/data/import

基本 Docker 运行命令

console
docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN_USER=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=password \
  docker.xuanyuan.run/bitnami/keycloak:latest

配置说明

Prometheus 指标

通过将metrics.enabled设置为true，可以将此Chart与Prometheus集成。这将在metrics服务中公开Keycloak原生Prometheus端点，可以在metrics.service部分下进行配置。它将具有必要的注释，以便被Prometheus自动抓取。

Prometheus 要求

要使集成正常工作，需要安装Prometheus或Prometheus Operator。安装https://github.com/bitnami/charts/tree/main/bitnami/prometheus%E6%88%96https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus%EF%BC%8C%E5%8F%AF%E4%BB%A5%E8%BD%BB%E6%9D%BE%E5%9C%A8%E9%9B%86%E7%BE%A4%E4%B8%AD%E6%8B%A5%E6%9C%89%E4%B8%80%E4%B8%AA%E5%8F%AF%E7%94%A8%E7%9A%84Prometheus%E3%80%82

与 Prometheus Operator 集成

通过设置metrics.serviceMonitor.enabled=true，Chart可以部署ServiceMonitor对象，以便与Prometheus Operator集成。确保在集群中安装了Prometheus Operator CustomResourceDefinitions，否则将失败并显示以下错误：

text
no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

安装https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus%E4%BB%A5%E8%8E%B7%E5%8F%96%E5%BF%85%E8%A6%81%E7%9A%84CRD%E5%92%8CPrometheus Operator。

使用外部数据库

有时，您可能希望让Keycloak连接到外部PostgreSQL数据库，而不是集群内的数据库 - 例如，当使用托管数据库服务时，或者为所有应用程序运行单个数据库服务器时。要实现此目的，请将postgresql.enabled参数设置为false，并使用externalDatabase.*参数指定外部数据库的凭据。以下是一个示例：

text
postgresql.enabled=false
externalDatabase.host=myexternalhost
externalDatabase.user=myuser
externalDatabase.password=mypassword
externalDatabase.database=mydatabase
externalDatabase.port=5432
externalDatabase.schema=public

注意: 仅支持PostgreSQL数据库服务器作为外部数据库

虽然不推荐，但也可以使用外部MSSQL数据库运行Keycloak，配置如下：

yaml
externalDatabase:
  host: "mssql.example.com"
  port: 1433
  user: keycloak
  database: keycloak
  existingSecret: passwords
extraEnvVars:
  - name: KC_DB # 覆盖配置文件中的值
    value: 'mssql'
  - name: KC_DB_URL
    value: 'jdbc:sqlserver://mssql.example.com:1433;databaseName=keycloak;'

导入和导出 Realm

导入 Realm

您可以通过将KEYCLOAK_EXTRA_ARGS设置为包含--import-realm参数来导入Realm。

根据官方文档https://www.keycloak.org/server/importExport#_importing_a_realm_from_a_directory%E7%9A%84%E8%AF%B4%E6%98%8E%EF%BC%8C%E8%BF%99%E5%B0%86%E5%AF%BC%E5%85%A5%60/opt/bitnami/keycloak/data/import%60%E4%B8%8B%E6%89%80%E6%9C%89%60*.json%60%E6%96%87%E4%BB%B6%E4%BD%9C%E4%B8%BAKeycloak%E7%9A%84Realm%E3%80%82%E6%82%A8%E5%8F%AF%E4%BB%A5%E9%80%9A%E8%BF%87%E6%8C%82%E8%BD%BD%E5%8D%B7%E6%9D%A5%E6%8F%90%E4%BE%9B%E6%96%87%E4%BB%B6%EF%BC%8C%E4%BE%8B%E5%A6%82%E4%BD%BF%E7%94%A8docker compose：

yaml
keycloak:
  image: docker.xuanyuan.run/bitnami/keycloak:latest
  volumes:
    - /local/path/to/realms/folder:/opt/bitnami/keycloak/data/import

导出 Realm

您可以通过GUI导出Realm，但即使设置了选项，它也不会导出用户，这是Keycloak的一个已知https://github.com/keycloak/keycloak/issues/23970%E3%80%82

通过使用kc.sh脚本，您可以导出包含用户的Realm。确保将导出文件夹挂载到本地文件夹：

yaml
keycloak:
  image: docker.xuanyuan.run/bitnami/keycloak:latest
  volumes:
    - /local/path/to/export/folder:/export

然后在运行的keycloak容器中打开终端并运行：

bash
kc.sh export --dir /export/ --users realm_file

这将把所有Realm连同用户一起导出到/export文件夹。

配置 Ingress

此Chart提供对Ingress资源的支持。如果您的集群上安装了Ingress控制器（例如https://github.com/bitnami/charts/tree/main/bitnami/nginx-ingress-controller%E6%88%96https://github.com/bitnami/charts/tree/main/bitnami/contour%EF%BC%89%EF%BC%8C%E6%82%A8%E5%8F%AF%E4%BB%A5%E5%88%A9%E7%94%A8Ingress%E6%8E%A7%E5%88%B6%E5%99%A8%E6%9D%A5%E6%8F%90%E4%BE%9B%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F%E6%9C%8D%E5%8A%A1%E3%80%82%E8%A6%81%E5%90%AF%E7%94%A8Ingress%E9%9B%86%E6%88%90%EF%BC%8C%E8%AF%B7%E5%B0%86%60ingress.enabled%60%E8%AE%BE%E7%BD%AE%E4%B8%BA%60true%60%E3%80%82

最常见的场景是将一个主机名映射到部署。在这种情况下，可以使用ingress.hostname属性来设置主机名。ingress.tls参数可用于为此主机添加TLS配置。

但是，也可以有多个主机。为了实现这一点，可以设置ingress.extraHosts参数（如果可用），将主机名指定为数组。还可以使用ingress.extraTLS参数（如果可用）为额外的主机添加TLS配置。

注意: 对于ingress.extraHosts参数中指定的每个主机，需要设置名称、路径以及Ingress控制器应了解的任何注释。并非所有Ingress控制器都支持所有注释，但https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md%E5%88%97%E5%87%BA%E4%BA%86%E8%AE%B8%E5%A4%9A%E6%B5%81%E8%A1%8CIngress%E6%8E%A7%E5%88%B6%E5%99%A8%E6%94%AF%E6%8C%81%E7%9A%84%E6%B3%A8%E9%87%8A%E3%80%82

添加TLS参数（如果可用）将导致Chart生成HTTPS URL，应用程序将在端口443上可用。实际的TLS密钥不必由此Chart生成。但是，如果启用了TLS，则在TLS密钥存在之前，Ingress记录将无法工作。

https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/%E3%80%82

配置用于 Ingress 的 TLS 密钥

此Chart有助于创建用于Ingress控制器的TLS密钥（尽管这不是必需的）。有几种常见的用例：

• 基于Chart参数生成证书密钥
• 启用外部生成的证书
• 通过外部服务（如https://github.com/jetstack/cert-manager/%EF%BC%89%E7%AE%A1%E7%90%86%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F%E8%AF%81%E4%B9%A6
• 在Chart中创建自签名证书（如果支持）

在前两种情况下，需要证书和密钥。文件应为.pem格式。

证书文件示例：

注意: 如果存在证书链，可能会有多个证书。

text
-----BEGIN CERTIFICATE-----
MIID6TCCAtGgAwIBAgIJAIaCwivkeB5EMA0GCSqGSIb3DQEBCwUAMFYxCzAJBgNV
...
jScrvkiBO65F46KioCL9h5tDvomdU1aqpI/CBzhvZn1c0ZTf87tGQR8NK7v7
-----END CERTIFICATE-----

证书密钥示例：

text
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAvLYcyu8f3skuRyUgeeNpeDvYBCDcgq+LsWap6zbX5f8oLqp4
...
wrj2wDbCDCFmfqnSJ+dKI3vFLlEz44sAV8jX/kd4Y6ZTQhlLbYc=
-----END RSA PRIVATE KEY-----

• 如果使用Helm基于参数管理证书，请将这些值复制到给定*.ingress.secrets条目的certificate和key值中。
• 如果单独管理TLS密钥，则需要创建名称为INGRESS_HOSTNAME-tls的TLS密钥（其中INGRESS_HOSTNAME是一个占位符，需要替换为您使用*.ingress.hostname参数设置的主机名）。
• 如果您的集群有https://github.com/jetstack/cert-manager%E6%8F%92%E4%BB%B6%E6%9D%A5%E8%87%AA%E5%8A%A8%E7%AE%A1%E7%90%86%E5%92%8C%E9%A2%81%E5%8F%91TLS%E8%AF%81%E4%B9%A6%EF%BC%8C%E8%AF%B7%E5%B0%86https://cert-manager.io/docs/usage/ingress/#supported-annotations%E6%B7%BB%E5%8A%A0%E5%88%B0%60*.ingress.annotations%60%E4%B8%AD%E3%80%82
• 如果使用Helm创建的自签名证书，请将*.ingress.tls和*.ingress.selfSigned都设置为true。

使用 TLS 保护流量

可以通过指定tls.enabled=true在Chart中启用Web界面的TLS支持。有两种可能的选项：

• 提供您自己的PEM或JKS证书密钥
• 让Chart自动生成证书

提供您自己的 TLS 密钥

要提供您自己的密钥，请设置tls.existingSecret值。可以使用PEM或JKS格式。

使用PEM证书：

• tls.usePemCerts=true: 使用PEM证书而不是JKS文件。
• tls.certFilename: 证书文件名。默认为tls.crt。
• tls.certKeyFilename: 证书密钥文件名。默认为tls.key

使用JKS密钥库：

• tls.usePemCerts=false: 使用JKS文件。
• tls.keystoreFilename: 证书文件名。默认为keycloak.keystore.jks。
• tls.truststoreFilename: 信任库文件名。默认为keycloak.truststore.jks。

在以下示例中，我们将使用PEM证书。首先，使用证书文件创建密钥：

console
kubectl create secret generic certificates-tls-secret --from-file=./cert.pem --from-file=./cert.key

然后，使用以下参数：

console
tls.enabled=true
tls.autoGenerated.enabled=false
tls.usePemCerts=true
tls.existingSecret="certificates-tls-secret"
tls.certFilename="cert.pem"
tls.certKeyFilename="cert.key"

自动生成 TLS 证书

也可以依靠Chart的证书自动生成功能。Chart支持两种不同的自动生成所需证书的方式：

• 使用Helm功能。通过将tls.autoGenerated.enabled设置为true并将tls.autoGenerated.engine设置为helm来启用此功能。
• 依赖CertManager（请注意，需要在K8s集群中安装CertManager）。通过将tls.autoGenerated.enabled设置为true并将tls.autoGenerated.engine设置为cert-manager来启用此功能。请注意，支持通过设置tls.autoGenerated.certManager.existingIssuer和tls.autoGenerated.certManager.existingIssuerKind参数来使用现有的Issuer/ClusterIssuer来颁发TLS证书。

与 Ingress 一起使用 SSL 卸载

如果您的Ingress控制器具有TLS/SSL终止功能，您可能需要通过proxyHeaders参数正确配置反向代理头。在https://www.keycloak.org/server/reverseproxy%E4%B8%AD%E6%89%BE%E5%88%B0%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%E3%80%82

更新凭据

Bitnami charts在首次启动时配置凭据。对密钥或凭据的任何进一步更改都需要手动干预。请按照以下说明操作：

• 按照https://www.keycloak.org/server/configuration%E6%9B%B4%E6%96%B0%E7%94%A8%E6%88%B7%E5%AF%86%E7%A0%81
• 使用新值更新密码密钥（替换SECRET_NAME和PASSWORD占位符）

shell
kubectl create secret generic SECRET_NAME --from-literal=admin-password=PASSWORD --dry-run -o yaml | kubectl apply -f -

备份和恢复

要在Kubernetes上备份和恢复Helm chart部署，您需要从源部署备份持久卷，并使用https://velero.io/%EF%BC%88Kubernetes%E5%A4%87%E4%BB%BD/%E6%81%A2%E5%A4%8D%E5%B7%A5%E5%85%B7%EF%BC%89%E5%B0%86%E5%AE%83%E4%BB%AC%E9%99%84%E5%8A%A0%E5%88%B0%E6%96%B0%E9%83%A8%E7%BD%B2%E3%80%82%E5%9C%A8https://techdocs.broadcom.com/us/en/vmware-tanzu/application-catalog/tanzu-application-catalog/services/tac-doc/apps-tutorials-backup-restore-deployments-velero-index.html%E4%B8%AD%E6%89%BE%E5%88%B0%E4%BD%BF%E7%94%A8Velero%E7%9A%84%E8%AF%B4%E6%98%8E%E3%80%82

资源请求和限制

Bitnami charts允许为Chart部署内的所有容器设置资源请求和限制。这些在resources值内（检查参数表）。设置请求对于生产工作负载至关重要，这些应该根据您的具体用例进行调整。

为了使此过程更容易，Chart包含resourcesPreset值，它根据不同的预设自动设置resources部分。在https://github.com/bitnami/charts/blob/main/bitnami/common/templates/_resources.tpl#L15%E4%B8%AD%E6%A3%80%E6%9F%A5%E8%BF%99%E4%BA%9B%E9%A2%84%E8%AE%BE%E3%80%82%E4%BD%86%E6%98%AF%EF%BC%8C%E5%9C%A8%E7%94%9F%E4%BA%A7%E5%B7%A5%E4%BD%9C%E8%B4%9F%E8%BD%BD%E4%B8%AD%E4%B8%8D%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%60resourcesPreset%60%EF%BC%8C%E5%9B%A0%E4%B8%BA%E5%AE%83%E5%8F%AF%E8%83%BD%E6%97%A0%E6%B3%95%E5%AE%8C%E5%85%A8%E9%80%82%E5%BA%94%E6%82%A8%E7%9A%84%E7%89%B9%E5%AE%9A%E9%9C%80%E6%B1%82%E3%80%82%E5%9C%A8https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/%E4%B8%AD%E6%89%BE%E5%88%B0%E6%9C%89%E5%85%B3%E5%AE%B9%E5%99%A8%E8%B5%84%E6%BA%90%E7%AE%A1%E7%90%86%E7%9A%84%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%E3%80%82

设置 Pod 亲和性

此Chart允许您使用affinity参数设置自定义亲和性。在[kubernetes文档](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-