使用UCX公用程式將您的工作區升級至 Unity 目錄

本文介紹 UCX，這是 Databricks Labs 專案，其提供工具來協助您將非 Unity 目錄工作區升級至 Unity 目錄。

注意

UCX 就像 databrickslabs GitHub 帳戶中的所有項目一樣，只會提供您探索，且 Databricks 並未正式支援服務等級協定 （SLA）。 它會依目前提供。 我們不保證任何形式的保證。 請勿提交 Databricks 支援票證，該票證與使用此項目時發生的問題有關。 請改為 提出 GitHub 問題。 問題會檢閱為時間許可，但沒有正式的 SLA 支援。

UCX 專案提供下列移轉工具和工作流程：

1. 評定工作流程 可協助您規劃移轉。
2. 群組移轉工作流程 可協助您將群組成員資格從工作區升級至 Databricks 帳戶，並將許可權移轉至新的帳戶層級群組。
3. 數據表移轉工作流程 可協助您將工作區 Hive 中繼存放區中註冊的數據表升級至 Unity 目錄中繼存放區。 此工作流程也可協助您移轉儲存位置，以及存取它們所需的認證。

下圖顯示整體移轉流程，依名稱識別移轉工作流程和公用程式：

注意

圖表中所描述的程式代碼移轉工作流程仍在開發中，但尚無法使用。

開始之前

您必須先符合下列需求，才能安裝UCX並執行UCX工作流程。

在您執行 UCX 的電腦上安裝套件：

• Databricks CLI v0.213 或更新版本。 請參閱安裝或更新 Databricks CLI。

  您必須有 Databricks 組態檔，其中包含工作區和 Databricks 帳戶的組態配置檔。

• Python 3.10 或更新版本。

• 如果您想要執行 UCX 工作流程，以識別您工作區中 Hive 數據表所使用的儲存位置（建議但不需要），您必須在執行 UCX 工作流程的電腦上安裝雲端記憶體提供者的 CLI（Azure CLI 或 AWS CLI）。

網路存取：

• 從執行UCX安裝的電腦到您要移轉的 Azure Databricks 工作區進行網路存取。
• 從執行UCX安裝的電腦存取因特網。 這是存取 pypi.org 和 github.com 的必要專案。
• 從 Azure Databricks 工作區存取網路，以 pypi.org 下載 databricks-sdk 和 pyyaml 套件。

Databricks 角色和許可權：

• 執行UCX安裝之使用者的 Azure Databricks 帳戶管理員和工作區管理員角色。 您無法以服務主體的形式執行安裝。

其他 Databricks 必要條件：

• 針對裝載您要升級之工作區的每個區域所建立的 Unity 目錄中繼存放區，其中每個 Azure Databricks 工作區都附加至 Unity 目錄中繼存放區。

  若要瞭解如何判斷您是否已經有相關工作區區域中的 Unity 目錄中繼存放區、如何建立中繼存放區，以及如何將 Unity 目錄中繼存放區附加至工作區，請參閱 <步驟 1：確認已在 Unity 目錄設定>一文中啟用 Unity 目錄的工作區。 或者，UCX 提供 公用程式，將 Unity 目錄中繼存放區指派給安裝 UCX 之後可以使用的 工作區。

  將 Unity 目錄中繼存放區附加至工作區也會啟用 身分識別同盟，您可以在其中集中管理 Azure Databricks 帳戶層級的使用者管理，這也是使用 UCX 的必要條件。 請參閱 啟用身分識別同盟。

• 如果您的工作區使用外部 Hive 中繼存放區（例如 AWS Glue），而不是預設工作區本機 Hive 中繼存放區，您必須執行一些必要條件設定。 請參閱 databrickslabs/ucx 存放庫中的外部 Hive 中繼存放區整合 。

• 在您執行UCX工作流程的工作區上執行的 Pro或無伺服器 SQL 倉儲，需要轉譯評量工作流程所產生的報表。

安裝UCX

若要安裝 UCX，請使用 Databricks CLI：

databricks labs install ucx

系統會提示您選擇下列專案：

1. 您要升級之工作區的 Databricks 組態配置檔。 組態檔也必須包含工作區父 Databricks 帳戶的組態配置檔。

2. 清查資料庫的名稱，將用來儲存移轉工作流程的輸出。 一般而言，選取預設值是 ucx。。

3. 要執行安裝程式的 SQL 倉儲。

4. 您要移轉至帳戶層級群組的工作區本地組清單。 如果您將此保留為預設值 （<ALL>），則任何名稱符合工作區本地組的現有帳戶層級群組，都會被視為該工作區本地組的取代專案，並在安裝后執行 群組移轉工作流程 時繼承其所有工作區許可權。

   您有機會在執行安裝程式和執行群組移轉之前，修改 workspace-group-to-account-group 對應。 請參閱 UCX 存放庫中的組名衝突解決 。

5. 如果您有外部 Hive 中繼存放區，例如 AWS Glue，您可以選擇與其連線。 請參閱 databrickslabs/ucx 存放庫中的外部 Hive 中繼存放區整合 。

6. 是否要開啟產生的自述檔筆記本。

安裝完成後，它會在工作區中部署自述檔筆記本、儀錶板、資料庫、連結庫、作業和其他資產。

如需詳細資訊，請參閱 專案自述檔中的安裝指示。 您也可以 在 Databricks 帳戶中的所有工作區上安裝 UCX。

開啟自述檔筆記本

每個安裝都會建立自述檔筆記本，以提供所有工作流程和工作的詳細描述，並提供工作流程和儀錶板的快速連結。 請參閱 自述檔筆記本。

步驟 1. 執行評定工作流程

評定工作流程會評估目前工作區中群組身分識別、儲存位置、記憶體認證、訪問控制和數據表的 Unity 目錄相容性，並提供規劃移轉至 Unity 目錄所需的資訊。 根據指定的相依性，評定工作流程中的工作可以平行或循序執行。 評估工作流程完成後，評估儀錶板會填入結果和常見建議。

每個工作流程工作的輸出會儲存在您安裝期間所指定之架構中的 $inventory_database Delta 數據表中。 您可以使用這些數據表，使用評量報告執行進一步分析和決策。 您可以多次執行評定工作流程，以確保在開始移轉程式之前，先識別並考慮所有不相容的實體。

您可以從 UCX 產生的自述檔筆記本和 Azure Databricks UI 觸發評定工作流程（工作流程 > 作業 > [UCX] 評定），或執行下列 Databricks CLI 命令：

databricks labs ucx ensure-assessment-run

如需詳細指示，請參閱 評定工作流程。

步驟 2. 執行群組移轉工作流程

群組移轉工作流程會將工作區-本地組升級至帳戶層級群組，以支援 Unity 目錄。 它可確保工作區中提供適當的帳戶層級群組，並復寫所有許可權。 它也會從工作區中移除任何不必要的群組和許可權。 群組移轉工作流程中的工作取決於評定工作流程的輸出。

每個工作流程工作的輸出會儲存在您安裝期間所指定之架構中的 $inventory_database Delta 數據表中。 您可以使用這些資料表來執行進一步分析和決策。 您可以多次執行群組移轉工作流程，以確保所有群組都已成功升級，並已指派所有必要的許可權。

如需執行群組移轉工作流程的相關信息，請參閱 UCX 自述檔中的 UCX 產生的自述檔筆記本和 群組移轉工作流程 。

步驟 3. 執行數據表移轉工作流程

數據表移轉工作流程會將數據表從Hive中繼存放區升級至 Unity 目錄中繼存放區。 Hive 中繼存放區中的外部數據表會使用 SYNC 升級為 Unity 目錄中的外部資料表。 Hive 中繼存放區中儲存在工作區記憶體中的受控數據表（也稱為 DBFS 根目錄）會使用 DEEP CLONE 升級為 Unity 目錄中的受控數據表。

Hive Managed 數據表必須是 Delta 或 Parquet 格式，才能升級。 外部 Hive 資料表必須是使用外部資料表中列出的其中一種數據格式。

執行準備命令

數據表移轉包含您在執行數據表移轉工作流程之前所執行的一些準備工作。 您可以使用下列 Databricks CLI 命令來執行這些工作：

• create-table-mapping命令會建立 CSV 檔案，將目標 Unity 目錄、架構和數據表對應至將升級的每個 Hive 數據表。 您應該先檢閱並更新對應檔案，再繼續進行移轉工作流程。
• create-uber-principal此命令會建立服務主體，並具有此工作區中數據表所用之所有記憶體的唯讀存取權。 工作流程作業計算資源會使用此主體來升級工作區中的數據表。 當您完成升級時，取消布建此服務主體。
• （選擇性） principal-prefix-access 命令，識別工作區中 Hive 數據表所使用的記憶體帳戶和記憶體存取認證。
• （選擇性） migrate-credentials 命令，從所 principal-prefix-access識別的記憶體存取認證建立 Unity 目錄記憶體認證。
• （選擇性） migration locations 命令會使用 所 migrate-credentials建立的記憶體認證，從評量工作流程所識別的儲存位置建立 Unity Catalog 外部位置。
• （選擇性）命令 create-catalogs-schemas會建立將保存已升級數據表的 Unity 目錄和架構。

如需詳細資訊，包括其他數據表移轉工作流程命令和選項，請參閱 UCX 自述檔中的數據表移轉命令 。

執行數據表移轉

執行準備工作之後，您可以從 UCX 產生的自述檔筆記本，或從 工作區 UI 中的工作流程 > 作業 執行數據表移轉工作流程。

每個工作流程工作的輸出會儲存在您安裝期間所指定之架構中的 $inventory_database Delta 數據表中。 您可以使用這些資料表來執行進一步分析和決策。 您可能需要多次執行數據表移轉工作流程，以確保所有數據表都已成功升級。

如需完整的數據表移轉指示，請參閱 UCX 自述檔中的 UCX 產生的自述檔筆記本和 數據表移轉工作流程 。

其他工具

UCX 也包含：

• 啟用 Hive 中繼存放區同盟的公用程式，Azure Databricks 整合工具可讓 Unity 目錄控管 Hive 中繼存放區中註冊的數據表：

  • enable-hms-federation
  • create-federated-catalog

  Hive 中繼存放區同盟可讓您在舊版 Hive 中繼存放區及其 Unity 目錄中的鏡像上執行工作負載，以協助移轉，以緩和轉換至 Unity 目錄。 如需在移轉案例中使用Hive中繼存放區同盟的詳細資訊，請參閱 如何在移轉至 Unity 目錄期間使用 Hive 中繼存放區同盟？。

• 偵錯工具和其他公用程式，以協助您成功進行移轉。

如需詳細資訊，請參閱由UCX產生的自述檔筆記本和 UCX專案自述檔。

升級您的UCX安裝

UCX 專案會定期更新。 若要將 UCX 安裝升級至最新版本：

1. 確認已安裝UCX。

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

2. 執行升級：

   databricks labs upgrade ucx
   

取得協助

如需UCX CLI的說明，請執行：

databricks labs ucx --help

如需特定 UCX 命令的說明，請執行：

databricks labs ucx <command> --help

若要針對問題進行疑難解答：

• 使用任何命令執行 --debug 以啟用 偵錯記錄。
• 使用由UCX自動產生的偵錯筆記本。

若要提出問題或功能要求，請提出 GitHub 問題。

UCX 版本資訊

請參閱 UCX GitHub 存放庫中的變更記錄。