Apache Kyuubi 簡介

Apache Kyuubi 是分散式資料系統的多租戶 SQL 閘道。它為使用者與 BI 工具提供穩定的 JDBC 或 ODBC 端點，而不要求每位使用者管理 Spark 應用程式生命週期、叢集佇列或引擎設定。

Kyuubi 將長時間執行的用戶端端點與執行查詢的程序分離。 這項區分是 Kyuubi 在架構上的主要貢獻：

• Kyuubi 伺服器負責驗證用戶端、維護通訊協定工作階段、選取引擎，以及轉送作業。
• Kyuubi 引擎負責執行 SQL 並消耗運算資源。Spark SQL 是最常見的引擎，而 Kyuubi 的各個版本也可以整合其他查詢引擎。
• 外部服務仍然提供資源管理、詮釋資料、儲存、授權原則和服務探索。

因此，Kyuubi 不會取代 Spark、YARN、Kubernetes、Hive metastore 或物件儲存。它負責協調對這些元件的存取。

架構 #

典型的 Spark-on-YARN 部署如下：

Beeline、BI 工具或應用程式
            |
            | 使用 HiveServer2 通訊協定的 JDBC/ODBC
            v
   Kyuubi 伺服器池
      |          |
      |          `----> ZooKeeper 或其他已設定的探索服務
      |
      | 啟動、探索或重複使用
      v
Spark SQL 引擎應用程式
      |----> YARN，用於驅動程式和執行器資源
      |----> Hive Metastore，用於資料表詮釋資料
      |----> HDFS 或物件儲存，用於資料表資料
      `----> Ranger 或其他授權系統

由於引擎負責剖析、規劃、掃描、聯結、shuffle 和寫入，Kyuubi 伺服器相對輕量。增加伺服器節點可以提高連線和作業處理容量，但不會因此增加 Spark 執行器。

Apache Hive / Kyuubi Overview 更詳細地比較了這項設計與 HiveServer2 及 Spark Thrift Server 的差異。

追蹤查詢 #

假設 Beeline 傳送以下陳述式：

SELECT region, SUM(amount)
FROM lakehouse.sales
WHERE sale_date >= DATE '2026-08-01'
GROUP BY region;

要求通常會經過以下階段：

1. 用戶端開啟傳輸連線，並與 Kyuubi 伺服器執行已設定的驗證交換。
2. Kyuubi 建立通訊協定工作階段，並決定有效使用者、引擎類型、引擎共用範圍和允許的設定。
3. Kyuubi 搜尋相容的執行中引擎。如果不存在，則向 YARN、Kubernetes 或已設定的本機環境提交新的引擎應用程式。
4. 伺服器等待引擎註冊，然後轉送作業。
5. 引擎剖析並規劃 SQL、讀取目錄詮釋資料、檢查授權、要求運算資源，以及存取資料表檔案。
6. Kyuubi 公開作業狀態和記錄，而用戶端輪詢或擷取結果。
7. 關閉用戶端工作階段會釋放其作業狀態。引擎可能依照共用和逾時原則繼續執行以供重複使用，或停止執行。

這解釋了兩種特徵性的延遲模式。冷工作階段可能需要等待 Spark 驅動程式和執行器啟動；熱工作階段可以重複使用現有引擎，幾乎立即開始規劃。

選擇引擎共用層級 #

引擎共用層級定義哪些工作階段可以重複使用同一個引擎。名稱和詳細資訊應根據已部署的 Kyuubi 版本進行確認，但標準選項如下：

USER 是常見的預設值，因為它在重複使用和隔離之間取得平衡。但它不一定自動適合生產環境：

• CONNECTION 可以限制工作階段間的干擾，但可能因為驅動程式過多而使叢集過載。
• USER 在許多偶爾使用的使用者各自保留一個引擎時，可能導致資源閒置。
• GROUP 可以提高利用率，但需要可信任的群組對映和相容的授權規則。
• 伺服器範圍的共用會將無關的使用者置於同一個引擎程序中。工作階段層級的 SQL 授權必須足夠強，管理員也必須防止不安全的設定、暫存檢視表、快取和資源互動。

共用既是安全邊界，也是容量決策。不要只為了降低啟動時間而選擇共用層級。

了解引擎生命週期 #

伺服器和引擎具有獨立的生命週期。如果選取的探索和復原行為支援此模式，用戶端可以透過另一個伺服器節點重新連線，同時遠端部署的引擎繼續執行。

引擎通常會經過以下狀態：

requested -> submitted -> starting -> registered -> active -> idle -> stopped

重要控制項包括：

• 啟動逾時： 工作階段等待資源配置和引擎註冊的時間。
• 閒置逾時： 沒有作用中工作階段的引擎保持可用狀態的時間。
• 工作階段和作業逾時： 回收已放棄用戶端狀態的時機。
• 引擎存續時間： 定期取代長時間執行引擎的選用上限。
• 失敗限制和重試原則： Kyuubi 是否重試啟動，或將失敗回報給用戶端。

較長的閒置逾時可以改善互動式延遲，但會保留驅動程式記憶體，並可能保留執行器、快取資料、類別載入器和目錄狀態。較短的逾時可以節省資源，但使用者會反覆承擔冷啟動成本。在選擇數值前，請測量請求到達模式和引擎啟動時間。

分離設定層 #

Kyuubi 部署包含數個設定範圍：

1. 伺服器設定控制監聽器、驗證、探索、伺服器逾時、記錄，以及用於啟動引擎的規則。
2. 引擎設定控制 Spark 驅動程式、執行器、目錄、擴充功能、類別路徑、資源佇列和 SQL 執行階段。
3. 工作階段設定在管理員允許時，會影響一個邏輯用戶端工作階段。
4. 陳述式設定是 SET 等 SQL 命令，受引擎和安全性限制。

設定可能來自伺服器檔案、引擎預設值、環境專用範本、JDBC URL 參數和用戶端屬性。確切的優先順序和允許清單行為取決於版本。管理員應明確限制用戶端覆寫，而不是假設每個 spark.* 屬性都無害。

例如，允許用戶端選取 YARN 佇列可能很有用：

#spark.yarn.queue=analytics-interactive

但允許任意封存檔、JAR、擴充功能、代理使用者、事件記錄目的地或目錄實作，可能成為程式碼執行或權限提升的路徑。應將設定原則視為安全模型的一部分。

使用 JDBC 連線 #

Kyuubi 公開與 HiveServer2 相容的端點，因此 Beeline 和許多 Hive JDBC 工具無需使用 Kyuubi 專用的線路通訊協定即可連線：

beeline -u \
  'jdbc:hive2://sql.example.com:10009/default;ssl=true;principal=kyuubi/sql.example.com@EXAMPLE.COM'

URL 包含數個不同區域：

jdbc:hive2://host:port/database;session-properties?query-properties#engine-properties

支援情況和解讀方式取決於用戶端和伺服器版本。不要將密碼放入 shell 歷史或程序引數中；當認證資訊或查詢結果穿越不受信任的網路時，請使用 TLS，並驗證伺服器憑證和主機名稱。

如需完整的安全範例，請參閱 Kerberos Beeline-to-Kyuubi walkthrough，其中說明以下 URL：

jdbc:hive2://kyuubi.hadoop.vip.mycompany.com:10010/default;ssl=true;principal=kyuubi/kyuubi.hadoop.vip.mycompany.com@PROD.MYCOMPANY.COM?kyuubi.session.cluster=analytics-prod#spark.yarn.queue=analytics-high-memory

該範例追蹤 DNS 和 TLS、票證授予票證、服務票證取得、SASL/GSSAPI、Kyuubi 的服務 keytab、YARN 提交，以及 Hadoop 委派權杖。

部署 Kyuubi #

伺服器節點 #

在穩定端點後方執行多個 Kyuubi 伺服器，或使用受支援的服務探索模式。讓伺服器節點保持可互換：

• 分發相同的 Kyuubi 版本、引擎成品、設定、信任存放區和驗證資料；
• 在需要時，為每個節點提供唯一的公告位址；
• 將可變的查詢狀態保留在引擎或受支援的共用服務中，而非某個伺服器的本機磁碟上；
• 升級前先清空監聽器，讓現有作業完成；以及
• 執行循序升級前，先測試混合版本行為。

TCP 負載平衡器對用戶端而言較為簡單，而支援探索的 JDBC 可以直接公開已註冊的伺服器池。兩種機制都無法保證失敗連線中的進行中作業會透明地重新執行。用戶端需要有界重試，並且必須了解某個陳述式是否可以安全地重新提交。

YARN 上的 Spark 引擎 #

對於 YARN 部署，Kyuubi 會提交一個包含驅動程式的應用程式，之後再要求執行器。請確認：

• 提交者或代理身分可以使用選取的佇列；
• 引擎可以本地化 Spark、Kyuubi 引擎 JAR、Hadoop 設定、keytab 和目錄相依項目；
• ApplicationMaster 可以穿過防火牆向 Kyuubi 重新註冊；
• 驅動程式和執行器主機可以連線到 HMS、儲存、KMS、Ranger 和 shuffle 服務；
• 佇列上限允許要求的驅動程式和執行器規格；以及
• 引擎記錄和 Spark 事件記錄可以在容器終止後保留。

工作階段卡在引擎建立階段時，通常是資源配置或回呼問題，而不是 JDBC 問題。

Kubernetes 上的引擎 #

在 Kubernetes 上，相應的控制項包括命名空間、服務帳戶、RBAC、Pod、映像、Secrets、ConfigMaps、持久化或物件儲存支援的記錄、網路原則和資源配額。避免將長期有效的認證資訊直接放入映像。按照摘要固定映像，控制哪些工作階段設定可以影響 Pod 範本，並將受信任的管理引擎與一般使用者引擎分離。

整合目錄和儲存 #

Kyuubi 不會儲存資料表詮釋資料。Spark 引擎可以使用 Hive Metastore、Iceberg 目錄、JDBC 目錄或其他目錄外掛程式。引擎需要：

• 相符的用戶端程式庫和目錄擴充功能；
• 網路存取和驗證憑證；
• 相容的 Hadoop 檔案系統實作；
• 物件儲存或 HDFS 認證資訊；
• 在適用時存取加密金鑰；以及
• 具備正確擁有權的倉庫和暫存位置。

目錄程式庫應放在引擎類別路徑，而不只是 Kyuubi 伺服器類別路徑中。當引擎缺少目錄 JAR 或無法連線到 HMS 時，伺服器仍可接受 JDBC 工作階段，但之後每個查詢都可能失敗。

建立安全模型 #

安全性跨越多個跳接：

client -> Kyuubi server -> engine -> metastore/storage/authorization service

每個跳接回答不同的問題：

• TLS 在驗證憑證時保護傳輸並驗證端點。
• Kerberos、LDAP、PAM 或其他已設定的機制負責將用戶端驗證至 Kyuubi。
• Impersonation 或代理使用者規則決定哪個身分啟動引擎並存取下游 Hadoop 服務。
• 委派權杖和服務認證資訊讓長時間執行的引擎可以存取 HDFS、HMS、KMS 和相關服務。
• SQL 授權通常透過 Ranger 等原則外掛程式決定使用者可以存取哪些目錄、資料表、欄、列和作業。
• YARN 佇列或 Kubernetes 配額限制運算資源，而非資料權限。

驗證不代表授權。成功取得 Kerberos 服務票證只能證明身分已向 Kyuubi 證實，並不會授予資料表存取權。

稽核記錄至少應保留已驗證使用者、有效使用者、用戶端位址、伺服器、引擎應用程式 ID、工作階段和作業 ID、正規化陳述式或陳述式雜湊、可取得時的目標物件、開始與結束時間、結果，以及資源佇列。由於 SQL 文字可能包含敏感常值，請保護稽核記錄。

操作和觀測服務 #

分別監控閘道和引擎。

有用的伺服器訊號包括：

• 開啟和遭拒絕的連線；
• 作用中工作階段和作業；
• 驗證失敗；
• 引擎啟動要求、持續時間、逾時和失敗率；
• 要求佇列深度和 RPC 延遲；以及
• 伺服器堆積區、垃圾收集、執行緒和檔案描述元。

有用的引擎訊號包括：

• 每個引擎中的作用中工作階段和陳述式；
• 驅動程式記憶體和垃圾收集；
• 執行器配置和遺失；
• SQL 規劃和執行時間；
• shuffle 讀取/寫入、溢寫、偏斜和失敗階段；
• 目錄和儲存延遲；以及
• 閒置時間和終止原因。

將 Kyuubi 工作階段和作業識別碼與 Spark 應用程式 ID 建立關聯。只報告 Kyuubi 伺服器 CPU 的單一儀表板，即使所有查詢都因 YARN 容量或物件儲存節流而遭到阻塞，也可能看起來很健康。

依階段設定服務等級目標。連線建立、冷引擎啟動、熱查詢啟動和查詢執行具有不同原因，不應合併成單一延遲百分位數。

規劃容量 #

至少估計四個獨立限制：

1. 伺服器連線容量： 同時連線、工作階段、作業和結果擷取流量。
2. 驅動程式容量： 根據選取的共用原則保留的引擎數量和大小。
3. 執行器容量： 作用中 SQL 所需的尖峰和持續資源。
4. 下游容量： HMS 連線、物件儲存要求、HDFS 處理常式、授權檢查和 shuffle 頻寬。

對於 USER 共用，驅動程式記憶體的粗略上限如下：

同時保留的使用者引擎數
  * (驅動程式記憶體 + 驅動程式額外負荷)

這與執行器需求分開計算。數百個大多處於閒置狀態的使用者引擎，可能在消耗大量執行器 CPU 之前，先耗盡佇列應用程式限制或驅動程式記憶體。引擎池、審慎選取的閒置逾時和群組共用可以降低該成本，但每一項都會改變隔離程度。

使用佇列限制、陳述式逾時、准入控制和最大結果大小來保護互動式工作負載。透過 Kyuubi 擷取數百萬列的 JDBC 用戶端，通常不如將結果寫入受治理的儲存體。

診斷常見故障 #

用戶端無法連線 #

檢查 DNS、負載平衡器健康狀態、監聽器位址、TLS 信任和主機名稱驗證、驗證設定，以及所選伺服器是否已註冊。TCP 連線拒絕發生在引擎選擇之前。

驗證成功但引擎未啟動 #

檢查 Kyuubi 伺服器記錄和叢集管理器應用程式狀態。常見原因包括佇列拒絕、應用程式限制耗盡、引擎成品遺失、Spark 設定無效、容器映像無法使用、回呼網路受限，或身分無法提交應用程式。

引擎啟動但 SQL 無法解析資料表 #

檢查引擎的目錄設定和類別路徑、HMS URI、DNS、TLS 或 Kerberos 認證資訊、倉庫路徑，以及目錄版本相容性。只變更 Kyuubi 伺服器類別路徑，無法修復遠端引擎。

查詢因權限錯誤而失敗 #

找出拒絕要求的層：

• Kyuubi 驗證或代理使用者原則；
• SQL 授權原則；
• HMS 授權；
• HDFS 權限或 ACL；
• 物件儲存 IAM；
• 加密金鑰原則；或
• YARN/Kubernetes 資源原則。

不要透過授予 Kyuubi 服務身分廣泛的儲存存取權來掩蓋失敗。端對端驗證已驗證身分和有效身分。

熱查詢變慢 #

分離規劃和執行。檢查 HMS 延遲、過時統計資料、驅動程式垃圾收集、過多工作階段共用同一個引擎、執行器資源不足、偏斜、shuffle 溢寫、物件儲存節流，或結果擷取過大。重新啟動伺服器可能暫時掩蓋不健康的引擎，但無法找出原因。

用戶端在容錯移轉期間遺失結果 #

伺服器探索可以提供另一個端點，但無法使任意 SQL 作業具備可安全重播的能力。判斷作業是否已完成，對寫入使用應用程式層級的冪等性，並避免盲目重試 INSERT、MERGE 或 DDL。

比較主要選項 #

Kyuubi 增加了操作機制，但不會自動比 Spark Thrift Server 更快。它的價值來自引擎隔離、生命週期管理、路由、共用安全控制和穩定的服務邊界。

判斷 Kyuubi 是否適用 #

在以下情況，Kyuubi 很適合：

• 分析師、儀表板、筆記本和應用程式需要穩定的 SQL 端點；
• Spark 或其他受支援的後端已經是所需的執行引擎；
• 工作負載需要依使用者、群組或連線進行隔離；
• 管理員需要集中管理驗證、稽核、設定原則、佇列路由和引擎生命週期；以及
• 可以在冷啟動延遲和保留引擎的成本之間取得平衡。

如果所有工作負載都是排程工作、一個受信任的團隊可以使用單一 Spark Thrift Server，或其他查詢服務已提供所需的延遲、並行、治理和生態系統支援，Kyuubi 可能並不必要。

有用的心智模型是：Spark 提供運算；目錄描述資料；叢集管理器配置資源；Kyuubi 將這些元件轉換成受管理的多使用者 SQL 服務。