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 リポジトリの変更ログを参照してください。