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

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

注意

UCX（与 databrickslabs GitHub 帐户中的所有项目一样）仅用于探索，并且 Databricks 未正式支持服务级别协议（SLA）。 它按原样提供。 我们不提供任何形式的保证。 请勿提交与使用本项目所产生问题相关的 Databricks 支持工单。 请改为提交GitHub问题。 问题将根据时间的允许进行审查，但没有正式的支持服务水平协议（SLA）。

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

  1. 评估工作流，可帮助规划迁移。

  2. 组迁移工作流，可帮助你将组成员身份从工作区升级到 Databricks 帐户，并将权限迁移到新的帐户级组。

  3. 表迁移工作流，有助于将工作区的 Hive 元存储中注册的表升级到 Unity Catalog 元存储。 此工作流还有助于迁移存储位置以及访问存储位置所需的凭据。

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

UCX 迁移工作流图表

注意

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

有关使用 UXC 升级工作区的演示，请参阅 使用 UCX 进行架构升级。

开始之前

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

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

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

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

  • Python 3.10 或更高版本。

  • 如果要运行用于识别工作区中由 Hive 表使用的存储位置的 UCX 工作流（虽然推荐，但不是必须的），则必须在运行 UCX 工作流的计算机上安装云存储提供程序的 CLI（Azure CLI 或 AWS CLI）。

网络访问：

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

Databricks 角色和权限：

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

其他 Databricks 先决条件：

  • 为每个托管待升级工作区的区域创建 Unity Catalog 元存储，并将这些 Azure Databricks 工作区附加到 Unity Catalog 元存储。

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

    将 Unity Catalog 元存储附加到工作区还启用了身份联合，可以在 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 metastore（例如 AWS Glue），可以选择是否连接到它。 请参阅 databrickslabs/ucx 存储库中的Hive 外部元存储集成。

  6. 是否打开生成的README文档。

安装完成后，它将在您的工作区中部署 README 笔记本、仪表板、数据库、代码库、作业和其他资产。

有关详细信息，请参阅项目自述文件中的安装说明。 还可以在 Databricks 帐户中的所有工作区上安装 UCX。

打开README文件

每个安装都会创建一个自述文件笔记本，该笔记本提供所有工作流和任务的详细说明，并快速链接到工作流和仪表板。 请参阅Readme 笔记本。

步骤 1. 运行评估工作流

评估工作流评估当前工作区中组标识、存储位置、存储凭据、访问控制和表的 Unity 目录兼容性，并提供计划迁移到 Unity 目录所需的信息。 评估工作流中的任务可以并行或按顺序执行，具体取决于指定的依赖项。 评估工作流完成后，会填充评估仪表板，其中包含发现和常见建议。

每个工作流任务的输出存储在安装期间指定的 $inventory_database 架构中的 Delta 表中。 可以使用这些表通过评估报告执行进一步分析和决策。 可以多次运行评估工作流，以确保在开始迁移过程之前识别并考虑所有不兼容的实体。

可以从 UCX 生成的 README 笔记本和 Azure Databricks 用户界面（工作流>作业> [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 Catalog（统一目录）中的托管表。

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 Catalog 存储凭据。
  • （可选）migration locations 命令，用于使用 migrate-credentials 创建的存储凭据从评估工作流标识的存储位置创建 Unity 目录外部位置。
  • （可选）create-catalogs-schemas命令，用于创建 Unity Catalog 中的目录和模式，以保存升级后的表。

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

运行表迁移

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

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

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

其他工具

UCX 还包括：

  • 用于启用 Hive 元存储联合 的 Azure Databricks 集成工具，可通过 Unity Catalog 管理在 Hive 元存储中注册的表：

    • 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

若要排查问题：请执行以下操作：

若要提交问题或功能请求，请提交GitHub问题。

UCX 发行说明

请参阅 UCX GitHub 存储库中的 changelog。

  • Last updated on