Usare le utilità UCX per aggiornare l'area di lavoro a Unity Catalog

Questo articolo presenta UCX, un progetto di Databricks Labs che fornisce strumenti che consentono di aggiornare l'area di lavoro non Unity-Catalog a Unity Catalog.

Nota

UCX, come tutti i progetti nell'account GitHub databrickslabs, viene fornito solo per l'esplorazione e non è formalmente supportato da Databricks con contratti di servizio (SLA). Viene fornito così come è. Non facciamo alcuna garanzia di alcun genere. Non inviare un ticket di supporto di Databricks relativo ai problemi che derivano dall'uso di questo progetto. Segnalare invece un problema di GitHub. I problemi verranno esaminati come permessi di tempo, ma non sono previsti contratti di servizio formali per il supporto.

Il progetto UCX fornisce i flussi di lavoro e gli strumenti di migrazione seguenti:

1. Flusso di lavoro di valutazione per pianificare la migrazione.
2. Flusso di lavoro di migrazione del gruppo per aggiornare l'appartenenza ai gruppi dall'area di lavoro all'account Databricks ed eseguire la migrazione delle autorizzazioni ai nuovi gruppi a livello di account.
3. Migrazione delle tabelle worfklow per aggiornare le tabelle registrate nel metastore Hive dell'area di lavoro al metastore del catalogo Unity. Questo flusso di lavoro consente anche di eseguire la migrazione dei percorsi di archiviazione e delle credenziali necessarie per accedervi.

Questo diagramma mostra il flusso di migrazione complessivo, identificando i flussi di lavoro di migrazione e le utilità in base al nome:

Nota

Il flusso di lavoro di migrazione del codice illustrato nel diagramma rimane in fase di sviluppo e non è ancora disponibile.

Operazioni preliminari

Prima di poter installare UCX ed eseguire i flussi di lavoro UCX, l'ambiente deve soddisfare i requisiti seguenti.

Pacchetti installati nel computer in cui si esegue UCX:

• Interfaccia della riga di comando di Databricks v0.213 o versione successiva. Vedere Installare o aggiornare l'interfaccia della riga di comando di Databricks.

  È necessario disporre di un file di configurazione di Databricks con profili di configurazione sia per l'area di lavoro che per l'account Databricks.

• Python 3.10 o versione successiva.

• Se si vuole eseguire il flusso di lavoro UCX che identifica i percorsi di archiviazione usati dalle tabelle Hive nell'area di lavoro (scelta consigliata, ma non obbligatoria), è necessario disporre dell'interfaccia della riga di comando per il provider di archiviazione cloud (interfaccia della riga di comando di Azure o dell'interfaccia della riga di comando di AWS) installato nel computer in cui si eseguono i flussi di lavoro UCX.

Accesso alla rete:

• Accesso di rete dal computer che esegue l'installazione UCX all'area di lavoro di Azure Databricks di cui si sta eseguendo la migrazione.
• Accesso di rete a Internet dal computer che esegue l'installazione UCX. Questa operazione è necessaria per l'accesso a pypi.org e github.com.
• Accesso di rete dall'area di lavoro di Azure Databricks per pypi.org per scaricare i databricks-sdk pacchetti e pyyaml .

Ruoli e autorizzazioni di Databricks:

• Ruoli di amministratore dell'account e dell'area di lavoro di Azure Databricks per l'utente che esegue l'installazione ucx. Non è possibile eseguire l'installazione come entità servizio.

Altri prerequisiti di Databricks:

• Metastore del catalogo Unity creato per ogni area che ospita un'area di lavoro da aggiornare, con ognuna di queste aree di lavoro di Azure Databricks collegate a un metastore del catalogo Unity.

  Per informazioni su come determinare se è già disponibile un metastore del catalogo Unity nelle aree di lavoro pertinenti, come creare un metastore in caso contrario e come collegare un metastore del catalogo Unity a un'area di lavoro, vedere Passaggio 1: Verificare che l'area di lavoro sia abilitata per il catalogo Unity nell'articolo sulla configurazione del catalogo Unity. In alternativa, UCX offre un'utilità per l'assegnazione di metastore del catalogo Unity alle aree di lavoro che è possibile usare dopo l'installazione di UCX.

  Il collegamento di un metastore del catalogo Unity a un'area di lavoro consente anche la federazione delle identità, in cui si centralizza la gestione degli utenti a livello di account Azure Databricks, che è anche un prerequisito per l'uso di UCX. Vedere Abilitare la federazione delle identità.

• Se l'area di lavoro usa un metastore Hive esterno ,ad esempio AWS Glue, anziché il metastore Hive locale dell'area di lavoro predefinito, è necessario eseguire una configurazione dei prerequisiti. Vedere Integrazione metastore Hive esterna nel repository databrickslabs/ucx.

• Un data warehouse SQL Pro o Serverless in esecuzione nell'area di lavoro in cui si eseguono flussi di lavoro UCX, necessari per eseguire il rendering del report generato dal flusso di lavoro di valutazione.

Installare UCX

Per installare UCX, usare l'interfaccia della riga di comando di Databricks:

databricks labs install ucx

Viene richiesto di selezionare quanto segue:

1. Profilo di configurazione di Databricks per l'area di lavoro da aggiornare. Il file di configurazione deve includere anche un profilo di configurazione per l'account Databricks padre dell'area di lavoro.

2. Nome del database di inventario che verrà usato per archiviare l'output dei flussi di lavoro di migrazione. In genere è consigliabile selezionare l'impostazione predefinita, ovvero ucx.

3. Un'istanza di SQL Warehouse in cui eseguire il processo di installazione.

4. Elenco di gruppi locali dell'area di lavoro di cui si vuole eseguire la migrazione ai gruppi a livello di account. Se si lascia questa opzione come predefinita (<ALL>), qualsiasi gruppo a livello di account esistente il cui nome corrisponde a un gruppo locale dell'area di lavoro verrà considerato come la sostituzione del gruppo locale dell'area di lavoro e erediterà tutte le autorizzazioni dell'area di lavoro quando si esegue il flusso di lavoro di migrazione del gruppo dopo l'installazione.

   È possibile modificare il mapping tra gruppi di aree di lavoro dopo aver eseguito il programma di installazione e prima di eseguire la migrazione dei gruppi. Vedere Group Name Conflict Resolution (Risoluzione dei conflitti nome gruppo) nel repository UCX.

5. Se si dispone di un metastore Hive esterno, ad esempio AWS Glue, è possibile connettersi o meno. Vedere Integrazione metastore Hive esterna nel repository databrickslabs/ucx.

6. Indica se aprire il notebook README generato.

Al termine dell'installazione, distribuisce un notebook README, dashboard, database, librerie, processi e altri asset nell'area di lavoro.

Per altre informazioni, vedere le istruzioni di installazione nel file leggimi del progetto. È anche possibile installare UCX in tutte le aree di lavoro nell'account Databricks.

Aprire il notebook README

Ogni installazione crea un notebook README che fornisce una descrizione dettagliata di tutti i flussi di lavoro e attività, con collegamenti rapidi ai flussi di lavoro e ai dashboard. Vedere Notebook Leggimi.

Passaggio 1. Eseguire il flusso di lavoro di valutazione

Il flusso di lavoro di valutazione valuta la compatibilità del catalogo Unity delle identità dei gruppi, delle posizioni di archiviazione, delle credenziali di archiviazione, dei controlli di accesso e delle tabelle nell'area di lavoro corrente e fornisce le informazioni necessarie per pianificare la migrazione a Unity Catalog. Le attività nel flusso di lavoro di valutazione possono essere eseguite in parallelo o sequenziale, a seconda delle dipendenze specificate. Al termine del flusso di lavoro di valutazione, un dashboard di valutazione viene popolato con i risultati e le raccomandazioni comuni.

L'output di ogni attività del flusso di lavoro viene archiviato nelle tabelle Delta nello $inventory_database schema specificato durante l'installazione. È possibile usare queste tabelle per eseguire ulteriori analisi e processi decisionali usando un report di valutazione. È possibile eseguire il flusso di lavoro di valutazione più volte per assicurarsi che tutte le entità incompatibili vengano identificate e gestite prima di avviare il processo di migrazione.

È possibile attivare il flusso di lavoro di valutazione dal notebook README generato da UCX e dall'interfaccia utente di Azure Databricks (Processi > di lavoro > [UCX] Assessment) oppure eseguire il comando dell'interfaccia della riga di comando di Databricks seguente:

databricks labs ucx ensure-assessment-run

Per istruzioni dettagliate, vedere Flusso di lavoro di valutazione.

Passaggio 2. Eseguire il flusso di lavoro di migrazione del gruppo

Il flusso di lavoro di migrazione del gruppo aggiorna i gruppi locali dell'area di lavoro ai gruppi a livello di account per supportare Il catalogo unity. Garantisce che i gruppi a livello di account appropriati siano disponibili nell'area di lavoro e replicano tutte le autorizzazioni. Rimuove anche tutti i gruppi e le autorizzazioni non necessari dall'area di lavoro. Le attività nel flusso di lavoro di migrazione del gruppo dipendono dall'output del flusso di lavoro di valutazione.

L'output di ogni attività del flusso di lavoro viene archiviato nelle tabelle Delta nello $inventory_database schema specificato durante l'installazione. È possibile usare queste tabelle per eseguire ulteriori analisi e processi decisionali. È possibile eseguire il flusso di lavoro di migrazione del gruppo più volte per assicurarsi che tutti i gruppi vengano aggiornati correttamente e che siano assegnate tutte le autorizzazioni necessarie.

Per informazioni sull'esecuzione del flusso di lavoro di migrazione del gruppo, vedere il notebook README generato da UCX e il flusso di lavoro di migrazione del gruppo nel file leggimi UCX.

Passaggio 3. Eseguire il flusso di lavoro di migrazione della tabella

Il flusso di lavoro di migrazione delle tabelle aggiorna le tabelle dal metastore Hive al metastore di Unity Catalog. Le tabelle esterne nel metastore Hive vengono aggiornate come tabelle esterne nel catalogo unity tramite SYNC. Le tabelle gestite nel metastore Hive archiviate nell'archiviazione dell'area di lavoro (nota anche come radice DBFS) vengono aggiornate come tabelle gestite nel catalogo Unity, usando D edizione Enterprise P CLONE.

Le tabelle gestite hive devono essere in formato Delta o Parquet da aggiornare. Le tabelle Hive esterne devono trovarsi in uno dei formati di dati elencati in Tabelle esterne.

Eseguire i comandi preliminari

La migrazione delle tabelle include una serie di attività preliminari eseguite prima di eseguire il flusso di lavoro di migrazione delle tabelle. Queste attività vengono eseguite usando i comandi dell'interfaccia della riga di comando di Databricks seguenti:

• Il create-table-mapping comando , che crea un file CSV che esegue il mapping di un catalogo, uno schema e una tabella Unity di destinazione a ogni tabella Hive che verrà aggiornata. È necessario esaminare e aggiornare il file di mapping prima di procedere con il flusso di lavoro di migrazione.
• Il create-uber-principal comando , che crea un'entità servizio con accesso in sola lettura a tutte le risorse di archiviazione usate dalle tabelle in questa area di lavoro. La risorsa di calcolo del processo del flusso di lavoro usa questa entità per aggiornare le tabelle nell'area di lavoro. Effettuare il deprovisioning di questa entità servizio al termine dell'aggiornamento.
• (Facoltativo) Il principal-prefix-access comando , che identifica gli account di archiviazione e le credenziali di accesso alle risorse di archiviazione usate dalle tabelle Hive nell'area di lavoro.
• (Facoltativo) Il migrate-credentials comando , che crea le credenziali di archiviazione del catalogo Unity dalle credenziali di accesso alle risorse di archiviazione identificate da principal-prefix-access.
• (Facoltativo) Il migration locations comando , che crea percorsi esterni del catalogo Unity dalle posizioni di archiviazione identificate dal flusso di lavoro di valutazione, usando le credenziali di archiviazione create da migrate-credentials.
• (Facoltativo) Il create-catalogs-schemascomando , che crea cataloghi e schemi del catalogo Unity che conterranno le tabelle aggiornate.

Per informazioni dettagliate, inclusi i comandi aggiuntivi del flusso di lavoro di migrazione delle tabelle e le opzioni, vedere Comandi di migrazione delle tabelle nel file leggimi UCX.

Eseguire la migrazione della tabella

Dopo aver eseguito le attività preliminari, è possibile eseguire il flusso di lavoro di migrazione della tabella dal notebook README generato da UCX o dai processi flussi di lavoro > nell'interfaccia utente dell'area di lavoro.

L'output di ogni attività del flusso di lavoro viene archiviato nelle tabelle Delta nello $inventory_database schema specificato durante l'installazione. È possibile usare queste tabelle per eseguire ulteriori analisi e processi decisionali. Potrebbe essere necessario eseguire il flusso di lavoro di migrazione della tabella più volte per assicurarsi che tutte le tabelle vengano aggiornate correttamente.

Per istruzioni complete sulla migrazione delle tabelle, vedere il notebook README generato da UCX e il flusso di lavoro di migrazione delle tabelle nel file leggimi UCX.

Strumenti aggiuntivi

UCX include anche strumenti di debug e altre utilità per facilitare la migrazione. Per altre informazioni, vedere il notebook README generato da UCX e il file leggimi del progetto UCX.

Aggiornare l'installazione ucx

Il progetto UCX viene aggiornato regolarmente. Per aggiornare l'installazione ucx alla versione più recente:

1. Verificare che UCX sia installato.

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

2. Eseguire l'aggiornamento:

   databricks labs upgrade ucx
   

Come ottenere assistenza

Per informazioni sull'interfaccia della riga di comando ucx, eseguire:

databricks labs ucx --help

Per assistenza con un comando UCX specifico, eseguire:

databricks labs ucx <command> --help

Per risolvere i problemi:

• Eseguire --debug con qualsiasi comando per abilitare i log di debug.
• Usare il notebook di debug generato automaticamente da UCX.

Per segnalare un problema o una richiesta di funzionalità, segnalare un problema di GitHub.

Note sulla versione ucx

Vedere il log delle modifiche nel repository GitHub UCX.