UCX ユーティリティを使用してワークスペースを Unity Catalog にアップグレードする

[アーティクル]
05/03/2024

この記事では、Unity Catalog 以外のワークスペースを Unity Catalog にアップグレードするのに役立つツールを提供する Databricks Labs プロジェクトである UCX について説明します。

Note

UCX は、databrickslabs GitHub アカウント内のすべてのプロジェクトと同様に、探索専用に提供され、サービスレベルアグリーメント (SLA) をのある Databricks では正式にはサポートされていません。そのまま提供されます。当社は、いかなる種類の保証も行いません。このプロジェクトの使用によって発生する問題に関連する Databricks サポートチケットを送信しないでください。代わりに、GitHub の問題を報告してください。問題は時間の許す限り見直されますが、サポートのための正式な SLA はありません。

UCX プロジェクトには、次の移行ツールとワークフローが用意されています:

移行の計画に役立つ評価ワークフロー。
ワークスペースから Databricks アカウントにグループメンバーシップをアップグレードし、アクセス許可を新しいアカウントレベルのグループに移行するのに役立つグループ移行ワークフロー。
ワークスペースの Hive メタストアに登録されているテーブルを Unity Catalog メタストアにアップグレードするのに役立つテーブル移行のワークフロー。このワークフローは、ストレージの場所とその場所にアクセスするために必要な資格情報を移行するのにも役立ちます。

次の図は、移行フロー全体を示し、名前で移行ワークフローとユーティリティを識別します:

UCX 移行ワークフローのグラフ

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

次の方法で共有

UCX ユーティリティを使用してワークスペースを Unity Catalog にアップグレードする

開始する前に

UCX のインストール

README ノートブックを開く

手順 1. 評価ワークフローを実行する

手順 2. グループ移行ワークフローの実行

手順 3. テーブル移行ワークフローを実行する

準備コマンドの実行

テーブルの移行を実行する

その他のツール

UCX インストールのアップグレード

ヘルプを取得

UCX リリースノート

フィードバック

フィードバック

その他のリソース

次の方法で共有

UCX ユーティリティを使用してワークスペースを Unity Catalog にアップグレードする

開始する前に

UCX のインストール

README ノートブックを開く

手順 1. 評価ワークフローを実行する

手順 2. グループ移行ワークフローの実行

手順 3. テーブル移行ワークフローを実行する

準備コマンドの実行

テーブルの移行を実行する

その他のツール

UCX インストールのアップグレード

ヘルプを取得

UCX リリース ノート

フィードバック

フィードバック

その他のリソース

UCX リリースノート