Upgrade pracovního prostoru na katalog Unity pomocí nástrojů UCX

Tento článek představuje UCX, projekt Databricks Labs, který poskytuje nástroje, které vám pomůžou upgradovat pracovní prostor mimo Unity-Catalog na Katalog Unity.

Poznámka:

UCX, stejně jako všechny projekty v účtu Databrickslabs GitHub, je poskytován pouze pro váš průzkum a databricks není formálně podporována smlouvami o úrovni služeb (SLA). Poskytuje se tak, jak je. Neposkytujeme žádné záruky. Neodesílejte lístek podpory Databricks týkající se problémů, které vznikají z použití tohoto projektu. Místo toho zapište problém na GitHubu. Problémy budou zkontrolovány jako časové povolení, ale neexistují žádné formální smlouvy SLA pro podporu.

Projekt UCX poskytuje následující nástroje a pracovní postupy migrace:

1. Pracovní postup posouzení, který vám pomůže naplánovat migraci.
2. Pracovní postup migrace skupin, který vám pomůže upgradovat členství ve skupinách z pracovního prostoru na účet Databricks a migrovat oprávnění do nových skupin na úrovni účtu.
3. Pracovní postup migrace tabulek, který vám pomůže s upgradem tabulek registrovaných v metastoru Hive vašeho pracovního prostoru na metastore katalogu Unity. Tento pracovní postup vám také pomůže migrovat umístění úložiště a přihlašovací údaje potřebné pro přístup k nim.

Tento diagram znázorňuje celkový tok migrace a identifikuje pracovní postupy migrace a nástroje podle názvu:

Poznámka:

Pracovní postup migrace kódu, který je znázorněný v diagramu, zůstává ve vývoji a ještě není k dispozici.

Než začnete

Než budete moct nainstalovat UCX a spustit pracovní postupy UCX, musí vaše prostředí splňovat následující požadavky.

Balíčky nainstalované v počítači, na kterém spouštíte UCX:

• Databricks CLI verze 0.213 nebo novější Viz Instalace nebo aktualizace rozhraní příkazového řádku Databricks.

  Musíte mít konfigurační soubor Databricks s konfiguračními profily pro pracovní prostor i účet Databricks.

• Python 3.10 nebo novější

• Pokud chcete spustit pracovní postup UCX, který identifikuje umístění úložiště používaná tabulkami Hive ve vašem pracovním prostoru (doporučeno, ale nevyžaduje se), musíte mít rozhraní příkazového řádku pro poskytovatele cloudového úložiště (Azure CLI nebo AWS CLI) nainstalované v počítači, na kterém spouštíte pracovní postupy UCX.

Přístup k síti:

• Síťový přístup z počítače, na kterém běží instalace UCX, do pracovního prostoru Azure Databricks, který migrujete.
• Síťový přístup k internetu z počítače, na kterém běží instalace UCX. To se vyžaduje pro přístup k pypi.org a github.com.
• Síťový přístup z pracovního prostoru Azure Databricks k pypi.org ke stažení databricks-sdk a pyyaml balíčků.

Role a oprávnění Databricks:

• Role správce účtu Azure Databricks a správce pracovního prostoru pro uživatele, který spouští instalaci UCX. Instalaci nelze spustit jako instanční objekt.

Další požadavky Databricks:

• Metastor katalogu Unity vytvořený pro každou oblast, která je hostitelem pracovního prostoru, který chcete upgradovat, s každým z těchto pracovních prostorů Azure Databricks připojeným k metastore katalogu Unity.

  Informace o tom, jak zjistit, jestli už máte metastore katalogu Unity v příslušných oblastech pracovního prostoru, jak vytvořit metastor, pokud ne, a jak připojit metastore katalogu Unity k pracovnímu prostoru, najdete v kroku 1: Potvrzení, že je váš pracovní prostor povolený pro katalog Unity v článku o nastavení katalogu Unity. Jako alternativu poskytuje UCX nástroj pro přiřazování metastorů Katalogu Unity pracovním prostorům , které můžete použít po instalaci UCX.

  Připojení metastoru katalogu Unity k pracovnímu prostoru také umožňuje federaci identit, ve které centralizujete správu uživatelů na úrovni účtu Azure Databricks, což je také předpokladem pro použití UCX. Viz Povolení federace identit.

• Pokud váš pracovní prostor používá externí metastor Hive (například AWS Glue) místo výchozího metastoru Hive místního pracovního prostoru, musíte provést některé požadované nastavení. Viz Integrace externího metastoru Hive v úložišti databrickslabs/ucx.

• Pro nebo bezserverový SQL Warehouse spuštěný v pracovním prostoru, ve kterém spouštíte pracovní postupy UCX, které jsou potřeba k vykreslení sestavy vygenerované pracovním postupem posouzení.

Instalace UCX

K instalaci UCX použijte rozhraní příkazového řádku Databricks:

databricks labs install ucx

Zobrazí se výzva k výběru následujících možností:

1. Konfigurační profil Databricks pro pracovní prostor, který chcete upgradovat. Konfigurační soubor musí také obsahovat konfigurační profil pro nadřazený účet Databricks pracovního prostoru.

2. Název databáze inventáře, která se použije k uložení výstupu pracovních postupů migrace. Obvykle je vhodné vybrat výchozí hodnotu, což je ucx.

3. SQL Warehouse pro spuštění procesu instalace.

4. Seznam místních skupin pracovního prostoru, které chcete migrovat na skupiny na úrovni účtu. Pokud tuto možnost ponecháte jako výchozí (<ALL>), všechny existující skupiny na úrovni účtu, jejichž název odpovídá místní skupině pracovního prostoru, se bude považovat za náhradu této místní skupiny pracovního prostoru a při spuštění pracovního postupu migrace skupiny po instalaci zdědí všechna jeho oprávnění k pracovnímu prostoru .

   Po spuštění instalačního programu a před spuštěním migrace skupiny máte možnost upravit mapování skupiny pracovního prostoru na účet. Viz řešení konfliktů názvů skupin v úložišti UCX.

5. Pokud máte externí metastore Hive, například AWS Glue, máte možnost se k němu připojit nebo ne. Viz Integrace externího metastoru Hive v úložišti databrickslabs/ucx.

6. Zda se má otevřít vygenerovaný poznámkový blok README.

Po dokončení instalace se ve vašem pracovním prostoru nasadí poznámkový blok README, řídicí panely, databáze, knihovny, úlohy a další prostředky.

Další informace najdete v pokynech k instalaci v souboru readme projektu. UCX můžete také nainstalovat do všech pracovních prostorů ve vašem účtu Databricks.

Otevření poznámkového bloku README

Každá instalace vytvoří poznámkový blok README, který poskytuje podrobný popis všech pracovních postupů a úkolů s rychlými odkazy na pracovní postupy a řídicí panely. Viz poznámkový blok Readme.

Krok 1. Spuštění pracovního postupu posouzení

Pracovní postup posouzení vyhodnocuje kompatibilitu katalogu Unity s identitami skupin, umístěním úložiště, přihlašovacími údaji úložiště, řízením přístupu a tabulkami v aktuálním pracovním prostoru a poskytuje informace potřebné pro plánování migrace do katalogu Unity. Úkoly v pracovním postupu posouzení lze provádět paralelně nebo postupně v závislosti na zadaných závislostech. Po dokončení pracovního postupu posouzení se řídicí panel posouzení naplní zjištěními a běžnými doporučeními.

Výstup každého úkolu pracovního postupu je uložen v tabulkách Delta ve schématu $inventory_database , které zadáte během instalace. Tyto tabulky můžete použít k další analýze a rozhodování pomocí sestavy posouzení. Pracovní postup posouzení můžete spustit několikrát, abyste před zahájením procesu migrace zajistili, že jsou identifikovány a zohledněny všechny nekompatibilní entity.

Pracovní postup posouzení můžete aktivovat z poznámkového bloku README generovaného UCX a uživatelského rozhraní Azure Databricks (úlohy > pracovních postupů > [UCX] Assessment) nebo spustit následující příkaz Rozhraní příkazového řádku Databricks:

databricks labs ucx ensure-assessment-run

Podrobné pokyny najdete v části Pracovní postup posouzení.

Krok 2. Spuštění pracovního postupu migrace skupiny

Pracovní postup migrace skupiny upgraduje místní skupiny pracovního prostoru na skupiny na úrovni účtu, aby podporovaly katalog Unity. Zajišťuje, aby byly v pracovním prostoru k dispozici příslušné skupiny na úrovni účtu a replikují se všechna oprávnění. Odebere také všechny nepotřebné skupiny a oprávnění z pracovního prostoru. Úlohy v pracovním postupu migrace skupiny závisí na výstupu pracovního postupu posouzení.

Výstup každého úkolu pracovního postupu je uložen v tabulkách Delta ve schématu $inventory_database , které zadáte během instalace. Tyto tabulky můžete použít k další analýze a rozhodování. Pracovní postup migrace skupiny můžete spustit několikrát, abyste zajistili, že všechny skupiny budou úspěšně upgradovány a že jsou přiřazena všechna potřebná oprávnění.

Informace o spuštění pracovního postupu migrace skupiny najdete v souboru README vygenerovaného poznámkového bloku README a pracovního postupu migrace skupin v souboru README v UCX.

Krok 3. Spuštění pracovního postupu migrace tabulek

Pracovní postup migrace tabulek upgraduje tabulky z metastoru Hive na metastore katalogu Unity. Externí tabulky v metastoru Hive se upgradují jako externí tabulky v katalogu Unity pomocí synchronizace. Spravované tabulky v metastoru Hive uložené v úložišti pracovních prostorů (označované také jako kořen DBFS) se upgradují jako spravované tabulky v katalogu Unity pomocí DEEP CLONE.

Spravované tabulky Hive musí být upgradované ve formátu Delta nebo Parquet. Externí tabulky Hive musí být v jednom z datových formátů uvedených v části Práce s externími tabulkami.

Spuštění přípravných příkazů

Migrace tabulek zahrnuje řadu přípravných úloh, které spustíte před spuštěním pracovního postupu migrace tabulek. Tyto úlohy provedete pomocí následujících příkazů rozhraní příkazového řádku Databricks:

• Příkaz create-table-mapping , který vytvoří soubor CSV, který mapuje cílový katalog, schéma a tabulku Unity na každou tabulku Hive, která se upgraduje. Než budete pokračovat v pracovním postupu migrace, měli byste zkontrolovat a aktualizovat soubor mapování.
• Příkaz create-uber-principal , který vytvoří instanční objekt s přístupem jen pro čtení ke všem úložištím používaným tabulkami v tomto pracovním prostoru. Výpočetní prostředek úlohy pracovního postupu používá tento objekt zabezpečení k upgradu tabulek v pracovním prostoru. Po dokončení upgradu tento instanční objekt zrušte.
• (Volitelné) Příkaz principal-prefix-access , který identifikuje účty úložiště a přihlašovací údaje pro přístup k úložišti používané tabulkami Hive v pracovním prostoru.
• (Volitelné) Příkazmigrate-credentials, který vytvoří přihlašovací údaje k úložišti Unity Catalog z přihlašovacích údajů pro přístup k úložišti identifikovaných .principal-prefix-access
• (Volitelné) Příkazmigration locations, který vytvoří externí umístění katalogu Unity z umístění úložiště identifikovaných pracovním postupem posouzení pomocí přihlašovacích údajů úložiště vytvořených .migrate-credentials
• (Volitelné) Příkaz create-catalogs-schemas, který vytvoří katalogy a schémata Unity, které budou obsahovat upgradované tabulky.

Podrobnosti, včetně dalších příkazů a možností pracovního postupu migrace tabulek, najdete v tématu Příkazy pro migraci tabulek v souboru READme UCX.

Spuštění migrace tabulek

Jakmile spustíte přípravné úlohy, můžete pracovní postup migrace tabulky spustit z poznámkového bloku README generovaného ucX nebo úloh pracovních postupů > v uživatelském rozhraní pracovního prostoru.

Výstup každého úkolu pracovního postupu je uložen v tabulkách Delta ve schématu $inventory_database , které zadáte během instalace. Tyto tabulky můžete použít k další analýze a rozhodování. Možná budete muset pracovní postup migrace tabulek spustit několikrát, abyste zajistili, že se všechny tabulky úspěšně upgradují.

Kompletní pokyny k migraci tabulek najdete v poznámkovém bloku README generovaném ucX a pracovním postupu migrace tabulek v souboru readme UCX.

Další nástroje

UCX také zahrnuje:

• Nástroje pro povolení federace metastoru Hive , integrační nástroj Azure Databricks, který umožňuje službě Unity Catalog řídit tabulky zaregistrované v metastoru Hive:

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

  Federace metastoru Hive pomáhá při migraci tím, že umožňuje spouštět úlohy na starším metastoru Hive i na jeho zrcadle v katalogu Unity a zmírnit přechod do katalogu Unity. Další informace o používání federace metastoru Hive ve scénáři migrace najdete v tématu Jak během migrace do katalogu Unity používáte federaci metastoru Hive?.

• Nástroje pro ladění a další nástroje, které vám pomůžou s migrací uspět.

Další informace najdete v poznámkovém bloku README generovaném ucX a souboru readme projektu UCX.

Upgrade instalace UCX

Projekt UCX se pravidelně aktualizuje. Upgrade instalace UCX na nejnovější verzi:

1. Ověřte, že je nainstalovaný UCX.

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

2. Spusťte upgrade:

   databricks labs upgrade ucx
   

Získání pomoci

Nápovědu k rozhraní příkazového řádku UCX můžou získat spuštěním následujícího příkazu:

databricks labs ucx --help

Nápovědu ke konkrétnímu příkazu UCX zobrazíte spuštěním následujícího příkazu:

databricks labs ucx <command> --help

Řešení potíží:

• Spuštěním --debug libovolného příkazu povolte protokoly ladění.
• Použijte ladicí poznámkový blok, který je automaticky generován UCX.

Pokud chcete podat žádost o problém nebo funkci, vytvořte problém GitHubu.

Poznámky k verzi UCX

Podívejte se na protokol změn v úložišti UCX Na GitHubu.