Använd UCX-verktygen för att uppgradera din arbetsyta till Unity Catalog

Den här artikeln introducerar UCX, ett Databricks Labs-projekt som innehåller verktyg som hjälper dig att uppgradera din arbetsyta som inte är Unity-Catalog till Unity Catalog.

Kommentar

UCX, liksom alla projekt i GitHub-kontot för databrickslabs, tillhandahålls endast för din utforskning och stöds inte formellt av Databricks med serviceavtal (SLA). Den tillhandahålls som den är. Vi ger inga garantier av något slag. Skicka inte ett Databricks-supportärende som rör problem som uppstår vid användning av det här projektet. Skapa i stället ett GitHub-problem. Problem kommer att granskas när tiden tillåter, men det finns inga formella serviceavtal för support.

UCX-projektet innehåller följande migreringsverktyg och arbetsflöden:

1. Utvärderingsarbetsflöde som hjälper dig att planera migreringen.
2. Arbetsflöde för gruppmigrering som hjälper dig att uppgradera gruppmedlemskap från din arbetsyta till ditt Databricks-konto och migrera behörigheter till de nya grupperna på kontonivå.
3. Tabellmigrering hjälper dig att uppgradera tabeller som är registrerade i din arbetsytas Hive-metaarkiv till Unity Catalog-metaarkivet. Det här arbetsflödet hjälper dig också att migrera lagringsplatser och de autentiseringsuppgifter som krävs för att komma åt dem.

Det här diagrammet visar det övergripande migreringsflödet och identifierar migreringsarbetsflöden och verktyg efter namn:

Kommentar

Arbetsflödet för kodmigrering som visas i diagrammet är fortfarande under utveckling och är ännu inte tillgängligt.

Innan du börjar

Innan du kan installera UCX och köra UCX-arbetsflöden måste din miljö uppfylla följande krav.

Paket installerade på datorn där du kör UCX:

• Databricks CLI v0.213 eller senare. Se Installera eller uppdatera Databricks CLI.

  Du måste ha en Databricks-konfigurationsfil med konfigurationsprofiler för både arbetsytan och Databricks-kontot.

• Python 3.10 eller senare.

• Om du vill köra UCX-arbetsflödet som identifierar lagringsplatser som används av Hive-tabeller på din arbetsyta (rekommenderas men inte krävs) måste du ha CLI för molnlagringsprovidern (Azure CLI eller AWS CLI) installerat på datorn där du kör UCX-arbetsflöden.

Nätverksåtkomst:

• Nätverksåtkomst från datorn som kör UCX-installationen till den Azure Databricks-arbetsyta som du migrerar.
• Nätverksåtkomst till Internet från datorn som kör UCX-installationen. Detta krävs för åtkomst till pypi.org och github.com.
• Nätverksåtkomst från din Azure Databricks-arbetsyta till pypi.org för att ladda ned paketen databricks-sdk och pyyaml .

Databricks-roller och -behörigheter:

• Administratörsroller för Azure Databricks-konto och arbetsyteadministratör för den användare som kör UCX-installationen. Du kan inte köra installationen som tjänstens huvudnamn.

Andra Krav för Databricks:

• Ett Unity Catalog-metaarkiv som skapats för varje region som är värd för en arbetsyta som du vill uppgradera, med var och en av dessa Azure Databricks-arbetsytor kopplade till ett Unity Catalog-metaarkiv.

  Information om hur du avgör om du redan har ett Unity Catalog-metaarkiv i relevanta arbetsyteregioner, hur du skapar ett metaarkiv om du inte har det och hur du kopplar ett Unity Catalog-metaarkiv till en arbetsyta finns i Steg 1: Bekräfta att din arbetsyta är aktiverad för Unity Catalog i installationsartikeln för Unity Catalog. Alternativt tillhandahåller UCX ett verktyg för att tilldela Unity Catalog-metaarkiv till arbetsytor som du kan använda när UCX har installerats.

  När du kopplar ett Unity Catalog-metaarkiv till en arbetsyta kan du också aktivera identitetsfederation, där du centraliserar användarhantering på Azure Databricks-kontonivå, vilket också är en förutsättning för att använda UCX. Se Aktivera identitetsfederation.

• Om din arbetsyta använder ett externt Hive-metaarkiv (till exempel AWS Glue) i stället för det lokala Hive-standardmetaarkivet för arbetsytan måste du utföra en nödvändig konfiguration. Se Extern Hive-metaarkivintegrering i databrickslabs/ucx-lagringsplatsen.

• Ett Pro- eller Serverlöst SQL-lager som körs på arbetsytan där du kör UCX-arbetsflöden, som krävs för att återge rapporten som genereras av utvärderingsarbetsflödet.

Installera UCX

Om du vill installera UCX använder du Databricks CLI:

databricks labs install ucx

Du uppmanas att välja följande:

1. Databricks-konfigurationsprofilen för den arbetsyta som du vill uppgradera. Konfigurationsfilen måste också innehålla en konfigurationsprofil för arbetsytans överordnade Databricks-konto.

2. Ett namn på inventeringsdatabasen som ska användas för att lagra utdata från migreringsarbetsflödena. Vanligtvis är det bra att välja standardvärdet, som är ucx.

3. Ett SQL-lager som installationsprocessen ska köras på.

4. En lista över arbetsytelokala grupper som du vill migrera till grupper på kontonivå. Om du lämnar detta som standard (<ALL>) behandlas alla befintliga grupper på kontonivå vars namn matchar en arbetsytelokal grupp som ersättning för den arbetsytelokala gruppen och ärver alla dess arbetsytebehörigheter när du kör arbetsflödet för gruppmigrering efter installationen.

   Du har möjlighet att ändra mappningen workspace-group-to-account-group när du har kört installationsprogrammet och innan du kör gruppmigreringen. Se Konfliktlösning för gruppnamn i UCX-lagringsplatsen.

5. Om du har ett externt Hive-metaarkiv, till exempel AWS Glue, kan du ansluta till det eller inte. Se Extern Hive-metaarkivintegrering i databrickslabs/ucx-lagringsplatsen.

6. Om du vill öppna den genererade README-anteckningsboken.

När installationen är klar distribuerar den en README-anteckningsbok, instrumentpaneler, databaser, bibliotek, jobb och andra tillgångar på din arbetsyta.

Mer information finns i installationsanvisningarna i projektläsningen. Du kan också installera UCX på alla arbetsytor i ditt Databricks-konto.

Öppna README-anteckningsboken

Varje installation skapar en README-anteckningsbok som ger en detaljerad beskrivning av alla arbetsflöden och uppgifter, med snabblänkar till arbetsflöden och instrumentpaneler. Se Readme Notebook.

Steg 1. Kör utvärderingsarbetsflödet

Utvärderingsarbetsflödet utvärderar Unity Catalog-kompatibiliteten för gruppidentiteter, lagringsplatser, lagringsuppgifter, åtkomstkontroller och tabeller på den aktuella arbetsytan och tillhandahåller den information som krävs för att planera migreringen till Unity Catalog. Uppgifterna i utvärderingsarbetsflödet kan köras parallellt eller sekventiellt, beroende på angivna beroenden. När utvärderingsarbetsflödet har slutförts fylls en utvärderingsinstrumentpanel med resultat och vanliga rekommendationer.

Utdata för varje arbetsflödesuppgift lagras i Delta-tabeller i det $inventory_database schema som du anger under installationen. Du kan använda dessa tabeller för att utföra ytterligare analys och beslutsfattande med hjälp av en utvärderingsrapport. Du kan köra utvärderingsarbetsflödet flera gånger för att säkerställa att alla inkompatibla entiteter identifieras och redovisas innan du påbörjar migreringsprocessen.

Du kan utlösa utvärderingsarbetsflödet från den UCX-genererade README-anteckningsboken och Azure Databricks UI (Workflows > Jobs > [UCX] Assessment) eller köra följande Databricks CLI-kommando:

databricks labs ucx ensure-assessment-run

Detaljerade instruktioner finns i Arbetsflöde för utvärdering.

Steg 2. Kör arbetsflödet för gruppmigrering

Arbetsflödet för gruppmigrering uppgraderar arbetsytelokala grupper till grupper på kontonivå för att stödja Unity Catalog. Det säkerställer att lämpliga grupper på kontonivå är tillgängliga på arbetsytan och replikerar alla behörigheter. Den tar också bort onödiga grupper och behörigheter från arbetsytan. Uppgifterna i arbetsflödet för gruppmigrering beror på resultatet av utvärderingsarbetsflödet.

Utdata för varje arbetsflödesuppgift lagras i Delta-tabeller i det $inventory_database schema som du anger under installationen. Du kan använda dessa tabeller för att utföra ytterligare analys och beslutsfattande. Du kan köra arbetsflödet för gruppmigrering flera gånger för att säkerställa att alla grupper har uppgraderats och att alla nödvändiga behörigheter har tilldelats.

Information om hur du kör arbetsflödet för gruppmigrering finns i ditt UCX-genererade README-notebook- och gruppmigreringsarbetsflöde i UCX-läsningen.

Steg 3. Kör arbetsflödet för tabellmigrering

Arbetsflödet för tabellmigrering uppgraderar tabeller från Hive-metaarkivet till Unity Catalog-metaarkivet. Externa tabeller i Hive-metaarkivet uppgraderas som externa tabeller i Unity Catalog med hjälp av SYNC. Hanterade tabeller i Hive-metaarkivet som lagras i arbetsytelagringen (kallas även DBFS-rot) uppgraderas som hanterade tabeller i Unity Catalog med DEEP CLONE.

Hive-hanterade tabeller måste vara i Delta- eller Parquet-format för att uppgraderas. Externa Hive-tabeller måste vara i något av de dataformat som anges i Arbeta med externa tabeller.

Kör de förberedande kommandona

Tabellmigrering innehåller ett antal förberedande uppgifter som du kör innan du kör arbetsflödet för tabellmigrering. Du utför dessa uppgifter med hjälp av följande Databricks CLI-kommandon:

• Kommandot create-table-mapping , som skapar en CSV-fil som mappar en Unity Catalog-målkatalog, ett schema och en tabell till varje Hive-tabell som ska uppgraderas. Du bör granska och uppdatera mappningsfilen innan du fortsätter med migreringsarbetsflödet.
• Kommandot create-uber-principal , som skapar ett huvudnamn för tjänsten med skrivskyddad åtkomst till all lagring som används av tabellerna på den här arbetsytan. Beräkningsresursen för arbetsflödesjobbet använder det här huvudkontot för att uppgradera tabellerna på arbetsytan. Avetablera tjänstens huvudnamn när du är klar med uppgraderingen.
• (Valfritt) Kommandot principal-prefix-access som identifierar lagringskonton och autentiseringsuppgifter för lagringsåtkomst som används av Hive-tabellerna på arbetsytan.
• (Valfritt) Kommandot migrate-credentials , som skapar autentiseringsuppgifter för Unity Catalog-lagring från de autentiseringsuppgifter för lagringsåtkomst som identifieras av principal-prefix-access.
• (Valfritt) Kommandot migration locations , som skapar externa Platser i Unity Catalog från lagringsplatserna som identifieras av utvärderingsarbetsflödet, med hjälp av lagringsautentiseringsuppgifterna som skapats av migrate-credentials.
• (Valfritt) Kommandot create-catalogs-schemas, som skapar Unity Catalog-kataloger och scheman som ska innehålla de uppgraderade tabellerna.

Mer information, inklusive ytterligare kommandon och alternativ för arbetsflöden för tabellmigrering finns i Tabellmigreringskommandon i UCX-läsningen.

Kör tabellmigreringen

När du har kört de förberedande uppgifterna kan du köra arbetsflödet för tabellmigrering från den UCX-genererade README-anteckningsboken eller från Arbetsflödesjobb i arbetsytans > användargränssnitt.

Utdata för varje arbetsflödesuppgift lagras i Delta-tabeller i det $inventory_database schema som du anger under installationen. Du kan använda dessa tabeller för att utföra ytterligare analys och beslutsfattande. Du kan behöva köra arbetsflödet för tabellmigrering flera gånger för att säkerställa att alla tabeller har uppgraderats.

Fullständiga instruktioner för tabellmigrering finns i din UCX-genererade README-anteckningsbok och arbetsflödet för tabellmigrering i UCX-läsningen.

Fler verktyg

UCX innehåller även felsökningsverktyg och andra verktyg som hjälper dig att lyckas med migreringen. Mer information finns i den UCX-genererade README-anteckningsboken och UCX-projektläsningen.

Uppgradera UCX-installationen

UCX-projektet uppdateras regelbundet. Så här uppgraderar du UCX-installationen till den senaste versionen:

1. Kontrollera att UCX är installerat.

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

2. Kör uppgraderingen:

   databricks labs upgrade ucx
   

Få hjälp

Om du vill ha hjälp med UCX CLI kör du:

databricks labs ucx --help

Om du vill ha hjälp med ett specifikt UCX-kommando kör du:

databricks labs ucx <command> --help

Så här felsöker du problem:

• Kör --debug med valfritt kommando för att aktivera felsökningsloggar.
• Använd den felsökningsanteckningsbok som genereras automatiskt av UCX.

Om du vill skicka ett problem eller en funktionsbegäran kan du skicka ett GitHub-problem.

Viktig information om UCX

Se ändringsloggen i UCX GitHub-lagringsplatsen.