UCX ユーティリティを使用してワークスペースをUnity Catalogにアップグレードする
この記事では、Unity Catalog 以外のワークスペースを Unity Catalog にアップグレードするのに役立つツールを提供する Databricks Labs プロジェクトであるUCXを紹介します。
注:
UCX は、databrickslabs GitHubアカウントのすべてのプロジェクトと同様に、調査目的のみに提供されており、 Databricksによってサービス レベル アグリーメント (SLA) で正式にサポートされていません。 現状有姿で提供されます。 当社は、いかなる種類の保証も行いません。 このプロジェクトの使用から生じる問題に関連する Databricks サポート チケットを送信しないでください。 代わりに、 GitHub の問題を報告してください。 問題は時間が許す限りレビューされますが、サポートに関する正式な SLA はありません。
UCX プロジェクトでは、次の移行ツールとワークフローが提供されます。
移行の計画に役立つ評価ワークフロー。
グループ移行は、グループ メンバーシップをワークスペースからDatabricksアカウントにアップグレードし、アクセス許可を新しいアカウント レベルのグループに移行するのに役立ちます。
ワークスペースの に登録されているテーブルを メタストアにアップグレードするのに役立つ テーブル移行ワークフローHive metastore Unity Catalog。このワークフローは、ストレージの場所と、そこにアクセスするために必要な資格情報の移行にも役立ちます。
この図は、移行ワークフローとユーティリティを名前で識別しながら、全体的な移行フローを示しています。
注:
図に示されているコード移行ワークフローはまだ開発中であり、利用できません。
始める前に
UCX をインストールして UCX ワークフローを実行する前に、環境が次の要件を満たしている必要があります。
UCX を実行するコンピューターにインストールされているパッケージ:
Databricks CLI v0.213 以上。 「Databricks CLI のインストールまたは更新」を参照してください。
ワークスペースと Databricks アカウントの両方の構成プロファイルを含む Databricks 構成ファイルが必要です。
Python 3.10 以上。
ワークスペース内のHiveテーブルで使用されるストレージの場所を識別する UCX ワークフロー を実行する場合 (推奨されますが、必須ではありません)、UCX ワークフロー を実行するコンピューターにクラウド ストレージ プロバイダーのCLI ( Azure CLIまたはAWS CLI ) がインストールされている必要があります。
ネットワークアクセス:
UCX インストールを実行するコンピューターから、移行する Databricks ワークスペースへのネットワーク アクセス。
UCX インストールを実行するコンピューターからインターネットへのネットワーク アクセス。 これは、pypi.org と github.com にアクセスするために必要です。
databricks-sdk
およびpyyaml
パッケージをダウンロードするには、Databricks ワークスペースから pypi.org へのネットワーク アクセスが必要です。
Databricks のロールと権限:
UCX インストールを実行するユーザーの Databricks アカウント管理者およびワークスペース管理者のロール。 サービスプリンシパルとしてインストールを実行することはできません。
その他の Databricks の前提条件:
アップグレードするワークスペースをホストするリージョンごとに作成されたUnity Catalogメタストア。各DatabricksワークスペースはUnity Catalogメタストアに接続されます。
Unity Catalog関連するワークスペース領域に メタストアが既に存在するかどうかを確認する方法、存在しない場合にメタストアを作成する方法、およびUnity Catalog メタストアをワークスペースにアタッチする方法については、 セットアップ記事の 「ステップ 1: ワークスペースが に対して有効になっていることを確認する」をUnity Catalog Unity Catalog参照してください。代替手段として、UCX は、UCX のインストール後に使用できるワークスペースに Unity Catalog メタストアを割り当てるユーティリティを提供します。
Unity Catalog メタストアをワークスペースにアタッチすると、 ID フェデレーションも有効になり、Databricks アカウント レベルでユーザー管理が集中化されます。これは、UCX を使用するための前提条件でもあります。 「ID フェデレーションの有効化」を参照してください。
ワークスペースHive metastore AWSが デフォルト ワークスペース -local の代わりに外部 ( Glue など)Hive metastore を使用する場合は、いくつかの前提条件の設定を実行する必要があります。databrickslabs/ucx リポジトリの「外部Hive metastore統合」を参照してください。
評価ワークフローによって生成されたレポートをレンダリングするには、UCX ワークフローを実行するワークスペースで実行されている Pro またはサーバーレス SQL ウェアハウスが必要です。
UCXのインストール
UCX をインストールするには、Databricks CLI を使用します。
databricks labs install ucx
以下を選択するように求められます。
アップグレードするワークスペースの Databricks 構成プロファイル。 構成ファイルには、ワークスペースの親 Databricks アカウントの構成プロファイルも含める必要があります。
移行ワークフローの出力を保存するために使用されるインベントリ データベースの名前。 通常は、デフォルトの
ucx
を選択しても問題ありません。インストール プロセスを実行する SQL ウェアハウス。
アカウント レベルのグループに移行するワークスペース ローカル グループのリスト。 これをデフォルト (
<ALL>
) のままにすると、ワークスペース ローカル グループと名前が一致する既存のアカウント レベル グループがそのワークスペース ローカル グループの代わりとして扱われ、インストール後にグループ移行ワークフローを実行するときに、そのワークスペース権限がすべて継承されます。インストーラーを実行した後、グループの移行を実行する前に、ワークスペース グループとアカウント グループのマッピングを変更する機会があります。 UCX リポジトリのグループ名の競合解決を参照してください。
Glue などの外部Hive metastore がある場合は、それに接続するかどうかを選択できます。AWSdatabrickslabs/ucx リポジトリの「外部Hive metastore統合」を参照してください。
生成された README ノートブックを開くかどうか。
インストールが完了すると、README ノートブック、ダッシュボード、データベース、ライブラリ、ジョブ、その他のアセットがワークスペースにデプロイされます。
詳細については、プロジェクトの readme のインストール手順を参照してください。 Databricks アカウント内のすべてのワークスペースに UCX をインストールすることもできます。
READMEを開く
すべてのインストールでは、すべてのワークフローとタスクの詳細な説明と、ワークフローとダッシュボードへのクイック リンクを提供する README ノートブックが作成されます。 Readme を参照してください。
ステップ1. 評価を実行する
評価ワークフローは、現在のワークスペース内のグループ ID、ストレージの場所、ストレージの資格情報、アクセス制御、およびテーブルの Unity Catalog 互換性を評価し、Unity Catalog への移行を計画するために必要な情報を提供します。 評価ワークフロー内のタスクは、指定された依存関係に応じて、並列または順次実行できます。 評価ワークフローが終了すると、評価ダッシュボードに結果と一般的な推奨事項が表示されます。
各ワークフロー タスクの出力は、インストール時に指定した$inventory_database
スキーマの Delta テーブルに保存されます。 これらのテーブルを使用して、 評価レポートを使用して詳細な分析と意思決定を行うことができます。 移行プロセスを開始する前に、すべての互換性のないエンティティが識別され、確認されていることを確認するために、評価ワークフローを複数回実行できます。
UCX で生成された README とDatabricks UI (ワークフロー > Jobs > [UCX] Assessment) から評価ワークフローをトリガーするか、次のDatabricks CLIコマンドを実行できます。
databricks labs ucx ensure-assessment-run
詳細な手順については、 「評価ワークフロー」を参照してください。
ステップ 2. グループ移行ワークフローを実行する
グループ移行ワークフローでは、ワークスペース ローカル グループをアカウント レベルのグループにアップグレードして、 Unity Catalogをサポートします。 これにより、適切なアカウント レベルのグループがワークスペースで使用可能になり、すべての権限が複製されます。 また、ワークスペースから不要なグループと権限も削除されます。 グループ移行ワークフローのタスクは、評価ワークフローの出力によって異なります。
各ワークフロー タスクの出力は、インストール時に指定した$inventory_database
スキーマの Delta テーブルに保存されます。 これらのテーブルを使用して、詳細な分析と意思決定を行うことができます。 グループ移行ワークフローを複数回実行して、すべてのグループが正常にアップグレードされ、必要なすべての権限が割り当てられていることを確認できます。
グループ移行ワークフローの実行に関する情報については、UCX によって生成された README と UCX readme 内のグループ移行ワークフローを参照してください。
ステップ 3. テーブル移行を実行する
テーブル移行ワークフローは、 Hive metastoreからUnity Catalogメタストアにテーブルをアップグレードします。 内の外部テーブルは、SYNC を使用してHive metastore Unity Catalog内の外部テーブルとしてアップグレードされます。Hive metastoreワークスペース ストレージ (DBFS ルートとも呼ばれます) に保存されている 内の管理対象テーブルは、Unity Catalog DEEP CLONE を使用して 内の管理対象テーブルとしてアップグレードされます。
Hive マネージドテーブルをアップグレードするには、Delta または Parquet 形式である必要があります。 外部 Hive テーブルは、「外部テーブルの操作」にリストされているデータ形式のいずれかである必要があります。
準備コマンドを実行する
テーブル移行には、テーブル移行ワークフローを実行する前に実行するいくつかの準備タスクが含まれます。 これらのタスクは、次の Databricks CLI コマンドを使用して実行します。
create-table-mapping
コマンドは、ターゲットの Unity Catalog カタログ、スキーマ、およびテーブルを、アップグレードされる各 Hive テーブルにマップする CSV ファイルを作成します。 移行ワークフローを続行する前に、マッピング ファイルを確認して更新する必要があります。create-uber-principal
コマンドは、このワークスペース内のテーブルによって使用されるすべてのストレージへの読み取り専用アクセス権を持つサービスプリンシパルを作成します。 ワークフロー ジョブ コンピュート リソースは、このプリンシパルを使用してワークスペース内のテーブルをアップグレードします。 アップグレードが完了したら、この サービスプリンシパル のプロビジョニングを解除します。(オプション) ワークスペース内の Hive テーブルで使用されるストレージ アカウントとストレージ アクセス資格情報を識別します。
principal-prefix-access
コマンド。(オプション)
migrate-credentials
コマンドは、principal-prefix-access
で識別されるストレージ アクセス資格情報から Unity Catalog ストレージ資格情報を作成します。(オプション)
migration locations
コマンドは、migrate-credentials
によって作成されたストレージ資格情報を使用して、評価ワークフローによって識別されたストレージの場所からUnity Catalog外部場所を作成します。(オプション) アップグレードされたテーブルを保持する Unity Catalog カタログとスキーマを作成する
create-catalogs-schemas
コマンド。
追加のテーブル移行ワークフロー コマンドとオプションを含む詳細については、UCX readme のテーブル移行コマンドを参照してください。
テーブル移行を実行する
準備タスクを実行したら、UCX で生成された README から、またはワークスペース UI の[ワークフロー] > [ジョブ]からテーブル移行ワークフローを実行できます。
各ワークフロー タスクの出力は、インストール時に指定した$inventory_database
スキーマの Delta テーブルに保存されます。 これらのテーブルを使用して、詳細な分析と意思決定を行うことができます。 すべてのテーブルが正常にアップグレードされたことを確認するには、テーブル移行ワークフローを複数回実行する必要がある場合があります。
完全なテーブル移行手順については、UCX で生成された README ノートブックと、UCX readme のテーブル移行ワークフローを参照してください。
その他のツール
UCX には、移行を成功させるのに役立つデバッグ ツールやその他のユーティリティも含まれています。 詳細については、UCX で生成された README およびUCX プロジェクトの readmeを参照してください。
UCXインストールのアップグレード
UCXプロジェクトは定期的に更新されます。 UCX インストールを最新バージョンにアップグレードするには:
UCX がインストールされていることを確認します。
databricks labs installed Name Description Version ucx Unity Catalog Migration Toolkit (UCX) 0.20.0
アップグレードを実行します:
databricks labs upgrade ucx
ヘルプを活用
UCX CLI のヘルプについては、次を実行してください。
databricks labs ucx --help
特定の UCX コマンドのヘルプについては、次を実行してください。
databricks labs ucx <command> --help
問題をトラブルシューティングするには:
デバッグ ログを有効にするには、任意のコマンドで
--debug
を実行します。UCX によって自動的に生成されるデバッグ ノートブックを使用します。
問題や機能リクエストを提出するには、 GitHub の問題を提出してください。
UCX リリースノート
UCX GitHub リポジトリの 変更ログを参照してください。