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