使用 UCX 实用工具将工作区升级到 Unity 目录

本文介绍 UCX，这是一个 Databricks Labs 项目，该项目提供的工具可帮助你将非 Unity 目录工作区升级到 Unity 目录。

注意

与 databrickslabs GitHub 帐户中的所有项目一样，UCX 仅用于探索，Databricks 没有正式支持服务级别协议 (SLA)。 它按原样提供。 我们不提供任何形式的保证。 请勿提交与使用本项目所产生问题相关的 Databricks 支持工单。 正确的做法是提交 GitHub 问题。 在时间允许的情况下，将对问题进行审查，但没有正式的支持 SLA。

UCX 项目提供以下迁移工具和工作流：

1. 评估工作流，可帮助规划迁移。
2. 组迁移工作流，可帮助你将组成员身份从工作区升级到 Databricks 帐户，并将权限迁移到新的帐户级组。
3. 表迁移工作流，有助于将注册在工作区的 Hive 元存储中的表升级到 Unity Catalog 元存储。 此工作流还有助于迁移存储位置以及访问存储位置所需的凭据。

下图显示了总体迁移流，按名称标识迁移工作流和实用工具：

注意

关系图中显示的代码迁移工作流仍处于开发阶段，尚不可用。

开始之前

在安装 UCX 并运行 UCX 工作流之前，环境必须满足以下要求。

在运行 UCX 的计算机上安装的包：

• Databricks CLI v0.213 或更高版本。 请参阅安装或更新 Databricks CLI。

  必须有一个 Databricks 配置文件，其中包含工作区和 Databricks 帐户的配置文件。

• Python 3.10 或更高版本。

• 如果想要运行 UCX 工作流，用于标识 Hive 表在工作区中使用的存储位置（建议但非必需），则必须在运行 UCX 工作流的计算机上安装云存储提供程序（Azure CLI 或 AWS CLI）的 CLI。

网络访问：

• 从运行 UCX 安装的计算机到要迁移的 Azure Databricks 工作区的网络访问。
• 从运行 UCX 安装的计算机对 Internet 进行网络访问。 这是访问 pypi.org 和 github.com 所必需的。
• 从 Azure Databricks 工作区进行网络访问，通过 pypi.org 下载 databricks-sdk 和 pyyaml 包。

Databricks 角色和权限：

• 运行 UCX 安装的用户的 Azure Databricks 帐户管理员和工作区管理员角色。 不能将安装作为服务主体运行。

其他 Databricks 先决条件：

• 为托管要升级的工作区的每个区域创建的 Unity 目录元存储，其中每个 Azure Databricks 工作区都附加到 Unity 目录元存储。

  要了解如何确定相关工作区区域中是否已有 Unity Catalog 元存储、如何创建元存储（如果没有）以及如何将 Unity Catalog 元存储附加到工作区，请参阅 Unity Catalog 设置文章中的步骤 1：确认工作区已启用 Unity Catalog。 为此，UCX 提供了一个实用工具，用于将 Unity 目录元存储分配给安装 UCX 后可以使用的工作区。

  将 Unity 目录元存储附加到工作区还会启用联合身份验证，可在其中将用户管理集中到 Azure Databricks 帐户级别，这也是使用 UCX 的先决条件。 请参阅“启用联合身份验证”。

• 如果工作区使用外部 Hive 元存储（如 AWS Glue），而不是默认工作区本地 Hive 元存储，则必须执行一些先决条件设置。 请参阅 UCX 文档中 外部 Hive 元存储集成。

• 在运行 UCX 工作流的工作区上运行的 Pro 或无服务器 SQL 仓库，呈现评估工作流生成的报表所必需的。

安装 UCX

若要安装 UCX，请使用 Databricks CLI：

databricks labs install ucx

系统会提示你选择以下内容：

1. 要升级的工作区的 Databricks 配置文件。 配置文件还必须包含工作区的 Databricks 父帐户的配置文件。

2. 清单数据库的名称，用于存储迁移工作流的输出。 通常可选择默认选项 ucx。

3. 要运行安装过程的 SQL 仓库。

4. 要迁移到帐户级组的工作区本地组的列表。 如果将此项保留为默认组 (<ALL>)，则与工作区本地组匹配的任何现有帐户级组都将被视为该工作区本地组的替换项，并在安装后运行组迁移工作流时继承其所有工作区权限。

   在运行安装程序和运行组迁移之前，你有机会修改工作区组到帐户组的映射。 请参阅 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 托管表必须采用 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 目录外部位置。
• （可选）create-catalogs-schemas命令，用于创建将保存升级表的 Unity 目录和架构。

有关详细信息，包括其他表迁移工作流命令和选项，请参阅 UCX 自述文件中的表迁移命令。

运行表迁移

运行准备任务后，可以从 UCX 生成的 README 笔记本或工作区 UI 中的作业和管道中运行表迁移工作流。

每个工作流任务的输出存储在安装期间指定的 $inventory_database 架构中的 Delta 表中。 可以使用这些表执行进一步分析和决策。 可能需要多次运行表迁移工作流，以确保所有表都已成功升级。

有关完整的表迁移说明，请参阅 UCX 生成的自述文件笔记本和 UCX 自述文件中的表迁移工作流。

其他工具

UCX 还包括：

• 用于启用 Hive 元存储联合的实用工具，这是使 Unity Catalog 能够管理注册在 Hive 元存储中的表的 Azure Databricks 集成工具：

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

  Hive 元存储联合有助于迁移，使你能够在旧版 Hive 元存储及其在 Unity 目录中的镜像上运行工作负载，从而简化向 Unity 目录的过渡。 有关在迁移方案中使用 Hive 元存储联合的更多信息，请参阅在迁移到 Unity Catalog 期间如何使用 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 存储库中的更改日志。