Użyj narzędzi UCX, aby uaktualnić przestrzeń roboczą do Unity Catalog

W tym artykule przedstawiono UCX, projekt Databricks Labs, który udostępnia narzędzia pomagające uaktualnić obszar roboczy niekorzystający z Unity Catalog do Unity Catalog.

Projekt UCX udostępnia następujące narzędzia i procesy migracji:

1. Przepływ pracy oceny pomaga zaplanować migrację.
2. Proces migracji grup, który pomaga przenieść członkostwo w grupach z obszaru roboczego na konto Databricks oraz przenieść uprawnienia do nowych grup na poziomie konta.
3. Przepływ pracy migracji tabel ułatwia uaktualnianie tabel zarejestrowanych w magazynie metadanych Hive obszaru roboczego do magazynu metadanych Unity Catalog. Ten przepływ pracy pomaga również migrować lokalizacje magazynu i poświadczenia wymagane do uzyskania do nich dostępu.

Ten diagram przedstawia ogólny proces migracji, wymieniając z nazwy przepływy pracy związane z migracją i narzędzia:

Aby zobaczyć demonstrację uaktualniania obszaru roboczego przy użyciu UCX, zapoznaj się z dokumentem Uaktualnianie schematu przy użyciu UCX.

Zanim rozpoczniesz

Przed zainstalowaniem interfejsu UCX i uruchomieniem przepływów pracy UCX środowisko musi spełniać następujące wymagania.

Pakiety zainstalowane na komputerze, na którym jest uruchamiany program UCX:

• Databricks CLI w wersji 0.213 lub nowszej. Zobacz Instalowanie lub aktualizowanie interfejsu wiersza poleceń Databricks.

  Musisz mieć plik konfiguracji usługi Databricks z profilami konfiguracji zarówno dla obszaru roboczego, jak i konta usługi Databricks.

• Środowisko Python w wersji 3.10 lub nowszej.

• Jeśli chcesz uruchomić przepływ pracy UCX, który identyfikuje lokalizacje magazynu używane przez tabele programu Hive w obszarze roboczym (zalecane, ale nie jest to wymagane), musisz mieć interfejs wiersza polecenia dla dostawcy magazynu w chmurze (interfejs wiersza polecenia platformy Azure lub interfejs wiersza polecenia platformy AWS) zainstalowany na komputerze, na którym są uruchamiane przepływy pracy UCX.

Dostęp sieciowy:

• Dostęp sieciowy z komputera, na którym uruchamiana jest instalacja UCX, do obszaru roboczego usługi Azure Databricks, który jest migrowany.
• Dostęp sieciowy do Internetu z komputera z instalacją UCX. Jest to wymagane w celu uzyskania dostępu do pypi.org i github.com.
• Dostęp sieciowy z obszaru roboczego Azure Databricks do pypi.org w celu pobrania pakietów databricks-sdk i pyyaml.

Role i uprawnienia usługi Databricks:

• Role administratora konta i administratora obszaru roboczego usługi Azure Databricks dla użytkownika, który uruchamia instalację UCX. Nie można uruchomić instalacji jako jednostki usługi.

Inne wymagania wstępne dotyczące Databricks:

• Magazyn metadanych Unity Catalog utworzony dla każdego regionu, w którym znajduje się obszar roboczy przeznaczony do uaktualnienia, przy czym każdy z tych obszarów roboczych usługi Azure Databricks jest przypisany do magazynu metadanych Unity Catalog.

  Aby dowiedzieć się, czy masz już magazyn Unity Catalog w odpowiednich regionach obszaru roboczego, jak utworzyć magazyn, jeśli go nie masz, oraz jak przypiąć magazyn Unity Catalog do obszaru roboczego, zobacz Krok 1: Potwierdź włączenie obszaru roboczego dla Unity Catalog w artykule o konfiguracji Unity Catalog. Alternatywnie UCX udostępnia narzędzie do przypisywania metastore’ów Unity Catalog do obszarów roboczych, którego można użyć po zainstalowaniu UCX.

  Dołączenie metastore usługi Unity Catalog do obszaru roboczego umożliwia również federację tożsamości, w ramach której centralizuje się zarządzanie użytkownikami na poziomie konta Azure Databricks, co jest również warunkiem wstępnym korzystania z UCX. Zobacz Włącz federację tożsamości.

• Jeśli obszar roboczy używa zewnętrznego magazynu metadanych Hive (takiego jak AWS Glue) zamiast domyślnego magazynu metadanych Hive w obszarze roboczym lokalnym, należy wykonać pewne wymagania wstępne. Zobacz Integracja zewnętrznego magazynu metadanych Hive w dokumentacji UCX.

• Usługa SQL Warehouse pro lub bezserwerowa uruchomiona w obszarze roboczym, w którym są uruchamiane przepływy pracy UCX, wymagane do renderowania raportu wygenerowanego przez przepływ pracy oceny.

Zainstaluj UCX

Aby zainstalować UCX, użyj interfejsu wiersza polecenia Databricks:

databricks labs install ucx

Zostanie wyświetlony monit o wybranie następujących elementów:

1. Profil konfiguracji usługi Databricks dla obszaru roboczego, który chcesz uaktualnić. Plik konfiguracji musi również zawierać profil konfiguracji dla nadrzędnego konta Databricks skojarzonego z obszarem roboczym.

2. Nazwa bazy danych spisu, która będzie używana do przechowywania danych wyjściowych przepływów pracy migracji. Zazwyczaj warto wybrać wartość domyślną, czyli ucx.

3. Magazyn danych SQL, na potrzeby uruchomienia procesu instalacji.

4. Lista lokalnych grup przestrzeni roboczej, które chcesz zmigrować do grup na poziomie konta. Jeśli pozostawisz to w ustawieniu domyślnym (<ALL>), dowolna istniejąca grupa na poziomie konta, której nazwa jest taka sama jak nazwa lokalnej grupy obszaru roboczego, będzie traktowana jako zamiennik tej lokalnej grupy obszaru roboczego i odziedziczy wszystkie jej uprawnienia obszaru roboczego po uruchomieniu przepływu pracy migracji grup po zakończeniu instalacji.

   Masz możliwość zmodyfikowania mapowania grupy obszaru roboczego na grupę konta po uruchomieniu instalatora i przed uruchomieniem migracji grup. Zobacz Rozwiązywanie konfliktów nazw grup w repozytorium UCX.

5. Jeśli masz zewnętrzny magazyn metadanych Hive, taki jak AWS Glue, możesz połączyć się z nim lub nie. Zobacz Integrację zewnętrznego magazynu metadanych Hive w repozytorium databrickslabs/ucx.

6. Czy otworzyć wygenerowany notatnik README.

Po zakończeniu instalacji wdraża notes README, pulpity nawigacyjne, bazy danych, biblioteki, zadania i inne zasoby w obszarze roboczym.

Aby uzyskać więcej informacji, zobacz instrukcje instalacji w pliku readme projektu. Możesz również zainstalować UCX we wszystkich obszarach roboczych na swoim koncie Databricks.

Otwieranie notesu README

Każda instalacja tworzy notes README, który zawiera szczegółowy opis wszystkich przepływów pracy i zadań, z szybkimi linkami do przepływów pracy i pulpitów nawigacyjnych. Zobacz notatnik Readme.

Krok 1. Uruchom przepływ pracy oceny

Przepływ pracy oceny sprawdza zgodność tożsamości grup, lokalizacji magazynowania, poświadczeń magazynowania, mechanizmów kontroli dostępu i tabel w bieżącym obszarze roboczym z Unity Catalog oraz udostępnia informacje niezbędne do zaplanowania migracji do Unity Catalog. Zadania w przepływie pracy oceny można wykonywać równolegle lub sekwencyjnie w zależności od określonych zależności. Po zakończeniu procesu oceny panel oceny zostanie uzupełniony o ustalenia i typowe zalecenia.

Dane wyjściowe każdego zadania przepływu pracy są przechowywane w tabelach delty w $inventory_database schemacie określonym podczas instalacji. Te tabele umożliwiają przeprowadzenie dalszej analizy i podejmowania decyzji przy użyciu raportu oceny. Przepływ pracy oceny można uruchomić wielokrotnie, aby upewnić się, że wszystkie niezgodne elementy zostaną zidentyfikowane i uwzględnione przed rozpoczęciem procesu migracji.

Przepływ pracy oceny można uruchomić z notesu README wygenerowanego przez UCX oraz z interfejsu użytkownika usługi Azure Databricks (Workflows > Jobs > [UCX] Assessment) albo uruchomić następujące polecenie Databricks CLI:

databricks labs ucx ensure-assessment-run

Aby uzyskać szczegółowe instrukcje, zobacz Przepływ pracy oceny.

Krok 2. Uruchom przepływ pracy migracji grup

Proces migracji grup aktualizuje grupy lokalne dla obszaru roboczego do grup na poziomie konta, aby obsługiwać Unity Catalog. Gwarantuje to, że odpowiednie grupy na poziomie konta są dostępne w obszarze roboczym i replikują wszystkie uprawnienia. Usuwa również wszystkie niepotrzebne grupy i uprawnienia z obszaru roboczego. Zadania w przepływie pracy migracji grup zależą od wyniku przepływu pracy oceny.

Dane wyjściowe każdego zadania przepływu pracy są przechowywane w tabelach delty w $inventory_database schemacie określonym podczas instalacji. Te tabele umożliwiają przeprowadzenie dalszej analizy i podejmowania decyzji. Przepływ pracy migracji grup można uruchamiać wielokrotnie, aby upewnić się, że wszystkie grupy zostały pomyślnie zaktualizowane oraz że przypisano wszystkie niezbędne uprawnienia.

Aby uzyskać informacje o uruchamianiu przepływu pracy migracji grup, zobacz notatnik README wygenerowany przez UCX oraz Przepływ pracy migracji grup w pliku README narzędzia UCX.

Krok 3. Uruchom przepływ migracji tabeli

Przepływ migracji tabel aktualizuje tabele z magazynu metadanych Hive do magazynu metadanych Unity Catalog. Tabele zewnętrzne w metastore Hive są uaktualniane jako tabele zewnętrzne w katalogu Unity przy użyciu SYNC. Zarządzane tabele w magazynie metadanych Hive, przechowywane w magazynie obszaru roboczego (nazywanym również korzeniem DBFS), są migrowane do Unity Catalog jako tabele zarządzane przy użyciu DEEP CLONE.

Tabele zarządzane w Hive muszą być w formacie Delta lub Parquet, aby można było je uaktualnić. Zewnętrzne tabele programu Hive muszą być w jednym z formatów danych wymienionych w temacie Praca z tabelami zewnętrznymi.

Uruchamianie poleceń przygotowawczych

Migracja tabel obejmuje szereg zadań przygotowawczych, które wykonuje się przed uruchomieniem procesu migracji tabel. Te zadania są wykonywane przy użyciu następujących poleceń interfejsu wiersza polecenia usługi Databricks:

• Polecenie create-table-mapping, które tworzy plik CSV, który przypisuje docelowy katalog, schemat i tabelę w Unity Catalog do każdej tabeli Hive, która zostanie uaktualniona. Przed kontynuowaniem procesu migracji należy przejrzeć i zaktualizować plik mapowania.
• Polecenie create-uber-principal, które tworzy jednostkę usługi z dostępem tylko do odczytu do wszystkich zasobów magazynu używanych przez tabele w tym obszarze roboczym. Zasób obliczeniowy zadania przepływu pracy używa tej tożsamości do aktualizowania tabel w obszarze roboczym. Cofnij aprowizację tej nazwy głównej usługi po zakończeniu uaktualnienia.
• (Opcjonalnie) Polecenie principal-prefix-access , które identyfikuje konta magazynu i poświadczenia dostępu do magazynu używane przez tabele programu Hive w obszarze roboczym.
• (Opcjonalnie) Polecenie migrate-credentials, które tworzy poświadczenia magazynu Unity Catalog na podstawie poświadczeń dostępu do magazynu określonych za pomocą polecenia principal-prefix-access.
• (Opcjonalnie) Polecenie migration locations, które tworzy lokalizacje zewnętrzne Unity Catalog na podstawie lokalizacji pamięci masowej zidentyfikowanych przez przepływ oceny, przy użyciu poświadczeń pamięci masowej utworzonych przez migrate-credentials.
• (Opcjonalnie) Polecenie create-catalogs-schemas, które tworzy katalogi i schematy Unity Catalog, w których będą przechowywane zaktualizowane tabele.

Aby uzyskać szczegółowe informacje, w tym dodatkowe polecenia i opcje przepływu pracy migracji tabel, zobacz Polecenia migracji tabel w pliku readme UCX.

Uruchom migrację tabeli

Po uruchomieniu zadań przygotowawczych możesz uruchomić przepływ pracy migracji tabel z poziomu notesu README wygenerowanego przez interfejs użytkownika UCX lub z obszaru Zadania i potoki w interfejsie użytkownika obszaru roboczego.

Dane wyjściowe każdego zadania przepływu pracy są przechowywane w tabelach delty w $inventory_database schemacie określonym podczas instalacji. Te tabele umożliwiają przeprowadzenie dalszej analizy i podejmowania decyzji. Może być konieczne wielokrotne uruchomienie przepływu pracy migracji tabel, aby upewnić się, że wszystkie tabele zostały pomyślnie uaktualnione.

Aby uzyskać pełne instrukcje dotyczące migracji tabel, zobacz notes README wygenerowany przez UCX i przepływy pracy migracji tabel w pliku readme UCX.

Dodatkowe narzędzia

UCX obejmuje również:

• Narzędzia umożliwiające federację magazynu Hive metastore , narzędzie integracji usługi Azure Databricks, które umożliwia Unity Catalog zarządzanie tabelami, które są zarejestrowane w magazynie metadanych Hive:

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

  Federacja magazynu metadanych Hive pomaga w migracji, umożliwiając jednoczesne uruchamianie obciążeń zarówno w starszym magazynie metadanych Hive, jak i jego replikacie w katalogu Unity, ułatwiając przejście do katalogu Unity. Aby uzyskać więcej informacji na temat używania federacji magazynu metadanych Hive w scenariuszu migracji, zobacz Jak używać federacji magazynu metadanych Hive w trakcie migracji do Unity Catalog?.

• Narzędzia do debugowania i inne narzędzia ułatwiające pomyślne rozwiązanie migracji.

Aby uzyskać więcej informacji, zobacz notes README wygenerowany przez UCX i dokumentację projektu UCX.

Uaktualnianie instalacji UCX

Projekt UCX jest regularnie aktualizowany. Aby uaktualnić instalację UCX do najnowszej wersji:

1. Sprawdź, czy UCX jest zainstalowany.

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

2. Uruchom uaktualnienie:

   databricks labs upgrade ucx
   

Uzyskaj pomoc

Aby uzyskać pomoc dotyczącą interfejsu CLI UCX, uruchom:

databricks labs ucx --help

Aby uzyskać pomoc dotyczącą określonego polecenia UCX, uruchom polecenie:

databricks labs ucx <command> --help

Aby rozwiązać problemy:

• Uruchom --debug z dowolnym poleceniem, aby włączyć logi debugowania.
• Aby uzyskać więcej informacji, zobacz przewodnik rozwiązywania problemów Z programem UCX .

Aby zgłosić problem lub żądanie funkcji, zgłoś problem z usługą GitHub.

Informacje o wersji UCX

Zobacz dziennik zmian w repozytorium GitHub UCX.