Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 5 章 在容器中运行红帽构建的 Keycloak

从容器镜像运行红帽构建的 Keycloak。

本章论述了如何优化并运行红帽构建的 Keycloak 容器镜像，以提供运行容器的最佳体验。

警告

本章只适用于构建您在 OpenShift 环境中运行的镜像。此镜像只支持 OpenShift 环境。如果您在其他 Kubernetes 发行版本中运行它，则不支持它。

5.1. 创建自定义和优化的容器镜像
复制链接

默认的红帽 Keycloak 容器镜像构建已准备好配置和优化。

为了获得红帽构建的 Keycloak 容器的最佳启动，请在容器构建过程中运行 构建步骤 构建镜像。此步骤将在容器镜像的后续开始阶段节省时间。

以下 Containerfile 创建一个预先配置的红帽 Keycloak 镜像构建，它启用了健康和指标端点，启用令牌交换功能，并使用 PostgreSQL 数据库。

Containerfile ：

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2 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

WORKDIR /opt/keycloak
# for demonstration purposes only, please make sure to use proper certificates in production instead
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
RUN /opt/keycloak/bin/kc.sh build

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2
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>
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
Copy to Clipboard Toggle word wrap

构建过程包含多个阶段：

  • 运行 build 命令，以设置服务器构建选项以创建优化的镜像。
  • 由 构建阶段 生成的文件复制到新镜像中。
  • 在最终镜像中，设置主机名和数据库的额外配置选项，以便在运行容器时不需要再次设置它们。
  • 在入口点中，kc.sh 可让您访问所有 distribution 子命令。

要安装自定义提供程序，您只需要定义一个步骤，以将 JAR 文件包含在 /opt/keycloak/providers 目录中。此步骤必须放在 RUNs build 命令的行前，如下所示： 

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2 as builder

...

# Add the provider JAR file to the providers directory
ADD --chown=keycloak:keycloak --chmod=644 <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar

...

# Context: RUN the build command
RUN /opt/keycloak/bin/kc.sh build
Copy to Clipboard Toggle word wrap

5.1.2. 安装其他 RPM 软件包
复制链接

如果您尝试在 FROM registry.redhat.io/rhbk/keycloak-rhel9 中安装新软件，您会注意到 microdnf、dnf 甚至 rpm 也不会被安装。另外，很少的软件包可用，只可用于 bash shell，并运行红帽 Keycloak 本身构建。这是因为安全强化措施减少了红帽构建的 Keycloak 容器的攻击面。

首先，请考虑您的用例是否可以以不同的方式实现，因此请避免将新 RPM 安装到最终容器中：

  • Containerfile 中的 RUN curl 指令可以替换为 ADD，因为该指令原生支持远程 URL。
  • 一些常见的 CLI 工具可以通过识别 Linux 文件系统来替代。例如，ip addr show tap0 变成 cat /sys/class/net/tap0/address
  • 需要 RPM 的任务可以移到镜像构建的前阶段，以及复制的结果。

下面是一个示例。在以前的构建阶段运行 update-ca-trust，然后复制结果转发： 

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt
RUN update-ca-trust

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /etc/pki /etc/pki
Copy to Clipboard Toggle word wrap

如果绝对需要，可以安装新的 RPM，遵循由 ubi-micro 建立的双阶段模式： 

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
RUN mkdir -p /mnt/rootfs
RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y && \
    dnf --installroot /mnt/rootfs clean all && \
    rpm --root /mnt/rootfs -e --nodeps setup

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /mnt/rootfs /
Copy to Clipboard Toggle word wrap

这种方法使用 chroot /mnt/rootfs，因此仅安装您指定的软件包及其依赖项，因此无需猜测即可轻松复制到第二个阶段。

警告

有些软件包具有大量依赖项。通过安装新的 RPM，您可能意外地增加容器的受攻击面。仔细检查安装的软件包列表。

5.1.3. 自定义 ENTRYPOINT shell 脚本
复制链接

如果您使用自定义入口点脚本，请使用 exec 启动 Red Hat build of Keycloak，以便它接收对安全关闭至关重要的终止信号。

ENTRYPOINT shell 脚本的正确方法

#!/bin/bash

# (add your custom logic here)

# Run the 'exec' command as the last step of the script.
# As it replaces the current shell process, no additional shell commands will run after the 'exec' command.
exec /opt/keycloak/bin/kc.sh start "$@"
Copy to Clipboard Toggle word wrap

警告

如果没有 exec，shell 脚本会在容器中保留 PID 1，并阻止 SIGTERM 等信号访问红帽构建的 Keycloak。这可防止安全关闭，并可能导致缓存不一致或数据丢失。

5.1.4. 构建容器镜像
复制链接

要构建实际的容器镜像，请从包含 Containerfile 的目录运行以下命令： 

podman build . -t mykeycloak
Copy to Clipboard Toggle word wrap
注意

Podman 只能用于创建或自定义镜像。在生产环境中运行红帽构建的 Keycloak 不支持 podman。

5.1.5. 启动优化的红帽构建的 Keycloak 容器镜像
复制链接

要启动镜像，请运行： 

podman run --name mykeycloak -p 8443:8443 -p 9000:9000 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=localhost
Copy to Clipboard Toggle word wrap

红帽构建的 Keycloak 以生产模式启动，仅使用安全 HTTPS 通信，并可在 https://localhost:8443 中提供。

健康检查端点位于 https://localhost:9000/health、https://localhost:9000/health/ready 和 https://localhost:9000/health/live。

打开 https://localhost:9000/metrics 会导致一个页面，其中包含您的监控解决方案可以使用的操作指标。

5.1.6. Docker 的已知问题
复制链接

  • 如果 RUN dnf install 命令似乎需要过多的时间，则您的 Docker systemd 服务可能会错误地配置了文件限制设置 LimitNOFILE。更新服务配置以使用更好的值，如 1024000，或者在 RUN 命令中使用 ulimit ： 
...
RUN ulimit -n 1024000 && dnf install --installroot ...
...
Copy to Clipboard Toggle word wrap
  • 如果您包含提供商 JAR，并且容器无法使用供应商 JAR 已更改的通知 进行启动 --optimized，这是由于 Docker 截断，或者修改 以构建 命令记录到运行时所看到的内容的文件修改时间戳。在这种情况下，您需要在运行构建前强制镜像使用带有 touch 命令选择的已知时间戳： 
...
# ADD or copy one or more provider jars
ADD --chown=keycloak:keycloak --chmod=644 some-jar.jar /opt/keycloak/providers/
...
RUN touch -m --date=@1743465600 /opt/keycloak/providers/*
RUN /opt/keycloak/bin/kc.sh build
...
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat