camunda/keycloak

Camunda Keycloak容器镜像

此Docker镜像提供基于https://hub.docker.com/r/bitnami/keycloak%E6%88%96Quay.io%E5%AE%98%E6%96%B9Keycloak%E9%95%9C%E5%83%8F%E7%9A%84%E9%80%9A%E7%94%A8Keycloak%E8%AE%BE%E7%BD%AE%E3%80%82%E8%BF%98%E5%8C%85%E5%90%AB%EF%BC%9A

• 可选AWS包装器，支持使用AWS身份与访问管理（IAM）角色用于服务账户（IRSA）进行数据库认证
• 可选Camunda身份认证登录主题

镜像变体

本仓库提供三种主要镜像变体：

⚠️ 关于Bitnami镜像的重要说明 由于https://github.com/bitnami/containers/issues/83267%EF%BC%8C%E8%87%AA2025%E5%B9%B48%E6%9C%8828%E6%97%A5%E8%B5%B7%EF%BC%8C%E6%96%B0%E7%9A%84Bitnami%E5%AE%B9%E5%99%A8%E9%95%9C%E5%83%8F%E4%B8%8D%E5%86%8D%E5%8F%91%E5%B8%83%E5%88%B0Docker Hub。本仓库现在使用docker.io/bitnamilegacy仓库的镜像以继续提供支持。

用户应考虑迁移到Quay-based镜像，这些镜像得到积极维护，推荐用于生产环境。

🦆 Quay-based镜像（docker.io/camunda/keycloak:quay-* 和 latest）[推荐]

基于Quay.io官方Keycloak镜像，遵循官方Keycloak配置模式，适合偏好上游容器约定的用户。这些镜像标签使用quay-前缀，latest标签指向最新的Quay-based版本，可在Docker Hub公开获取。

✅ 推荐：这些镜像积极维护，推荐用于生产环境。

🚀 优化镜像（docker.io/camunda/keycloak:quay-optimized-*）

Quay-based镜像的预构建配置变体，具有优化的启动时间和Camunda兼容设置：

• 更快启动：构建时将配置嵌入镜像
• Camunda兼容：预配置/auth基础路径，实现与Camunda无缝集成
• 生产就绪：包含AWS JDBC包装器、健康/指标端点，禁用XA事务
• 简化配置：减少运行时环境变量需求

🐳 Bitnami-based镜像（docker.io/camunda/keycloak:bitnami-*）

基于https://hub.docker.com/r/bitnamilegacy/keycloak%EF%BC%8C%E4%BD%BF%E7%94%A8Bitnami%E7%9A%84%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E7%BA%A6%E5%AE%9A%EF%BC%8C%E9%80%82%E5%90%88%E7%86%9F%E6%82%89Bitnami%E7%94%9F%E6%80%81%E7%B3%BB%E7%BB%9F%E7%9A%84%E7%94%A8%E6%88%B7%E3%80%82%E6%A0%87%E7%AD%BE%E4%BD%BF%E7%94%A8%60bitnami-%60%E5%89%8D%E7%BC%80%EF%BC%8C%E5%8F%AF%E5%9C%A8Docker Hub公开获取。为保持向后兼容，这些镜像也提供不带前缀的版本。

注意：这些镜像基于bitnamilegacy仓库，Bitnami不再提供更新。建议生产环境迁移到Quay-based镜像。

🏢 Bitnami企业版镜像（registry.camunda.cloud/keycloak-ee/keycloak:bitnami-ee-*）

基于Bitnami企业版的高级企业级镜像，标签使用bitnami-ee-前缀，仅对授权客户开放，可从Camunda企业 registry获取。为保持向后兼容，这些镜像在专用registry中也提供不带前缀的版本。

所有变体均包含相同的AWS JDBC包装器和Camunda Identity主题功能。

快速开始

• 📘 所有Keycloak相关问题，请参考官方Keycloak文档：[***]

• 🐳🚀 要在容器环境中运行Keycloak，请遵循以下步骤：

前提条件

确保您的机器已安装Docker。

⚙️ 启动容器

Bitnami-based镜像

启动Bitnami-based镜像：

bash
docker run --name mykeycloak -p 8443:8443 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        docker.io/camunda/keycloak:bitnami-26

Quay-based镜像

启动Quay-based镜像：

bash
docker run --name mykeycloak -p 8443:8443 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        docker.io/camunda/keycloak:quay-26 \
        start --hostname=localhost

Keycloak将以生产模式启动，使用安全HTTPS通信，可通过https://localhost:8443访问。

🚀 迁移建议

生产环境强烈推荐使用Quay-based镜像（camunda/keycloak:quay-*），因为：

• ✅ 接收定期安全更新
• ✅ 基于Red Hat官方Keycloak镜像
• ✅ 遵循上游Keycloak约定
• ✅ 积极维护和支持

Bitnami-based镜像仅建议用于：

• ⚠️ 临时迁移场景
• ⚠️ 开发环境（了解更新有限）
• ⚠️ 与现有Bitnami部署的特定兼容性要求

🏷️ Docker Hub可用标签

浏览Docker Hub上Camunda Keycloak Docker镜像的可用标签：

Quay-based镜像（✅ 推荐）

• https://hub.docker.com/r/camunda/keycloak/tags - 基于Quay.io官方Keycloak，使用quay-前缀
• 基础镜像标签：quay.io/keycloak/keycloak

Bitnami-based镜像（⚠️ 遗留 - 有限更新）

• https://hub.docker.com/r/camunda/keycloak/tags - 基于Bitnami Legacy Keycloak
• 基础镜像标签：https://hub.docker.com/r/bitnamilegacy/keycloak/tags

标签约定

Bitnami-based镜像：

• :<基础镜像版本>-<yyyy-mm-dd>-<迭代>：例如 24-2024-03-04-004 🏷️
• :<基础镜像版本>：例如 24.0.1-0
• :<Keycloak主版本>：例如 24

Quay-based镜像（带quay-前缀）：

• :quay-<基础镜像版本>-<yyyy-mm-dd>-<迭代>：例如 quay-24-2024-03-04-004 🏷️
• :quay-<基础镜像版本>：例如 quay-24.0.1
• :quay-<Keycloak主版本>：例如 quay-24
• :quay-optimized-<基础镜像版本>-<yyyy-mm-dd>-<迭代>：例如 quay-optimized-24-2024-03-04-004 🏷️
• :quay-optimized-<基础镜像版本>：例如 quay-optimized-24.0.1
• :quay-optimized-<Keycloak主版本>：例如 quay-optimized-24
• :quay-optimized-latest：最新优化Quay-based镜像
• :latest：对应最新稳定标准（非优化）Quay-based镜像

配置

Bitnami-based镜像

Bitnami Keycloak容器镜像配置详见https://hub.docker.com/r/bitnami/keycloak%E3%80%82

环境变量迁移（Bitnami 26.3.3+）

从Keycloak 26.3.2开始，以下遗留环境变量已弃用，改用原生KC_*变量：

更多环境变量信息详见https://github.com/bitnami/containers/blob/main/bitnami/keycloak/README.md%E3%80%82

Quay-based镜像

官方Keycloak容器配置文档：keycloak.org/server/containers。

镜像子类型

Quay-based镜像提供两种子类型：

标准镜像（quay-<version>）

• 通过环境变量运行时配置
• 支持所有Keycloak配置选项，灵活性高
• 适合开发和自定义配置

优化镜像（quay-optimized-<version>）

• 预构建配置，启动更快
• AWS JDBC包装器和常用设置嵌入镜像
• Camunda兼容路径配置，/auth基础路径
• 强制AWS包装器：所有数据库连接必须使用jdbc:aws-wrapper:postgresql://... URL
• 推荐用于生产部署，尤其是配合Keycloak Operator
• 减少所需运行时环境变量

Camunda路径配置（--http-relative-path=/auth）

/auth路径预配置用于与Camunda Platform 8无缝集成，Camunda期望Keycloak在此基础路径上可用。此配置：

• ✅ 确保与Camunda认证流程兼容
• ✅ 匹配Camunda组件预期的默认路径
• ⚠️ 重要：所有Keycloak端点将带有/auth前缀（例如 /auth/realms/master）
• ⚠️ 如不与Camunda一起部署，考虑使用标准镜像获取根路径访问

XA事务禁用（--transaction-xa-enabled=false）

优化镜像中禁用XA事务的原因：

• AWS Aurora PostgreSQL不支持分布式事务
• 提升性能并降低复杂度
• 云原生部署推荐配置

构建参数和配置差异的技术细节详见DEVELOPER.md。

IAM角色用于服务账户（IRSA）支持

从Keycloak 21及更高版本开始，可使用镜像中包含的AWS Advanced JDBC包装器启用IRSA（服务账户IAM角色）。详见Keycloak文档。

Kubernetes配置

Bitnami-based镜像

Kubernetes中使用IRSA，配置以下环境变量：

yaml
- name: KEYCLOAK_EXTRA_ARGS
  value: "--db-driver=software.amazon.jdbc.Driver --transaction-xa-enabled=false --log-level=INFO,software.amazon.jdbc:INFO"
- name: KEYCLOAK_JDBC_PARAMS
  value: "wrapperPlugins=iam"
- name: KEYCLOAK_JDBC_DRIVER
  value: "aws-wrapper:postgresql"

- name: KEYCLOAK_DATABASE_USER
  value: db-user-name
- name: KEYCLOAK_DATABASE_NAME
  value: db-name
- name: KEYCLOAK_DATABASE_HOST
  value: db-host
- name: KEYCLOAK_DATABASE_PORT
  value: 5432

- name: KEYCLOAK_ENABLE_STATISTICS
  value: "true"
- name: KEYCLOAK_ENABLE_HEALTH_ENDPOINTS
  value: "true"

Quay-based镜像

Kubernetes中使用IRSA，配置以下环境变量：

标准镜像（quay-<version>）

yaml
- name: KC_DB
  value: postgres
- name: KC_DB_DRIVER
  value: software.amazon.jdbc.Driver
- name: KC_DB_URL
  value: "jdbc:aws-wrapper:postgresql://db-host:5432/db-name?wrapperPlugins=iam"
- name: KC_DB_USERNAME
  value: db-user-name
- name: KC_TRANSACTION_XA_ENABLED
  value: "false"
- name: KC_HEALTH_ENABLED
  value: "true"
- name: KC_METRICS_ENABLED
  value: "true"

优化镜像（quay-optimized-<version>）

优化镜像预配置AWS JDBC包装器驱动，必须使用aws-wrapper URL格式，即使非IRSA部署：

yaml
# IRSA（IAM认证）
- name: KC_DB_URL
  value: "jdbc:aws-wrapper:postgresql://db-host:5432/db-name?wrapperPlugins=iam"
- name: KC_DB_USERNAME
  value: db-user-name
# IRSA无需KC_DB_PASSWORD

# 传统用户名/密码认证
- name: KC_DB_URL
  value: "jdbc:aws-wrapper:postgresql://db-host:5432/db-name"
- name: KC_DB_USERNAME
  value: db-user-name
- name: KC_DB_PASSWORD
  value: db-password

# 注意：数据库驱动、健康/指标和XA设置已预配置

不要忘记将部署/statefulset的serviceAccountName设置为带有IRSA注解的服务账户。

Helm Chart使用

要在Helm Chart中使用此镜像，可使用bitnami/keycloak并更新镜像及添加必要环境变量：

Bitnami-based镜像 ⚠️ [遗留 - 考虑迁移]

⚠️ 迁移建议：新部署建议使用Keycloak Operator配合Quay-based镜像，提供更好的长期支持并遵循Keycloak最佳实践。

现有Bitnami部署可使用bitnami/keycloak Helm Chart：

yaml
image: docker.io/camunda/keycloak:bitnami-26
extraEnvVars:
  - name: KEYCLOAK_EXTRA_ARGS
    value: "--db-driver=software.amazon.jdbc.Driver --transaction-xa-enabled=false --log-level=INFO,software.amazon.jdbc:INFO"
  - name: KEYCLOAK_JDBC_PARAMS
    value: "wrapperPlugins=iam"
  - name: KEYCLOAK_JDBC_DRIVER
    value: "aws-wrapper:postgresql"
externalDatabase:
  host: "aurora.rds.your.domain"
  port: 5432
  user: keycloak
  database: keycloak

global:
  security:
    # 以下参数因https://github.com/bitnami/charts/issues/30850需要
    # 不会降低安全性，仅允许Bitnami镜像的分支（如本镜像）被Chart部署
    allowInsecureImages: true

Quay-based镜像 [推荐]

生产环境Quay-based镜像推荐使用官方Keycloak Operator，提供更好的生命周期管理并遵循Keycloak最佳实践：

📋 Keycloak Operator安装：[***]

Operator允许声明式部署Keycloak实例并提供适当的配置管理。以下是使用Camunda镜像的Keycloak自定义资源示例：

yaml
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
  namespace: keycloak
spec:
  image: docker.io/camunda/keycloak:quay-optimized-26
  instances: 3
  db:
    vendor: postgres
    host: aurora.rds.your.domain
    port: 5432
    database: keycloak
    usernameSecret:
      name: keycloak-db-secret
      key: username
    # IRSA场景，省略passwordSecret以使用IAM认证
  # IRSA支持仅适用于优化镜像
  unsupported:
    podTemplate:
      spec:
        serviceAccountName: keycloak-service-account
        containers:
          - name: keycloak
            env:
              - name: KC_DB_URL
                value: "jdbc:aws-wrapper:postgresql://aurora.rds.your.domain:5432/keycloak?wrapperPlugins=iam"

⚠️ Keycloak Operator重要说明

使用标准镜像（quay-<version>或latest）配合Key