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

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

注記

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

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

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

次の図は、全体的な移行フローを示しており、移行ワークフローとユーティリティを名前で識別しています。

UCX 移行ワークフローチャート

注記

図に示されているコード移行ワークフローは、まだ開発中であり、まだ使用できません。

始める前に

UCX をインストールして UCX ワークフローを実行する前に、環境が次の要件を満たしている必要があります。

UCX を実行するコンピューターにインストールされているパッケージ :

Databricks CLI v0.213 以降。「Databricks CLI のインストールまたは更新」を参照してください。

ワークスペースと Databricks アカウントの両方の構成プロファイルを含む Databricks 構成ファイルが必要です。
Python 3.10 以降。
ワークスペース内のテーブルで使用されるストレージの場所を特定する UCX ワークフローを実行する場合HiveCLI AzureCLIAWSCLI(推奨されますが、必須ではありません)、UCX ワークフローを実行するコンピュータに、クラウドストレージプロバイダ ( または) のがインストールされている必要があります。

ネットワークアクセス :

UCX インストールを実行するコンピューターから、移行する Databricks ワークスペースへのネットワークアクセス。
UCX インストールを実行しているコンピューターからインターネットへのネットワークアクセス。これは、pypi.org と github.com にアクセスするために必要です。
Databricks ワークスペースから pypi.org へのネットワークアクセスで、 databricks-sdk パッケージと 1 pyyaml パッケージをダウンロードします。

Databricks のロールとアクセス許可 :

UCX インストールを実行するユーザーの Databricks アカウント管理者とワークスペース管理者ロール。インストールをサービスプリンシパルとして実行することはできません。

その他の Databricks の前提条件 :

アップグレードするワークスペースをホストするすべてのリージョンに対して作成された Unity Catalog メタストアで、それらの Databricks ワークスペースのそれぞれが Unity Catalog メタストアにアタッチされています。

関連するワークスペースリージョンに Unity Catalog メタストアが既に存在するかどうかを確認する方法、メタストアがない場合にメタストアを作成する方法、および Unity Catalog メタストアをワークスペースにアタッチする方法については、Unity Catalog のセットアップに関する記事の「手順 1: ワークスペースで Unity Catalog が有効になっていることを確認する」を参照してください。別の方法として、UCX には、UCX のインストール後に使用できるワークスペースに Unity Catalog メタストアを割り当てるためのユーティリティが用意されています。

Unity Catalog メタストアをワークスペースにアタッチすると、 ID フェデレーション も有効になり、UCX を使用するための前提条件でもある Databricks アカウントレベルでユーザー管理を一元化できます。「ID フェデレーションを有効にする」を参照してください。
ワークスペースで Hive metastoreAWS Glueではなく外部Hive metastore ( など) を使用している場合は、前提条件の設定を行う必要があります。databrickslabs/ucx リポジトリの「外部 Hive metastore 統合」を参照してください。
UCX ワークフローを実行するワークスペースで実行されている Pro またはサーバレス SQLウェアハウス (評価ワークフローによって生成されたレポートをレンダリングするために必要です)。

UCXのインストール

UCX をインストールするには、Databricks CLI を使用します。

Bash
databricks labs install ucx

以下を選択するように求められます。

アップグレードするワークスペースの Databricks 構成プロファイル。構成ファイルには、ワークスペースの親 Databricks アカウントの構成プロファイルも含まれている必要があります。
移行ワークフローの出力を格納するために使用されるインベントリデータベースの名前。通常は、デフォルトの ucxを選択しても問題ありません。
インストールプロセスを実行するための SQLウェアハウス。
アカウントレベルのグループに移行するワークスペースローカルグループのリスト。これをデフォルト (<ALL>) のままにすると、名前がワークスペースローカルグループと一致する既存のアカウントレベルグループは、そのワークスペースローカルグループの置き換えとして扱われ、インストール後にグループ移行ワークフローを実行するときに、そのすべてのワークスペース権限を継承します。

インストーラーを実行した後、グループ移行を実行する前に、ワークスペースグループからアカウントグループへのマッピングを変更する機会があります。「UCX リポジトリのグループ名の競合解決」を参照してください。
外部 Hive metastoreがある場合、 AWS Glue、それに接続するかどうかを選択できます。 databrickslabs/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 コマンドを実行できます。

Bash

databricks labs ucx ensure-assessment-run

詳細な手順については、「評価ワークフロー」を参照してください。

ステップ2.グループ移行ワークフローを実行する

グループ migration ワークフローは、ワークスペース-local グループをアカウントレベルのグループにアップグレードして、 Unity Catalogをサポートします。これにより、適切なアカウントレベルのグループがワークスペースで使用できるようになり、すべてのアクセス許可がレプリケートされます。また、不要なグループとアクセス許可もワークスペースから削除されます。グループ移行ワークフローのタスクは、評価ワークフローの出力によって異なります。

各ワークフロータスクの出力は、インストール時に指定した $inventory_database スキーマの Delta テーブルに格納されます。これらのテーブルを使用して、詳細な分析と意思決定を行うことができます。グループ移行ワークフローを複数回実行して、すべてのグループが正常にアップグレードされ、必要なすべてのアクセス許可が割り当てられていることを確認できます。

グループ移行ワークフローの実行に関する情報については、UCX で生成された README ノートブックと UCX readme のグループ移行ワークフローを参照してください。

ステップ3.テーブル移行ワークフローを実行する

テーブル移行ワークフローでは、テーブルを Hive metastore から Unity Catalog メタストアにアップグレードします。内の外部テーブルは、Hive metastore Unity Catalogを使用して、SYNC の外部テーブルとしてアップグレードされます。Hive metastoreワークスペースストレージ(DBFS ルートとも呼ばれます)に保存されている内のマネージドテーブルは、Unity Catalogディープクローンを使用して、のマネージドテーブルとしてアップグレードされます。

Hive マネージドテーブルは、アップグレードする Delta 形式または Parquet 形式である必要があります。外部 Hive テーブルは、「外部テーブルの操作」に記載されているデータ形式のいずれかである必要があります。

準備コマンドを実行する

テーブル移行には、テーブル移行ワークフローを実行する前に実行するいくつかの準備タスクが含まれます。これらのタスクは、次の Databricks CLI コマンドを使用して実行します。

create-table-mapping コマンドは、ターゲット Unity Catalog カタログ、スキーマ、およびテーブルをアップグレードする各 Hive テーブルにマップする CSV ファイルを作成します。移行ワークフローを続行する前に、マッピングファイルを確認して更新する必要があります。
create-uber-principal コマンドは、このワークスペース内のテーブルで使用されるすべてのストレージへの読み取り専用アクセス権を持つサービスプリンシパルを作成します。ワークフロージョブコンピュートリソースは、このプリンシパルを使用してワークスペース内のテーブルをアップグレードします。アップグレードが完了したら、このサービスプリンシパルのプロビジョニングを解除します。
(オプション) principal-prefix-access コマンドは、ワークスペース内の Hive テーブルで使用されるストレージアカウントとストレージアクセス資格情報を識別します。
(オプション) migrate-credentials コマンドは、 principal-prefix-accessで識別されるストレージアクセス資格情報から Unity Catalog ストレージ資格情報を作成します。
(オプション)migration locations コマンドは、migrate-credentials によって作成されたストレージ資格情報を使用して、評価ワークフローによって識別されたストレージロケーションから Unity Catalog 外部ロケーションを作成します。
(オプション) create-catalogs-schemasコマンドは、アップグレードされたテーブルを保持する Unity Catalog カタログとスキーマを作成します。

追加のテーブル移行ワークフローコマンドとオプションなどの詳細については、UCX readme の「テーブル移行コマンド」を参照してください。

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

準備タスクを実行したら、UCX で生成された README ノートブックから、またはワークスペース UI の ワークフロー > ジョブ から、テーブル移行ワークフローを実行できます。

各ワークフロータスクの出力は、インストール時に指定した $inventory_database スキーマの Delta テーブルに格納されます。これらのテーブルを使用して、詳細な分析と意思決定を行うことができます。すべてのテーブルが正常にアップグレードされるように、テーブル移行ワークフローを複数回実行する必要がある場合があります。

テーブル移行の詳細な手順については、UCX で生成された README ノートブックと UCX readme のテーブル移行ワークフローを参照してください。

その他のツール

UCXには、次のものも含まれます。

に登録されたテーブルを管理できるようにする統合ツールであるフェデレーションを有効にするユーティリティ:Hive metastoreDatabricksUnity CatalogHive metastore
- enable-hms-federation
- create-federated-catalog
Hive metastore フェデレーションは、レガシ Hive metastore とそのミラーの両方でワークロードを Unity Catalogで実行できるようにすることで移行を支援し、 Unity Catalogへの移行を容易にします。 Hive metastore移行シナリオでのフェデレーションの使用の詳細については、「Hive metastoreへの移行中にUnity Catalog フェデレーションをどのように使用しますか? 」を参照してください。
移行を成功させるためのデバッグツールとその他のユーティリティ。

詳細については、UCX で生成された README ノートブックと UCX プロジェクトの readme を参照してください。

UCX インストールをアップグレードする

UCXプロジェクトは定期的に更新されます。 UCXインストールを最新バージョンにアップグレードするには：

UCX がインストールされていることを確認します。

Bash
databricks labs installed

Name  Description                            Version
ucx   Unity Catalog Migration Toolkit (UCX)  0.20.0

アップグレードを実行します。
Bash
```
databricks labs upgrade ucx
```

助けを求める

UCX CLI のヘルプについては、次を実行します。

Bash

databricks labs ucx --help

特定の UCX コマンドのヘルプについては、次のコマンドを実行します。

Bash
databricks labs ucx <command> --help

問題のトラブルシューティングを行うには：

任意のコマンドで --debug を実行して、デバッグログを有効にします。
UCX によって自動的に生成されるデバッグノートブックを使用します。

問題または機能リクエストを提出するには、 GitHub の問題を提出してください。

UCX リリースノート

UCX GitHub リポジトリの変更ログを参照してください。

始める前に​

UCXのインストール​

README ノートブックを開く​

ステップ1.評価ワークフローを実行する​

ステップ2.グループ移行ワークフローを実行する​

ステップ3.テーブル移行ワークフローを実行する​

準備コマンドを実行する​

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

その他のツール​

UCX インストールをアップグレードする​

助けを求める​

UCX リリースノート​