kc.sh --help2020年12月16日 Keycloakチーム
世界は急速に変化しており、ITはその原動力の重要な一部となっています。企業がインフラストラクチャをクラウドに移行し始めるにつれて、セキュリティはこの移行を成功させるための重要な要素になります。
この度、KeycloakがQuarkus上で動作するようになったことを発表いたします。Quarkusは、Kubernetesおよびクラウドネイティブスタックであり、最高のJavaライブラリと標準を利用して、ユーザビリティ、スケーラビリティに重点を置き、ハイブリッドクラウドでの実行に最適化されたクラウドフレンドリーなディストリビューションをユーザーに提供します。
Keycloak.Xとしても知られるこの新しいディストリビューション形式は、以下を提供します。
起動時間の短縮
メモリフットプリントの削減
コンテナファーストのアプローチ
より良い開発者体験
ユーザビリティに重点
Keycloakは基本的にJavaアプリケーションであり、現在はWildfly（JEE）アプリケーションサーバー上で動作しています。これまで、それがKeycloak Serverを一般向けにリリースしてきた方法です。
Wildflyはおそらく最も最適化され、使いやすく、最高のパフォーマンスを発揮するJEEアプリケーションサーバーですが、よりクラウドネイティブな方法で実行するための現在の要件は私たちを前進させます。QuarkusはJavaおよびコンテナファーストのスタックであり、KubernetesやOpenshiftのようなプラットフォームに焦点を当てたハイブリッドクラウドでの実行にQuarkusを最適なものにするすべての機能をKeycloakにもたらすための、より自然な道筋を提供します。
Quarkusの詳細については、Webサイトhttps://quarkus.io/をご覧ください。
Quarkusでは、KeycloakはWildflyディストリビューションと比較してはるかにシンプルなスタックを持つ通常のJavaアプリケーションです。
新しいディストリビューションでは、ユーザーはサーバーの構成と起動、およびその他の一般的な操作を実行する際に、より良いエクスペリエンスを期待できます。
豊富なコマンドラインインターフェースの導入により、Keycloakのインストールと使用がはるかに簡単になります。
ディストリビューションはディレクトリ数が少なくなりシンプルになり、ディストリビューションの合計サイズは現在のWildFlyベースのディストリビューションのほぼ半分です。
Quarkusを活用することで、Keycloakはサーバーの起動時間、メモリフットプリント（低RSS）を大幅に削減し、Vert.xを通じてより優れたランタイムパフォーマンスを実現しました。
これらの側面はすべて、最適なランタイム環境を提供し、コストを削減するためにリソース使用率を最適化する必要があるハイブリッドクラウドにデプロイする場合に重要です。
Keycloak Operatorと組み合わせることで、Keycloakをハイブリッドクラウドにデプロイすることがより簡単になるはずです。
単純なコンテナの起動についても同様です。
Quarkusは、さまざまなライブラリへの印象的な数の統合を備えた、開発者向けの豊富なエコシステムを提供します。
柔軟性はKeycloakの主な特徴の1つであり、Quarkusを使用することで、開発者にとってより良いエクスペリエンスを提供できると期待しています。
Keycloak.Xディストリビューションのzipまたはtar.gzファイルをhttps://keycloak.dokyumento.jp/downloadsからダウンロードして展開します。
binディレクトリは、すべてのバイナリが配置される場所であり、基本的には新しいKeycloak CLIといくつかのユーティリティです。
confディレクトリは、名前が示すように、構成ファイルが配置される場所です。サーバーを構成するために、このディレクトリ内のkeycloak.propertiesファイルを使用することも、使用しないこともできます。詳細については、後で構成について詳しく説明するときに説明します。
providersディレクトリは、カスタムプロバイダーまたはテーマjarを含むJARファイルをデプロイする必要がある場所です。
私たちの主な要件の1つは、サーバーを初めて使用するときだけでなく、サーバーが本番環境で実行されている長期的な使用においても、ユーザーエクスペリエンスを向上させることです。
ユーザーが通常サーバーで実行する一般的な操作は実行しやすくなり、適切なデフォルトを提供し、実行中のサーバーに必要な最小限のオプションを設定することで、構成がよりシンプルになるはずです。
Keycloak CLIは、サーバーの起動と構成の変更に使用する必要があるツールです。他のCLIと同様に、自己記述的であり、その使用に関する優れたドキュメントが付属しています。
実行することで
kc.sh --helpこれで、サーバーの起動やレルムのエクスポートなど、実行できるさまざまなアクションを確認したり、サポートされている各コマンドに設定できるさまざまな構成オプションを確認したりできます。
私たちは常にCLIの改善を模索しています。改善に役立つと思われる提案があれば、お気軽にお問い合わせください。
前述したように、デフォルト構成では、サーバーの起動方法にいくつかの条件が課せられています。
サーバーを正常に起動するための主な条件の1つは、HTTPSを構成することです。
ただし、開発目的の場合、Keycloakは開発モードで起動できます。
現在、このモードは基本的に、ローカルキャッシュを使用してHTTPSなしでサーバーを実行できるようにする構成プロファイルです。
kc.sh start-dev上記のコマンドを実行すると、サーバーはhttps://#:8080/で利用可能になるはずです。
将来的には、このモードは、本番環境で実行されている場合には許可されないレルムの一部の構成ポリシーも緩和します。たとえば、クライアントの有効なリダイレクトURIとしてワイルドカードを使用するなどです。
IAMソリューションがいかに重要であり、構成ミスがデプロイメント全体のセキュリティに与える影響を考慮して、Keycloakは現在、デフォルトでセキュアなポリシーを念頭に置いて、可能な限り最小限の構成で配布されています。
アイデアは、本番環境で実行する前に構成をどのように設定する必要があるかについていくつかの重要な制約を課しながら、サーバーを実行するための必要最小限の構成オプションを提供することです。
これは、私たちが改善に取り組んでおり、常に改善しようとしている主要な領域の1つであり、ボイラープレート構成は、少数の構成オプションまたは適切なデフォルトを通じて回避する必要があります。
さまざまな構成オプションは、プロパティファイル、環境変数、またはKeycloak CLIを介した引数を使用して設定できるようになりました。
helpコマンドを実行することで、利用可能な構成オプションを簡単に確認できます。
構成の詳細については、構成設計ドキュメントを確認してください。
構成オプションは、2つのカテゴリに分類されます。
サーバーの起動時にランタイムで設定できるもの
configコマンドを使用してサーバーを構成するときにのみ設定できるもの
例として、HTTPポートを8180に変更する場合は、次を使用できます。
kc.sh --http-port=8180ただし、データベースを変更するには、サーバーを起動する前に、まずconfigコマンドを実行する必要があります。
kc.sh config --db=postgres --db-username=******* --db-password=*******
Kc.sh # then start the server基本的に、サーバーを構成するときに設定できる構成オプションは、サーバーの起動時にも設定できますが、その逆は真実ではなく、データベース構成はその例です。
利用可能な各コマンドに設定できるプロパティを確認するには、helpオプションを確認してください。
実際には、有効なキーペアと証明書を構成しますが、HTTPSの設定方法を理解するために、以下のコマンドを使用して自己署名証明書を生成できます。
ディストリビューションのルートディレクトリで次のコマンドを実行してください。
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上記のコマンドは、confディレクトリ内にserver.keystoreファイルを作成する必要があります。デフォルトでは、Keycloakは、設定されていない場合、このキーストアからキーと証明書をロードします。
その後、次のようにサーバーを実行できます。
kc.shデータベース構成ははるかにシンプルです。いくつかの簡単なコマンドライン引数だけでデータベースを変更できます。
kc.sh config --db=postgres && kc.sh --db-username=**** --db-password=****各データベースについて、JDBC URL、ドライバー、データベース名、およびダイアレクトの適切なデフォルトを提供しています。デフォルトで問題ない場合は、これらのオプションを指定する必要はありません。
上記の例では、サーバーはデータベース名がkeycloakであるlocalhostで実行されているPostgreSQLサービスに接続します。
もちろん、本番環境で実行する場合は、通常、JDBC URLやその他のパラメーターをカスタマイズする必要があるため、次のようにサーバーを起動できます。
kc.sh --db-url=jdbc:postgresql://<host>/<database> \
--db-username=****** \
--db-password=******または、引き続きデフォルトのJDBC URLに依存し、ホストとデータベースの両方を次のように設定します。
kc.sh -Dkc.db.url.host=<host> \
-Dkc.db.url.database=<database>
--db-username=******
--db-password=******当面の間、クラスタリングとHAデプロイメントには引き続きInfinispanとJGroupsを使用しています。
ただし、構成は現在、Wildfly Infinispanサブシステムのように抽象化を使用するのではなく、Infinispanのネイティブ構成を使用しています。これにより、構成、サポート、およびドキュメントに関して、はるかに柔軟性が向上するはずです。
構成も簡素化されており、サーバーがデプロイされているさまざまなプラットフォームに適したデフォルトが得られるはずです。
デフォルトでは、クラスタリングが有効になっており、デフォルト構成を使用してKeycloakクラスターを構築する準備ができています。
デフォルト構成はconfディレクトリにあり、ファイル名はcluster-default.xmlです。
同じディレクトリに、すべてのキャッシュをローカルに構成し、クラスタリングを行わないcluster-local.xmlファイルもあります。この構成を使用するには、次のコマンドを実行します。
kc.sh --cluster=localディストリビューションに同梱されているcluster-local.xmlファイルやcluster-defaultファイルのように、confディレクトリにcluster-プレフィックスを持つファイルを作成するだけで、独自のキャッシュ構成を定義できます。
KubernetesやEC2などの特定のプラットフォームに適したデフォルトも提供しています。たとえば、Kubernetesでクラスターを実行するには、次のコマンドを実行できます。
kc.sh -Djgroups.dns.query=<jgroups-ping-service>.<namespace>.<cluster-domain-suffix> --cluster-stack=kubernetesこれらのプラットフォームのデフォルト構成は、Infinispanによって提供されるデフォルトに基づいています。
上記の例では、Kubernetesのデフォルト構成は、ノード通信にUDP、ノード検出にDNS_PINGを使用することに基づいています。デフォルト構成をカスタマイズするために使用できるパラメーターは、Infinispanドキュメントから取得できます。
カスタムプロバイダーとテーマのJARファイルは、providersディレクトリに配置する必要があります。
ただし、カスタムプロバイダーをインストールする際の最適化の恩恵を受けるためには、サーバーを起動する前に、まずconfigコマンドを実行する必要があります。
kc.sh config
kc.sh # then start the server基本的に、SPI実装はサーバーを構成するときに解決されるため、起動時の起動時間とメモリが節約されます。カスタムプロバイダーをインストールするためにconfigコマンドを実行すると、それらはサーバーに静的にリンクされます。
Dockerを使用してKeycloakを実行するには、次のコマンドを使用できます。
docker run --name keycloak -p 8080:8080 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
quay.io/keycloak/keycloak-x \
start-dev予想どおり、コンテナは開発モードで実行されます。
コマンドライン引数を渡すことで、Keycloak.Xディストリビューションを使用する場合と同じようにサーバーを実行できます。
サーバーイメージに永続化したい追加構成でコンテナを構成するには、次のように--auto-configオプションを使用できます。
docker run --name keycloak -p 8080:8080 \
-e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
quay.io/keycloak/keycloak-x \
--auto-config \
--db=postgres -Dkc.db.url.host=$DB_HOST --db-username=keycloak --db-password=change_me --http-enabled=true上記のコマンドは、指定されたDB_HOSTでリッスンしているPostgreSQLデータベースを使用してサーバーを実行するのに十分なはずです。コンテナが作成されると、後続の再起動では構成フェーズを再度実行することはありませんが、以前に定義された構成でサーバーを起動するだけです。
ただし、推奨されるのは、常にこのイメージに基づいて独自のイメージを作成することです。そうすることで、カスタムプロバイダーやテーマのデプロイなど、より多くのカスタマイズを実行したり、構成手順を排除して起動時間を改善したりできます。
詳細と例については、https://github.com/keycloak/keycloak-containers/tree/master/server-xを参照してください。
これは、QuarkusとWildflyで実行されているKeycloak間の非常に簡単な比較のためのいくつかの数値です。
両方のディストリビューションはOpenJDK 11、PostgreSQLデータベースを使用して実行されており、数値は各ディストリビューションの10回の連続実行の平均です。
テストシナリオには、サーバーを初めて実行する場合と、データベースがすでに初期化されている場合の両方が含まれます。
ディストリビューション |
起動時間（秒） |
メモリフットプリント（RSS/MB） |
||
最初 |
2回目以降 |
最初 |
2回目以降 |
|
Wildfly |
12.1 |
8.1 |
646 |
512 |
Quarkus |
7.6 |
3.1 |
428 |
320 |
数値はそれ自体を物語るはずであり、人々はこれらの数値がKeycloak.Xの各リリースで改善されることを期待する必要があります。
ただし、MBを削減するだけでなく、メモリ使用量を最適化する方法も重要です。64MBのヒープを使用して両方のサーバーを実行すると、Wildflyで実行している場合、多くのガベージコレクションが発生し、最終的にサーバーが起動に失敗する可能性があることに気付くはずです。一方、Keycloak.Xで同じヒープサイズを使用すると、サーバーを実行できます。もちろん、このヒープサイズの使用はユースケースによっては現実的ではありませんが、今後何を期待できるかについて良いアイデアが得られます。
パフォーマンスに関しては、この最初のリリースでは、主な焦点は起動時間とメモリ消費量でした。ランタイムパフォーマンスはWIPであり、Keycloak.XがVert.X上で実行されているという事実により、結果は有望です。
一般的に、私たちはまだ旅の始まりに過ぎません。KeycloakがQuarkus上にネイティブディストリビューションを持つようになると、さらに高速な起動時間、より少ないメモリ消費、およびより少ないリソースで全体的に優れたパフォーマンスを期待できます。
これは、Keycloakを使用する人々に、よりクラウドフレンドリーなエクスペリエンスを提供するための私たちの旅の始まりに過ぎません。
Keycloak.Xはプレビューディストリビューションであり、コミュニティの助けを借りて、メインディストリビューションになるまで常に改善しています。この旅の間のフィードバックをお待ちしております。
Keycloak.Xディストリビューションを補完するために行われている多くの重要な作業があります。
ゼロダウンタイムアップグレード
ネイティブイメージのサポート
開発者エクスペリエンスの向上
ドキュメントの拡充
Keycloakの使用体験を向上させ続けるために、皆様のサポートとフィードバックをお願いいたします。
これはコミュニティによる共同の努力の結果であり、私たちが受けたすべての貢献に感謝し、強調したいと思います。
特別な感謝を
Quarkusチーム
Stuart Douglas
Sanne Grinovero
Guillaume Smet
Backbase
Dmitry Telegin (https://github.com/dteleguin)
Matthew Conners (https://github.com/bb-matthewc)
そして、構成設計ドキュメントにご協力いただいたすべての方々に感謝いたします。