Использование служебных программ UCX для обновления рабочей области до каталога Unity

В этой статье представлен проект UCX, проект Databricks Labs, который предоставляет средства для обновления рабочей области, отличной от Unity-Catalog, до каталога Unity.

Примечание.

UCX, как и все проекты в учетной записи GitHub databrickslabs, предоставляются только для изучения и не поддерживаются databricks с соглашениями об уровне обслуживания (соглашения об уровне обслуживания). Он предоставляется как есть. Мы не делаем никаких гарантий любого рода. Не отправляйте запрос в службу поддержки Databricks, связанный с проблемами, возникающими при использовании этого проекта. Вместо этого отправьте файл проблемы с GitHub. Проблемы будут рассмотрены в качестве разрешений на время, но для поддержки нет официальных соглашений об уровне обслуживания.

Проект UCX предоставляет следующие средства миграции и рабочие процессы:

1. Рабочий процесс оценки для планирования миграции.
2. Рабочий процесс миграции групп поможет обновить членство в группе из рабочей области в учетную запись Databricks и перенести разрешения на новые группы на уровне учетной записи.
3. Рабочий процесс миграции таблиц поможет обновить таблицы, зарегистрированные в хранилище метаданных Hive рабочей области в хранилище метаданных каталога Unity. Этот рабочий процесс также помогает перенести расположения хранилища и учетные данные, необходимые для доступа к ним.

На этой схеме показан общий поток миграции, определяющий рабочие процессы миграции и служебные программы по имени:

Примечание.

Рабочий процесс миграции кода, показанный на схеме, остается в стадии разработки и пока недоступен.

Подготовка к работе

Прежде чем установить UCX и запустить рабочие процессы UCX, среда должна соответствовать следующим требованиям.

Пакеты, установленные на компьютере, на котором выполняется UCX:

• Databricks CLI версии 0.213 или более поздней версии. См. статью "Установка или обновление интерфейса командной строки Databricks".

  У вас должен быть файл конфигурации Databricks с профилями конфигурации для рабочей области и учетной записи Databricks.

• Python 3.10 или более поздней версии.

• Если вы хотите запустить рабочий процесс UCX, определяющий расположения хранилища, используемые таблицами Hive в рабочей области (рекомендуется, но не обязательно), необходимо установить интерфейс командной строки для поставщика облачных хранилищ (Azure CLI или AWS CLI) на компьютере, на котором выполняются рабочие процессы UCX.

Сетевой доступ:

• Сетевой доступ с компьютера, на котором выполняется установка UCX, в рабочую область Azure Databricks, которую вы переносите.
• Сетевой доступ к Интернету с компьютера, на котором выполняется установка UCX. Это необходимо для доступа к pypi.org и github.com.
• Сетевой доступ из рабочей области Azure Databricks для pypi.org для скачивания databricks-sdk и pyyaml пакетов.

Роли и разрешения Databricks:

• Роли администратора учетной записи Azure Databricks и администратора рабочей области для пользователя, выполняющего установку UCX. Невозможно запустить установку в качестве субъекта-службы.

Другие предварительные требования Databricks:

• Хранилище метаданных каталога Unity, созданное для каждого региона, в котором размещена рабочая область, которую требуется обновить, с каждой из этих рабочих областей Azure Databricks, подключенных к хранилищу метаданных каталога Unity.

  Чтобы узнать, есть ли хранилище метаданных каталога Unity в соответствующих регионах рабочей области, как создать хранилище метаданных, если вы этого не сделали, и как подключить хранилище метаданных каталога Unity к рабочей области, см . шаг 1. Убедитесь, что рабочая область включена для каталога Unity в статье установки каталога Unity. В качестве альтернативы UCX предоставляет программу для назначения хранилища метаданных каталога Unity рабочим областям, которые можно использовать после установки UCX.

  Присоединение хранилища метаданных каталога Unity к рабочей области также включает федерацию удостоверений, в которой вы централизируете управление пользователями на уровне учетной записи Azure Databricks, что также является необходимым условием для использования UCX. См. раздел "Включить федерацию удостоверений".

• Если в рабочей области используется внешнее хранилище метаданных Hive (например, AWS Glue) вместо хранилища метаданных Hive по умолчанию, необходимо выполнить некоторые предварительные требования. См . сведения об интеграции внешнего хранилища метаданных Hive в репозитории databrickslabs/ucx.

• Хранилище SQL Pro или Serverless SQL, работающее в рабочей области, в которой выполняются рабочие процессы UCX, необходимое для отрисовки отчета, созданного рабочим процессом оценки.

Установка UCX

Чтобы установить UCX, используйте интерфейс командной строки Databricks:

databricks labs install ucx

Вам будет предложено выбрать следующее:

1. Профиль конфигурации Databricks для рабочей области, которую требуется обновить. Файл конфигурации также должен содержать профиль конфигурации для родительской учетной записи Databricks рабочей области.

2. Имя базы данных инвентаризации, которая будет использоваться для хранения выходных данных рабочих процессов миграции. Обычно это нормально выбрать значение по умолчанию.ucx

3. Хранилище SQL для запуска процесса установки.

4. Список локальных групп рабочей области, которые необходимо перенести в группы на уровне учетной записи. Если вы оставьте это значение по умолчанию (<ALL>), любая существующая группа на уровне учетной записи, имя которой соответствует локальной группе рабочей области, будет рассматриваться как замена этой локальной группы рабочей области и наследует все разрешения рабочей области при запуске рабочего процесса миграции группы после установки.

   У вас есть возможность изменить сопоставление рабочей области с учетной записью после запуска установщика и перед выполнением миграции группы. См. раздел "Разрешение конфликтов имен групп" в репозитории UCX.

5. Если у вас есть внешнее хранилище метаданных Hive, например AWS Glue, вы можете подключиться к нему или нет. См . сведения об интеграции внешнего хранилища метаданных Hive в репозитории databrickslabs/ucx.

6. Следует ли открывать созданную записную книжку README.

После установки она развертывает записную книжку README, панели мониторинга, базы данных, библиотеки, задания и другие ресурсы в рабочей области.

Дополнительные сведения см. в инструкциях по установке в project readme. Вы также можете установить UCX во всех рабочих областях в учетной записи Databricks.

Открытие записной книжки README

Каждая установка создает записную книжку README, которая содержит подробное описание всех рабочих процессов и задач с краткими ссылками на рабочие процессы и панели мониторинга. См. записную книжку Readme.

Шаг 1. Запуск рабочего процесса оценки

Рабочий процесс оценки оценивает совместимость каталога Unity с удостоверениями групп, расположениями хранения, учетными данными хранения, элементами управления доступом и таблицами в текущей рабочей области и предоставляет сведения, необходимые для планирования миграции в каталог Unity. Задачи в рабочем процессе оценки можно выполнять параллельно или последовательно в зависимости от указанных зависимостей. После завершения рабочего процесса оценки панель мониторинга оценки заполняется результатами и общими рекомендациями.

Выходные данные каждой задачи рабочего процесса хранятся в таблицах Delta в схеме, указанной $inventory_database во время установки. Эти таблицы можно использовать для дальнейшего анализа и принятия решений с помощью отчета об оценке. Рабочий процесс оценки можно запускать несколько раз, чтобы убедиться, что все несовместимые сущности определены и учитываются перед началом процесса миграции.

Вы можете активировать рабочий процесс оценки из записной книжки README, созданной UCX, и пользовательского интерфейса Azure Databricks (задания > рабочих > процессов [UCX]), или выполнить следующую команду Cli Databricks:

databricks labs ucx ensure-assessment-run

Подробные инструкции см. в разделе "Рабочий процесс оценки".

Шаг 2. Запуск рабочего процесса миграции группы

Рабочий процесс миграции группы обновляет локальные группы рабочей области до групп на уровне учетных записей для поддержки каталога Unity. Это гарантирует, что соответствующие группы на уровне учетной записи доступны в рабочей области и реплицируют все разрешения. Он также удаляет ненужные группы и разрешения из рабочей области. Задачи в рабочем процессе миграции группы зависят от выходных данных рабочего процесса оценки.

Выходные данные каждой задачи рабочего процесса хранятся в таблицах Delta в схеме, указанной $inventory_database во время установки. Эти таблицы можно использовать для дальнейшего анализа и принятия решений. Рабочий процесс миграции группы можно запустить несколько раз, чтобы убедиться, что все группы успешно обновлены и назначены все необходимые разрешения.

Сведения о выполнении рабочего процесса миграции группы см. в созданной UCX записной книжке README и рабочем процессе миграции групп в UCX.

Шаг 3. Запуск рабочего процесса миграции таблицы

Рабочий процесс миграции таблиц обновляет таблицы из хранилища метаданных Hive в хранилище метаданных каталога Unity. Внешние таблицы в хранилище метаданных Hive обновляются как внешние таблицы в каталоге Unity с помощью SYNC. Управляемые таблицы в хранилище метаданных Hive, хранящиеся в хранилище рабочих областей (также известный как корневой каталог DBFS), обновляются как управляемые таблицы в каталоге Unity с помощью DEEP CLONE.

Управляемые таблицы Hive должны быть в формате Delta или Parquet для обновления. Внешние таблицы Hive должны находиться в одном из форматов данных, перечисленных в разделе "Работа с внешними таблицами".

Выполнение подготовительных команд

Миграция таблиц включает ряд подготовительных задач, выполняемых перед запуском рабочего процесса миграции таблицы. Эти задачи выполняются с помощью следующих команд CLI Databricks:

• Команда create-table-mapping , которая создает CSV-файл, который сопоставляет целевой каталог каталога Unity, схему и таблицу с каждой таблицей Hive, которая будет обновлена. Перед продолжением рабочего процесса миграции необходимо просмотреть и обновить файл сопоставления.
• Команда create-uber-principal , которая создает субъект-службу с доступом только для чтения ко всему хранилищу, используемому таблицами в этой рабочей области. Вычислительный ресурс задания рабочего процесса использует этот субъект для обновления таблиц в рабочей области. Отмена подготовки этого субъекта-службы при завершении обновления.
• (Необязательно) Команда principal-prefix-access , которая определяет учетные записи хранения и учетные данные доступа к хранилищу, используемые таблицами Hive в рабочей области.
• (Необязательно) Командаmigrate-credentials, которая создает учетные данные хранилища каталога Unity из учетных данных доступа к хранилищу, определяемых.principal-prefix-access
• (Необязательно) Команда migration locations , которая создает внешние расположения каталога Unity из расположений хранилища, определенных рабочим процессом оценки, с помощью учетных данных хранилища, созданных migrate-credentials.
• (Необязательно) Команда create-catalogs-schemas, которая создает каталоги и схемы каталога Unity, в которых будут храниться обновленные таблицы.

Дополнительные сведения, включая дополнительные команды и параметры рабочего процесса миграции таблиц, см. в разделе "Команды миграции таблиц" в UCX readme.

Запуск миграции таблицы

После выполнения подготовительных задач можно запустить рабочий процесс миграции таблиц из созданной UCX записной книжки README или из заданий рабочих > процессов в пользовательском интерфейсе рабочей области.

Выходные данные каждой задачи рабочего процесса хранятся в таблицах Delta в схеме, указанной $inventory_database во время установки. Эти таблицы можно использовать для дальнейшего анализа и принятия решений. Возможно, потребуется несколько раз запустить рабочий процесс миграции таблиц, чтобы убедиться, что все таблицы успешно обновлены.

Полные инструкции по миграции таблиц см. в записной книжке README, созданной UCX, и в рабочем процессе миграции таблиц в UCX readme.

Дополнительные средства

UCX также включает средства отладки и другие служебные программы для успешной миграции. Дополнительные сведения см. в записной книжке README, созданной 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, выполните следующую команду:

databricks labs ucx --help

Чтобы помочь с определенной командой UCX, выполните следующую команду:

databricks labs ucx <command> --help

Чтобы устранить неполадки, выполните приведенные ниже действия.

• Выполните --debug любую команду, чтобы включить журналы отладки.
• Используйте записную книжку отладки, созданную автоматически UCX.

Чтобы отправить запрос на проблему или функцию, отправьте файл проблемы GitHub.

Заметки о выпуске UCX

См. журнал изменений в репозитории GitHub UCX.