Använd UCX-verktygen för att uppgradera din arbetsyta till Unity Catalog
Den här artikeln beskriver UCX, ett Databricks Labs-projekt som innehåller verktyg som hjälper dig att uppgradera din icke-Unity-Catalog arbetsyta 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:
- Utvärderingsarbetsflöde som hjälper dig att planera migreringen.
- 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å.
- arbetsflöde för tabellmigrering som 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
ochpyyaml
.
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å identitetsfederation, där du centraliserar användarhantering på Kontonivå för Azure Databricks, 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:
Databricks-konfigurationsprofilen för den arbetsyta som du vill uppgradera. Konfigurationsfilen måste också innehålla en konfigurationsprofil för arbetsytans överordnade Databricks-konto.
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, vilket är
ucx
.Ett SQL-lager som installationsprocessen ska köras på.
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.
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.
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ödesaktivitet 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ödesaktivitet 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 hjälp av 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 en tjänstehuvudprincip med endast läsbehörighet till all lagring som används av tabellerna på den här arbetsytan. Beräkningsresursen för arbetsflödesjobbet använder denna huvudman för att uppgradera tabellerna i 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 autentiseringsuppgifterna för lagringsåtkomst som identifieras avprincipal-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 avmigrate-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ödet för tabellmigrering, finns i Tabellmigreringskommandon i UCX-readme-filen.
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 Workflows > Jobs i arbetsytans användargränssnitt.
Utdata för varje arbetsflödesaktivitet 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 den UCX-genererade README-filen och tabellmigrationsarbetsflödet i UCX README-filen.
Fler verktyg
UCX omfattar även:
Verktyg för att aktivera Hive-metaarkivfederation, Azure Databricks-integreringsverktyget som gör det möjligt för Unity Catalog att styra tabeller som registrerats i ett Hive-metaarkiv:
enable-hms-federation
create-federated-catalog
Hive-metaarkivfederation underlättar migreringen genom att du kan köra arbetsbelastningar på både ditt äldre Hive-metaarkiv och dess spegling i Unity Catalog, vilket underlättar övergången till Unity Catalog. Mer information om hur du använder Hive-metaarkivfederation i ett migreringsscenario finns i Hur använder du Hive-metaarkivfederation under migreringen till Unity Catalog?.
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:
Kontrollera att UCX är installerat.
databricks labs installed Name Description Version ucx Unity Catalog Migration Toolkit (UCX) 0.20.0
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.