在Kubernetes中以readOnlyRootFilesystem: true运行Keycloak的问题

问题 #

我正在尝试基于Keycloak Docker镜像制作带安全加固的Helm Chart，要求在Pod的securityContext中设置readOnlyRootFilesystem: true。我遵循《Running Keycloak in a container》指南操作，希望保留通过环境变量动态配置Keycloak的能力（参考《All configuration》文档）。

根据指南，标准Keycloak容器无法直接以readOnlyRootFilesystem: true运行，因为它需要基于配置构建，因此我需自行构建优化镜像，示例Dockerfile如下：

FROM quay.io/keycloak/keycloak:latest as builder

# Enable health and metrics support
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor
ENV KC_DB=postgres
ENV KC_HOSTNAME_STRICT=false
ENV KC_HOSTNAME_STRICT_HTTPS=false
ENV KC_CACHE_STACK=kubernetes
ENV JAVA_OPTS_APPEND=-Djgroups.dns.query=keycloak-service-internal-headless
ENV KC_PROXY=edge
# ENV KC_HTTP_RELATIVE_PATH=/kc
ENV KC_HTTP_ENABLED=true
ENV PROXY_ADDRESS_FORWARDING=true

WORKDIR /opt/keycloak

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:latest
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
ENV KC_DB=postgres
ENV KC_DB_URL=<DBURL>
ENV KC_DB_USERNAME=<DBUSERNAME>
ENV KC_DB_PASSWORD=<DBPASSWORD>

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

但发现构建优化镜像时，配置项会被打包进generated-bytecode.jar等文件，使用start --optimized启动时，Helm生成的Kubernetes清单中的环境变量配置会被忽略。例如KC_HTTP_RELATIVE_PATH在构建时设置后，后续无法通过环境变量修改。

请问：

1. 构建Keycloak优化镜像时，哪些配置项可动态设置，哪些不可？是否有官方指引说明？
2. 有无其他合规方式，可在只读文件系统下运行Keycloak，并支持声明式动态配置？

回答 #

1. 可动态/不可动态配置的项及官方逻辑 #

Keycloak的配置项按生效阶段分为两类：

• 不可动态修改（构建时固化）：涉及底层架构、扩展加载、核心服务初始化的配置，比如KC_DB（数据库类型）、KC_HTTP_RELATIVE_PATH（相对路径）、KC_CACHE_STACK（缓存栈）、KC_HEALTH_ENABLED/KC_METRICS_ENABLED（健康/指标开关）。这类配置会触发代码生成或扩展初始化，kc.sh build阶段会被编译进generated-bytecode.jar，运行时无法通过环境变量覆盖。
• 可动态修改（运行时生效）：主要是连接类、动态参数类配置，比如KC_DB_URL、KC_DB_USERNAME、KC_DB_PASSWORD（数据库连接信息）、KC_HOSTNAME（主机名）、KC_PROXY（代理模式）、JAVA_OPTS_APPEND（JVM参数）、KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD（管理员账号）。这类配置仅做参数替换，不影响代码结构，运行时通过环境变量设置依然有效。

官方核心逻辑是：任何需要触发代码生成、扩展安装或核心服务初始化的配置，必须在构建阶段确定；仅涉及参数替换、连接配置的项可在运行时动态调整，容器构建章节明确提到build命令会预编译配置以优化启动速度，因此构建时的配置会固化到镜像中。

2. 只读文件系统下支持动态配置的合规方案 #

方案一：基础优化镜像+运行时挂载可写目录

1. 构建仅包含固化配置的基础镜像：只设置KC_DB、KC_CACHE_STACK这类必须在构建阶段确定的项，不包含动态参数。
2. 在Kubernetes中挂载Keycloak所需的可写目录：Keycloak运行时需要可写的目录为/opt/keycloak/data（临时数据、会话存储）、/opt/keycloak/log（日志），将这些目录挂载到emptyDir或临时卷，同时启用readOnlyRootFilesystem: true。
3. 运行时通过环境变量传入所有动态配置项，启动命令使用start --optimized。

示例Pod配置片段：

securityContext:
  readOnlyRootFilesystem: true
volumes:
  - name: keycloak-data
    emptyDir: {}
  - name: keycloak-log
    emptyDir: {}
volumeMounts:
  - name: keycloak-data
    mountPath: /opt/keycloak/data
  - name: keycloak-log
    mountPath: /opt/keycloak/log

方案二：使用Keycloak Operator管理

Keycloak Operator支持声明式管理Keycloak实例：

• 自动处理只读文件系统所需的卷挂载（data、log目录）。
• 所有配置通过Keycloak自定义资源（CR）声明，Operator自动将配置转换为环境变量或配置文件，无需自行构建镜像。
• 支持动态更新配置（修改CR后自动滚动更新Pod），同时满足文件系统只读的安全要求，符合Kubernetes声明式运维最佳实践。

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