コンテナでKeycloakを実行する

コンテナイメージからKeycloakを実行する方法を学びます

このガイドでは、コンテナを実行する上で最高のエクスペリエンスを提供するために、Keycloakコンテナイメージを最適化して実行する方法について説明します。

カスタマイズおよび最適化されたコンテナイメージの作成

デフォルトのKeycloakコンテナイメージは、構成および最適化される準備ができて出荷されます。

Keycloakコンテナを最適に起動するには、コンテナのビルド中にbuildステップを実行してイメージをビルドします。このステップにより、コンテナイメージの後続のすべての起動フェーズで時間を節約できます。

最適化されたKeycloak Containerfileの記述

次のContainerfileは、ヘルスおよびメトリクスエンドポイントを有効にし、トークン交換機能を有効にし、PostgreSQLデータベースを使用する、事前構成済みのKeycloakイメージを作成します。

Containerfile

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

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 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>
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

ビルドプロセスには複数のステージが含まれています

buildコマンドを実行して、最適化されたイメージを作成するためのサーバービルドオプションを設定します。
buildステージで生成されたファイルは、新しいイメージにコピーされます。
最終イメージでは、ホスト名とデータベースの追加の構成オプションが設定されているため、コンテナを実行するときに再度設定する必要はありません。
エントリポイントでは、kc.shはすべてのディストリビューションサブコマンドへのアクセスを有効にします。

カスタムプロバイダーをインストールするには、/opt/keycloak/providersディレクトリにJARファイルを含めるステップを定義するだけです。このステップは、以下のようにbuildコマンドをRUNする行の前に配置する必要があります

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
FROM quay.io/keycloak/keycloak:latest 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

追加のRPMパッケージのインストール

FROM quay.io/keycloak/keycloakステージで新しいソフトウェアをインストールしようとすると、microdnf、dnf、さらにはrpmもインストールされていないことに気付くでしょう。また、非常に少数のパッケージしか利用できず、bashシェルと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 quay.io/keycloak/keycloak
COPY --from=ubi-micro-build /etc/pki /etc/pki

ubi-microによって確立されたこの2段階パターンに従うと、どうしても必要な場合に新しいRPMをインストールできます

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 quay.io/keycloak/keycloak
COPY --from=ubi-micro-build /mnt/rootfs /

このアプローチでは、chroot、/mnt/rootfsを使用するため、指定したパッケージとその依存関係のみがインストールされ、推測することなく2番目のステージに簡単にコピーできます。

一部のパッケージには、依存関係の大きなツリーがあります。新しいRPMをインストールすると、意図せずにコンテナの攻撃対象領域を増やす可能性があります。インストールされているパッケージのリストを注意深く確認してください。

コンテナイメージのビルド

実際のコンテナイメージをビルドするには、Containerfileを含むディレクトリから次のコマンドを実行します

podman|docker build . -t mykeycloak

最適化されたKeycloakコンテナイメージの起動

イメージを起動するには、次を実行します

podman|docker 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

Keycloakは、セキュアなHTTPS通信のみを使用して、本番モードで起動し、https://#:8443で利用できます。

ヘルスチェックエンドポイントは、https://#:9000/health、https://#:9000/health/ready、およびhttps://#:9000/health/liveで利用できます。

https://#:9000/metricsを開くと、監視ソリューションで使用できる運用メトリクスを含むページが表示されます。

コンテナを別のポートに公開する

デフォルトでは、サーバーはポート8080および8443を使用してhttpおよびhttpsリクエストをリッスンしています。

別のポートを使用してコンテナを公開する場合は、それに応じてhostnameを設定する必要があります

デフォルトポート以外のポートを使用してコンテナを公開する

podman|docker run --name mykeycloak -p 3000:8443 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=https://#:3000

hostnameオプションを完全なURLに設定すると、https://#:3000でサーバーにアクセスできるようになります。

開発モードでKeycloakを試す

開発またはテスト目的でコンテナからKeycloakを試す最も簡単な方法は、開発モードを使用することです。start-devコマンドを使用します

podman|docker run --name mykeycloak -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        quay.io/keycloak/keycloak:latest \
        start-dev

このコマンドを呼び出すと、Keycloakサーバーが開発モードで起動します。

このモードは、安全でないデフォルトがあるため、本番環境では厳密に避ける必要があります。本番環境でのKeycloakの実行の詳細については、本番環境向けKeycloakの構成を参照してください。

標準のKeycloakコンテナの実行

イミュータブルインフラストラクチャなどの概念に従い、コンテナは定期的に再プロビジョニングする必要があります。これらの環境では、コンテナの起動が高速である必要があるため、前のセクションで説明したように最適化されたイメージを作成する必要があります。ただし、環境に異なる要件がある場合は、startコマンドを実行するだけで標準のKeycloakイメージを実行できます。例：

podman|docker run --name mykeycloak -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        quay.io/keycloak/keycloak:latest \
        start \
        --db=postgres --features=token-exchange \
        --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> \
        --https-key-store-file=<file> --https-key-store-password=<password>

このコマンドを実行すると、Keycloakサーバーが起動し、最初にビルドオプションを検出して適用します。例では、--db=postgres --features=token-exchange行は、データベースベンダーをPostgreSQLに設定し、トークン交換機能を有効にします。

次に、Keycloakが起動し、特定の環境の構成を適用します。このアプローチは、起動時間を大幅に増加させ、可変のイメージを作成します。これはベストプラクティスではありません。

コンテナで実行する場合の初期管理者認証情報の提供

Keycloakは、ローカルネットワーク接続からの初期管理者ユーザーの作成のみを許可します。これはコンテナで実行する場合は当てはまらないため、イメージを実行するときに次の環境変数を指定する必要があります

# setting the admin username
-e KC_BOOTSTRAP_ADMIN_USERNAME=<admin-user-name>

# setting the initial password
-e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me

起動時のレルムのインポート

Keycloakコンテナには、/opt/keycloak/data/importディレクトリがあります。ボリュームマウントまたはその他の手段で1つ以上のインポートファイルをそのディレクトリに配置し、起動引数--import-realmを追加すると、Keycloakコンテナは起動時にそのデータをインポートします！これは、開発モードでのみ意味があるかもしれません。

podman|docker run --name keycloak_unoptimized -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -v /path/to/realm/data:/opt/keycloak/data/import \
        quay.io/keycloak/keycloak:latest \
        start-dev --import-realm

管理者ブートストラッププロセスの強化に関するオープンなGitHubディスカッションに自由に参加してください。

異なるメモリ設定の指定

Keycloakコンテナは、初期ヒープサイズと最大ヒープサイズのハードコードされた値を指定する代わりに、コンテナの総メモリに対する相対値を使用します。この動作は、JVMオプション-XX:MaxRAMPercentage=70および-XX:InitialRAMPercentage=50によって実現されます。

-XX:MaxRAMPercentageオプションは、最大ヒープサイズをコンテナ総メモリの70％として表します。-XX:InitialRAMPercentageオプションは、初期ヒープサイズをコンテナ総メモリの50％として表します。これらの値は、Keycloakメモリ管理の詳細な分析に基づいて選択されました。

ヒープサイズはコンテナの総メモリに基づいて動的に計算されるため、コンテナのメモリ制限を常に設定する必要があります。以前は、最大ヒープサイズは512 MBに設定されていましたが、同様の値に近づけるには、メモリ制限を少なくとも750 MBに設定する必要があります。小規模な本番環境対応のデプロイメントの場合、推奨されるメモリ制限は2 GBです。

ヒープに関連するJVMオプションは、環境変数JAVA_OPTS_KC_HEAPを設定することでオーバーライドできます。JAVA_OPTS_KC_HEAPのデフォルト値は、kc.shまたはkc.batスクリプトのソースコードで見つけることができます。

たとえば、環境変数とメモリ制限を次のように指定できます

podman|docker run --name mykeycloak -p 8080:8080 -m 1g \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
        quay.io/keycloak/keycloak:latest \
        start-dev

メモリ制限が設定されていない場合、ヒープサイズはコンテナ総メモリの70％まで増加する可能性があるため、メモリ消費量が急速に増加します。JVMがメモリを割り当てると、現在のKeycloak GC設定ではOSに reluctantly 返されます。