Apache Kyuubi 入門

Apache Kyuubi は、分散データシステム向けのマルチテナント SQL ゲートウェイです。各ユーザーが Spark アプリケーションのライフサイクル、クラスタキュー、エンジン設定を管理しなくても、ユーザーや BI ツールに安定した JDBC または ODBC エンドポイントを提供します。

Kyuubi は、クエリを実行するプロセスから、長時間稼働するクライアントエンドポイントを分離します。 この分離が、Kyuubi の主なアーキテクチャ上の貢献です。

• Kyuubi サーバーはクライアントを認証し、プロトコルセッションを維持し、エンジンを選択して、操作を転送します。
• Kyuubi エンジンは SQL を実行し、コンピュートリソースを消費します。Spark SQL が最も一般的なエンジンですが、Kyuubi のリリースによっては他のクエリエンジンとも統合できます。
• 外部サービスは引き続き、リソース管理、メタデータ、ストレージ、認可ポリシー、サービスディスカバリを提供します。

したがって Kyuubi は、Spark、YARN、Kubernetes、Hive metastore、オブジェクトストレージを置き換えるものではありません。Kyuubi はそれらへのアクセスを調整します。

アーキテクチャ #

一般的な Spark-on-YARN デプロイメントは次のようになります。

Beeline、BI ツール、またはアプリケーション
            |
            | HiveServer2 プロトコルを使用する JDBC/ODBC
            v
   Kyuubi サーバープール
      |          |
      |          `----> ZooKeeper または設定済みの別のディスカバリサービス
      |
      | 起動、検出、または再利用
      v
Spark SQL エンジンアプリケーション
      |----> ドライバーとエグゼキューターのリソース用 YARN
      |----> テーブルメタデータ用 Hive Metastore
      |----> テーブルデータ用 HDFS またはオブジェクトストレージ
      `----> Ranger または別の認可システム

エンジンが解析、実行計画、スキャン、結合、シャッフル、書き込みを実行するため、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. クライアントセッションを閉じると、そのオペレーション状態が解放されます。共有ポリシーとタイムアウトポリシーに従い、エンジンは再利用のため稼働し続けるか停止します。

この流れから、特徴的な 2 種類のレイテンシパターンが分かります。コールドセッションでは Spark ドライバーとエグゼキューターの起動を待つ必要がありますが、ウォームセッションでは既存のエンジンを再利用できるため、ほぼ直ちに計画を開始できます。

エンジン共有レベルを選択する #

エンジン共有レベルは、どのセッションが 1 つのエンジンを再利用できるかを定義します。名称と詳細はデプロイ済みの Kyuubi リリースに照らして確認する必要がありますが、標準的な選択肢は次のとおりです。

USER は再利用と分離のバランスが取れているため、一般的なデフォルトです。ただし、本番環境で自動的に適切な選択になるわけではありません。

• CONNECTION はセッション間の干渉を制限しますが、ドライバーによってクラスタが過負荷になる可能性があります。
• USER は、多数の一時的なユーザーがそれぞれエンジンを保持すると、リソースが孤立する可能性があります。
• GROUP は利用率を改善しますが、信頼できるグループマッピングと互換性のある認可ルールが必要です。
• サーバー全体の共有では、無関係なユーザーが 1 つのエンジンプロセスに入ります。セッションレベルの SQL 認可を強固にし、危険な設定、一時ビュー、キャッシュ、リソースの相互作用を管理者が防止する必要があります。

共有設定は、セキュリティ境界であると同時にキャパシティに関する決定でもあります。起動時間を短縮することだけを理由に選択しないでください。

エンジンのライフサイクルを理解する #

サーバーとエンジンのライフサイクルは独立しています。選択したディスカバリおよびリカバリ動作がそれをサポートしていれば、リモートにデプロイされたエンジンが稼働し続けている間に、クライアントは別のサーバーノードを介して再接続できます。

エンジンは通常、次の状態を遷移します。

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

重要な制御項目は次のとおりです。

• 起動タイムアウト: リソース割り当てとエンジン登録をセッションが待機する時間。
• アイドルタイムアウト: アクティブなセッションがないエンジンを利用可能な状態で保持する時間。
• セッションおよびオペレーションタイムアウト: 放棄されたクライアント状態を回収するタイミング。
• エンジン有効期間: 長時間稼働するエンジンを定期的に置き換えるための任意の上限。
• 失敗制限と再試行ポリシー: Kyuubi が起動を再試行するか、クライアントに失敗を報告するか。

長いアイドルタイムアウトは対話型レイテンシを改善しますが、ドライバーメモリを確保し、エグゼキューター、キャッシュデータ、クラスローダー、カタログ状態を保持する可能性があります。短いタイムアウトはリソースを節約しますが、ユーザーはコールドスタートのコストを繰り返し負担します。値を選択する前に、到着パターンとエンジン起動時間を測定してください。

設定レイヤーを分離する #

Kyuubi デプロイメントには、複数の設定スコープがあります。

1. サーバー設定は、リスナー、認証、ディスカバリ、サーバータイムアウト、ロギング、エンジン起動に使用するルールを制御します。
2. エンジン設定は、Spark ドライバー、エグゼキューター、カタログ、拡張機能、クラスパス、リソースキュー、SQL ランタイムを制御します。
3. セッション設定は、管理者が許可した場合に、1 つの論理クライアントセッションへ影響します。
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

サポートと解釈はクライアントおよびサーバーのバージョンに依存します。パスワードをシェル履歴やプロセス引数に残さず、認証情報またはクエリ結果が信頼できないネットワークを通過する場合は 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 バージョン、エンジンアーティファクト、設定、トラストストア、認証マテリアルを配布する。
• 必要に応じて、各ノードに一意の広告アドレスを設定する。
• 可変なクエリ状態は、1 台のサーバーのローカルディスクではなく、エンジンまたはサポートされている共有サービスに保持する。
• 既存のオペレーションを完了できるよう、アップグレード前にリスナーをドレインする。
• ローリングアップグレードを実行する前に、混在バージョンの動作をテストする。

TCP ロードバランサーはクライアントにとって単純ですが、ディスカバリ対応 JDBC では登録済みサーバープールを直接公開できます。どちらの方式も、失敗した接続の実行中オペレーションが透過的に再生されることを保証しません。クライアントには上限付きの再試行が必要であり、ステートメントを安全に再送信できるかどうかを理解していなければなりません。

YARN 上の Spark エンジン #

YARN デプロイメントでは、Kyuubi がドライバーを持つアプリケーションを送信し、その後エグゼキューターを要求します。次を確認してください。

• 送信者またはプロキシアイデンティティが、選択したキューを使用できる。
• エンジンが Spark、Kyuubi エンジン JAR、Hadoop 設定、keytab、カタログ依存関係をローカライズできる。
• ApplicationMaster がファイアウォール越しに Kyuubi へ再登録できる。
• ドライバーホストとエグゼキューターホストが HMS、ストレージ、KMS、Ranger、シャッフルサービスに到達できる。
• キューの上限が、要求されたドライバーおよびエグゼキューターの構成を許可している。
• エンジンログと Spark イベントログがコンテナ終了後も保持される。

エンジン作成でセッションが停止する場合、JDBC の問題ではなく、リソース割り当てまたはコールバックの問題であることが少なくありません。

Kubernetes 上のエンジン #

Kubernetes では、対応する制御項目は、名前空間、サービスアカウント、RBAC、Pod、イメージ、Secret、ConfigMap、永続ログまたはオブジェクトストレージに保存するログ、ネットワークポリシー、リソースクォータです。長期間有効な認証情報をイメージに直接格納しないでください。ダイジェストでイメージを固定し、セッション設定が 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 とオペレーション ID、正規化されたステートメントまたはステートメントハッシュ、可能な場合は対象オブジェクト、開始時刻と終了時刻、結果、リソースキューを保持する必要があります。SQL テキストには機密性の高いリテラルが含まれる可能性があるため、監査ログを保護してください。

サービスを運用・監視する #

ゲートウェイとエンジンを個別に監視します。

有用なサーバーシグナルには、次のものがあります。

• オープン接続数と拒否接続数。
• アクティブなセッションとオペレーション。
• 認証失敗。
• エンジン起動要求、所要時間、タイムアウト、失敗率。
• リクエストキューの深さと RPC レイテンシ。
• サーバーヒープ、ガベージコレクション、スレッド、ファイルディスクリプター。

有用なエンジンシグナルには、次のものがあります。

• エンジンごとのアクティブセッションとステートメント。
• ドライバーメモリとガベージコレクション。
• エグゼキューターの割り当てと損失。
• SQL の計画および実行時間。
• シャッフルの読み取り・書き込み、スピル、データ偏り、失敗したステージ。
• カタログとストレージのレイテンシ。
• アイドル時間と終了理由。

Kyuubi のセッション ID およびオペレーション ID を Spark アプリケーション ID と関連付けます。Kyuubi サーバー CPU だけを報告する単一のダッシュボードでは、すべてのクエリが YARN のキャパシティやオブジェクトストレージのスロットリングによってブロックされていても、正常に見える可能性があります。

フェーズ単位でサービスレベル目標を設定します。接続確立、コールドエンジン起動、ウォームクエリ起動、クエリ実行には異なる原因があるため、1 つのレイテンシパーセンタイルにまとめないでください。

キャパシティを計画する #

少なくとも 4 つの独立した上限を見積もります。

1. サーバー接続キャパシティ: 同時トランスポート、セッション、オペレーション、結果取得トラフィック。
2. ドライバーキャパシティ: 選択した共有ポリシーで保持されるエンジンの数とサイズ。
3. エグゼキューターキャパシティ: アクティブな SQL に必要なピーク時および継続的なリソース。
4. 下流キャパシティ: HMS 接続、オブジェクトストレージ要求、HDFS ハンドラー、認可チェック、シャッフル帯域幅。

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 レイテンシ、古い統計情報、ドライバーのガベージコレクション、1 つのエンジンを共有するセッション数の過多、エグゼキューター不足、データ偏り、シャッフルスピル、オブジェクトストレージのスロットリング、過大な結果取得を確認します。サーバーを再起動すると、不健全なエンジンが一時的に隠れるだけで、原因を特定できない場合があります。

フェイルオーバー中にクライアントが結果を失う #

サーバーディスカバリによって別のエンドポイントは利用可能になりますが、任意の SQL オペレーションが安全に再実行できるようになるわけではありません。オペレーションが完了したかを確認し、書き込みにはアプリケーションレベルの冪等性を使用し、INSERT、MERGE、DDL の盲目的な再試行を避けます。

主な選択肢を比較する #

Kyuubi は運用機構を追加しますが、Spark Thrift Server より自動的に高速になるわけではありません。価値は、エンジン分離、ライフサイクル管理、ルーティング、共有セキュリティ制御、安定したサービス境界にあります。

Kyuubi が適しているか判断する #

Kyuubi は次の条件で適しています。

• アナリスト、ダッシュボード、ノートブック、アプリケーションが安定した SQL エンドポイントを必要とする。
• Spark または別のサポート対象バックエンドが、すでに望ましい実行エンジンである。
• ワークロードにユーザー単位、グループ単位、または接続単位の分離が必要である。
• 管理者が認証、監査、設定ポリシー、キュールーティング、エンジンライフサイクル管理を集中管理する必要がある。
• 保持されるエンジンのコストとコールドスタートレイテンシのバランスを取れる。

すべてのワークロードがスケジュール済みジョブである場合、信頼できる 1 つのチームが単一の Spark Thrift Server を使用できる場合、または別のクエリサービスが必要なレイテンシ、同時実行性、ガバナンス、エコシステムサポートをすでに提供している場合、Kyuubi は不要かもしれません。

有用なメンタルモデルは次のとおりです。Spark は計算を提供し、カタログはデータを記述し、クラスターマネージャーはリソースを割り当て、Kyuubi はそれらのコンポーネントを管理されたマルチユーザー SQL サービスに変換します。