Keycloak.X 發行版本介紹

2020 年 12 月 16 日，Keycloak 團隊

世界變化快速，而 IT 一直是重要的推動力。隨著公司開始將基礎設施轉移到雲端，安全性成為這趟旅程成功的關鍵因素。

我們很自豪地宣布，Keycloak 現在基於 Quarkus 運行，Quarkus 是一個 Kubernetes 和雲原生堆疊，採用最佳的 Java 函式庫和標準，為我們的使用者提供一個雲端友善的發行版本，它著重於可用性、可擴展性，並針對在混合雲中運行進行了最佳化。

這個新的發行版本格式也稱為 Keycloak.X，它提供了：

為什麼選擇 Quarkus？

Keycloak 本質上是一個 Java 應用程式，目前基於 Wildfly (JEE) 應用程式伺服器運行。到目前為止，我們一直以這種方式發布 Keycloak 伺服器供一般使用。

雖然 Wildfly 可能是最佳化、易於使用且效能最佳的 JEE 應用程式伺服器，但我們現在對於以更雲原生方式運行的需求推動我們向前邁進。Quarkus 作為 Java 和容器優先的堆疊，為 Keycloak 提供更自然的途徑，以實現所有使 Quarkus 成為在混合雲中運行的完美選擇的功能，並專注於 Kubernetes 和 Openshift 等平台。

有關 Quarkus 的更多資訊，請瀏覽其網站 https://quarkus.io/。

專注於可用性

在 Quarkus 上，與 Wildfly 發行版本相比，Keycloak 是一個堆疊更簡單的常規 Java 應用程式。

使用新的發行版本，使用者在配置和啟動伺服器以及執行其他常見操作時，應該會有更好的體驗。

引入豐富的命令列介面，讓安裝和使用 Keycloak 更加容易。

更小

該發行版本更簡單，只有幾個目錄，並且發行版本的總大小幾乎是目前基於 WildFly 的發行版本的一半。

透過利用 Quarkus，Keycloak 大幅縮短了伺服器啟動時間、記憶體佔用（低 RSS），並透過 Vert.x 提供了更好的運行時效能。

當部署在混合雲中時，所有這些方面都很重要，在混合雲中應最佳化資源使用，以提供最佳的運行時環境並降低成本。

容器優先和雲原生發行版本

與 Keycloak Operator 結合使用，將 Keycloak 部署到混合雲應該會更容易。

啟動一個簡單的容器也是如此。

開發者體驗

Quarkus 為開發人員提供了豐富的生態系統，其中包含大量與不同函式庫的整合。

靈活性可能是 Keycloak 的主要特點之一，而透過 Quarkus，我們期望為開發人員提供更好的體驗。

安裝

從 https://keycloak.dev.org.tw/downloads 下載並解壓縮 Keycloak.X 發行版本的 zip 或 tar.gz 檔案。

目錄結構

bin 目錄是所有二進制檔的所在位置，基本上是新的 Keycloak CLI 和一些其他公用程式。

conf 目錄，顧名思義，是組態檔的所在位置。您可能會在這個目錄中使用 keycloak.properties 檔案來配置伺服器，也可能不會。稍後當我們更詳細地討論配置時，您會看到更多相關資訊。

providers 目錄是您應該部署自訂提供者或佈景主題 jar 檔案的位置。

命令列介面

我們的主要需求之一是改善使用者首次使用伺服器以及伺服器在生產環境中長期運行時的體驗。

人們通常在伺服器上執行的常見操作更容易執行，並且透過提供良好的預設值並要求最少的選項來運行伺服器，配置應該會更簡單。

Keycloak CLI 是一個您現在應該用來啟動和變更伺服器配置的工具。與任何其他 CLI 一樣，它具有自我描述性，並有良好的使用說明文件。

透過執行

kc.sh --help

您現在可以查看您可以執行的不同動作，例如啟動伺服器或匯出領域，以及瀏覽您可以為每個支援的命令設定的不同配置選項。

我們一直在尋找 CLI 的改進。請隨時與我們聯繫，提出您認為可能有幫助的任何建議。

啟動伺服器

如前所述，預設配置對伺服器的啟動方式施加了一些條件。

成功啟動伺服器的主要條件之一是配置 HTTPS。

但是，為了開發目的，Keycloak 可以在開發模式下啟動。

目前，此模式基本上是一個配置設定檔，允許您在不使用 HTTPS 的情況下使用本機快取來運行伺服器。

kc.sh start-dev

執行上述命令後，伺服器應可在 https://127.0.0.1:8080/ 上使用。

未來，此模式還將放寬某些領域的配置政策，否則在生產環境中運行時將不允許這些政策。例如，使用萬用字元作為您用戶端的有效重定向 URI。

配置伺服器

考慮到 IAM 解決方案的重要性以及錯誤配置對部署整體安全性的影響，Keycloak 現在以盡可能少的配置發布，並以預設安全策略為考量。

我們的想法是提供運行伺服器的最低限度配置選項，同時對在生產環境中運行之前應如何設定配置施加一些關鍵限制。

這是我們正在改進的主要領域之一，並且我們不斷嘗試透過一小組配置選項或良好的預設值來避免樣板配置。

現在可以使用屬性檔案、環境變數或透過 Keycloak CLI 作為參數來設定不同的配置選項。

您可以透過執行 help 命令輕鬆檢查可用的配置選項。

有關配置的更多詳細資訊，請參閱 配置設計 文件。

配置類別

配置選項分為兩個類別

  • 可以在啟動伺服器時在運行時設定的選項

  • 只能在透過 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

在現實世界中，您會配置有效的金鑰對和憑證，但是您可以使用以下命令產生自我簽署的憑證來了解如何設定 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 的 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=******

叢集

目前，我們仍然使用 Infinispan 和 JGroups 進行叢集和 HA 部署。

但是，現在配置使用的是 Infinispan 的原生配置，而不是像在 Wildfly Infinispan 子系統中那樣使用抽象。這應該會在配置、支援和說明文件方面提供更大的靈活性。

配置也已簡化，您應該會獲得伺服器部署所在的不同平台的良好預設值。

預設情況下，已啟用叢集，您可以使用預設配置準備建置 Keycloak 叢集。

預設配置位於 conf 目錄中，檔案名稱為 cluster-default.xml。

在同一個目錄中，您還有一個 cluster-local.xml 檔案，它將所有快取配置為本機，沒有叢集。若要使用此配置，請執行以下命令

kc.sh --cluster=local

您可以透過在 conf 目錄中建立一個以 cluster- 為首碼的檔案（就像我們隨發行版本提供的 cluster-local.xml 和 cluster-default 檔案一樣）來定義自己的快取配置。

我們還為 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)

首次

第二次+

首次

第二次+

Wildfly

12.1

8.1

646

512

Quarkus

7.6

3.1

428

320

數據應該不言自明，並且人們應該預期這些數據在每個 Keycloak.X 版本中都會有所改善。

然而，這不僅僅是關於減少 MB 數，而是關於如何優化記憶體使用。通過使用 64MB 的堆記憶體運行兩個伺服器，您應該會注意到在 Wildfly 上運行時會有大量的垃圾回收，最終可能導致伺服器無法啟動。而使用相同堆大小的 Keycloak.X，您能夠讓伺服器正常運行。當然，根據您的用例，使用此堆大小並不實際，但它很好地說明了您從現在開始應該期望什麼。

關於效能，在此首個版本中，我們的主要重點是啟動時間和記憶體消耗。執行時效能正在開發中，由於 Keycloak.X 基於 Vert.X 運行，結果令人期待。

總體而言，我們仍然處於旅程的起點。一旦 Keycloak 在 Quarkus 上有了原生發行版本，我們可以預期更快的啟動時間、更小的記憶體消耗以及使用更少資源的整體更佳效能。

路線圖

這僅是我們為 Keycloak 使用者提供更友善雲端體驗的旅程的開始。

Keycloak.X 是一個預覽發行版本，我們在社群的幫助下不斷改進，直到它成為我們主要的發行版本。我們感謝在這個旅程中的任何回饋。

目前正在進行許多重要的工作來補充 Keycloak.X 發行版本，例如

  • 零停機時間升級

  • 原生映像檔支援

  • 改善開發人員體驗

  • 更多文件

我們希望得到您的支持和回饋，以持續改善您使用 Keycloak 的體驗。

感謝社群

這是社群共同努力的成果，因此我們要特別感謝所有貢獻。

特別感謝

以及所有幫助撰寫配置設計文件的人。

參考資料