De UCX-hulpprogramma's gebruiken om uw werkruimte te upgraden naar Unity Catalog

In dit artikel maakt u kennis met UCX, een Databricks Labs-project dat hulpprogramma's biedt waarmee u uw niet-Unity-Catalog-werkruimte kunt upgraden naar Unity Catalog.

Notitie

UCX, net als alle projecten in het GitHub-account van Databrickslabs, wordt alleen aangeboden voor uw verkenning en wordt niet formeel ondersteund door Databricks met service level agreements (SLA's). Het wordt geleverd zoals het is. Wij doen geen garanties van welke aard dan ook. Dien geen Databricks-ondersteuningsticket in met betrekking tot problemen die ontstaan door het gebruik van dit project. Dien in plaats daarvan een GitHub-probleem in. Problemen worden beoordeeld als tijd is toegestaan, maar er zijn geen formele SLA's voor ondersteuning.

Het UCX-project biedt de volgende migratiehulpprogramma's en werkstromen:

1. Evaluatiewerkstroom om u te helpen bij het plannen van uw migratie.
2. Werkstroom voor groepsmigratie om u te helpen bij het upgraden van groepslidmaatschap van uw werkruimte naar uw Databricks-account en machtigingen te migreren naar de nieuwe groepen op accountniveau.
3. Werkstroom voor tabelmigratie om u te helpen bij het upgraden van tabellen die zijn geregistreerd in de Hive-metastore van uw werkruimte naar de Unity Catalog-metastore. Deze werkstroom helpt u ook bij het migreren van opslaglocaties en de referenties die nodig zijn voor toegang tot deze locaties.

In dit diagram ziet u de algehele migratiestroom, waarmee migratiewerkstromen en hulpprogramma's op naam worden geïdentificeerd:

Notitie

De werkstroom voor codemigratie die in het diagram wordt weergegeven, blijft in ontwikkeling en is nog niet beschikbaar.

Voordat u begint

Voordat u UCX kunt installeren en de UCX-werkstromen kunt uitvoeren, moet uw omgeving aan de volgende vereisten voldoen.

Pakketten die zijn geïnstalleerd op de computer waarop u UCX uitvoert:

• Databricks CLI v0.213 of hoger. Zie De Databricks CLI installeren of bijwerken.

  U moet een Databricks-configuratiebestand met configuratieprofielen hebben voor zowel de werkruimte als het Databricks-account.

• Python 3.10 of hoger.

• Als u de UCX-werkstroom wilt uitvoeren die opslaglocaties identificeert die worden gebruikt door Hive-tabellen in uw werkruimte (aanbevolen, maar niet vereist), moet de CLI voor uw cloudopslagprovider (Azure CLI of AWS CLI) zijn geïnstalleerd op de computer waarop u de UCX-werkstromen uitvoert.

Netwerktoegang:

• Netwerktoegang vanaf de computer waarop de UCX-installatie wordt uitgevoerd naar de Azure Databricks-werkruimte die u migreert.
• Netwerktoegang tot internet vanaf de computer waarop de UCX-installatie wordt uitgevoerd. Dit is vereist voor toegang tot pypi.org en github.com.
• Netwerktoegang vanuit uw Azure Databricks-werkruimte om pypi.org om de databricks-sdk en pyyaml pakketten te downloaden.

Databricks-rollen en -machtigingen:

• Beheerders- en werkruimtebeheerdersrollen van het Azure Databricks-account voor de gebruiker die de UCX-installatie uitvoert. U kunt de installatie niet uitvoeren als een service-principal.

Andere vereisten voor Databricks:

• Een Unity Catalog-metastore die is gemaakt voor elke regio die als host fungeert voor een werkruimte die u wilt upgraden, waarbij elk van deze Azure Databricks-werkruimten is gekoppeld aan een Unity Catalog-metastore.

  Als u wilt weten of u al een Unity Catalog-metastore hebt in de relevante werkruimteregio's, hoe u een metastore maakt als u dat niet doet en hoe u een Unity Catalog-metastore aan een werkruimte koppelt, raadpleegt u stap 1: Controleer of uw werkruimte is ingeschakeld voor Unity Catalog in het installatieartikel van de Unity-catalogus. Als alternatief biedt UCX een hulpprogramma voor het toewijzen van Unity Catalog-metastores aan werkruimten die u kunt gebruiken nadat UCX is geïnstalleerd.

  Als u een Unity Catalog-metastore koppelt aan een werkruimte, is ook identiteitsfederatie mogelijk, waarin u gebruikersbeheer centraliseert op het niveau van het Azure Databricks-account. Dit is ook een vereiste voor het gebruik van UCX. Zie Identiteitsfederatie inschakelen.

• Als uw werkruimte gebruikmaakt van een externe Hive-metastore (zoals AWS Glue) in plaats van de standaard hive-metastore in de werkruimte, moet u een aantal vereiste instellingen uitvoeren. Zie Externe Hive Metastore-integratie in de databrickslabs/ucx-opslagplaats.

• Een Pro- of Serverloze SQL-warehouse dat wordt uitgevoerd in de werkruimte waarin u UCX-werkstromen uitvoert, die vereist is om het rapport weer te geven dat is gegenereerd door de evaluatiewerkstroom.

UCX installeren

Als u UCX wilt installeren, gebruikt u de Databricks CLI:

databricks labs install ucx

U wordt gevraagd het volgende te selecteren:

1. Het Databricks-configuratieprofiel voor de werkruimte die u wilt upgraden. Het configuratiebestand moet ook een configuratieprofiel bevatten voor het bovenliggende Databricks-account van de werkruimte.

2. Een naam voor de inventarisdatabase die wordt gebruikt om de uitvoer van de migratiewerkstromen op te slaan. Normaal gesproken is het prima om de standaardwaarde te selecteren.ucx

3. Een SQL Warehouse waarop het installatieproces wordt uitgevoerd.

4. Een lijst met werkruimte-lokale groepen die u wilt migreren naar groepen op accountniveau. Als u dit als standaardgroep ()<ALL> laat staan, wordt elke bestaande groep op accountniveau waarvan de naam overeenkomt met een lokale groep in de werkruimte behandeld als vervanging voor die werkruimte-lokale groep en neemt alle werkruimtemachtigingen over wanneer u de werkstroom voor groepsmigratie uitvoert na de installatie.

   U hebt de mogelijkheid om de toewijzing van werkruimte-groep-naar-account-groep te wijzigen nadat u het installatieprogramma hebt uitgevoerd en voordat u groepsmigratie uitvoert. Zie Groepsnaamconflictoplossing in de UCX-opslagplaats.

5. Als u een externe Hive-metastore hebt, zoals AWS Glue, hebt u de mogelijkheid om er verbinding mee te maken of niet. Zie Externe Hive Metastore-integratie in de databrickslabs/ucx-opslagplaats.

6. Hiermee wordt aangegeven of het gegenereerde README-notebook moet worden geopend.

Wanneer de installatie is voltooid, wordt een README-notebook, dashboards, databases, bibliotheken, taken en andere assets in uw werkruimte geïmplementeerd.

Zie de installatie-instructies in het leesmij-bestand voor het project voor meer informatie. U kunt UCX ook installeren op alle werkruimten in uw Databricks-account.

Het README-notebook openen

Elke installatie maakt een README-notebook met een gedetailleerde beschrijving van alle werkstromen en taken, met snelle koppelingen naar de werkstromen en dashboards. Zie Leesmij-notitieblok.

Stap 1. De evaluatiewerkstroom uitvoeren

De evaluatiewerkstroom beoordeelt de Unity Catalog-compatibiliteit van groepsidentiteiten, opslaglocaties, opslagreferenties, toegangsbeheer en tabellen in de huidige werkruimte en biedt de informatie die nodig is voor het plannen van de migratie naar Unity Catalog. De taken in de evaluatiewerkstroom kunnen parallel of opeenvolgend worden uitgevoerd, afhankelijk van opgegeven afhankelijkheden. Nadat de evaluatiewerkstroom is voltooid, wordt een evaluatiedashboard gevuld met bevindingen en algemene aanbevelingen.

De uitvoer van elke werkstroomtaak wordt opgeslagen in Delta-tabellen in het schema dat u tijdens de $inventory_database installatie opgeeft. U kunt deze tabellen gebruiken om verdere analyse en besluitvorming uit te voeren met behulp van een evaluatierapport. U kunt de evaluatiewerkstroom meerdere keren uitvoeren om ervoor te zorgen dat alle incompatibele entiteiten worden geïdentificeerd en verantwoordelijk zijn voordat u het migratieproces start.

U kunt de evaluatiewerkstroom activeren vanuit het DOOR UCX gegenereerde README-notebook en de Azure Databricks UI (Workflows > Jobs > [UCX] Assessment) of de volgende Databricks CLI-opdracht uitvoeren:

databricks labs ucx ensure-assessment-run

Zie De evaluatiewerkstroom voor gedetailleerde instructies.

Stap 2. De werkstroom voor groepsmigratie uitvoeren

Met de werkstroom voor groepsmigratie worden werkruimte-lokale groepen bijgewerkt naar groepen op accountniveau ter ondersteuning van Unity Catalog. Het zorgt ervoor dat de juiste groepen op accountniveau beschikbaar zijn in de werkruimte en alle machtigingen repliceert. Ook worden overbodige groepen en machtigingen uit de werkruimte verwijderd. De taken in de werkstroom voor groepsmigratie zijn afhankelijk van de uitvoer van de evaluatiewerkstroom.

De uitvoer van elke werkstroomtaak wordt opgeslagen in Delta-tabellen in het schema dat u tijdens de $inventory_database installatie opgeeft. U kunt deze tabellen gebruiken om verdere analyse en besluitvorming uit te voeren. U kunt de werkstroom voor groepsmigratie meerdere keren uitvoeren om ervoor te zorgen dat alle groepen zijn geüpgraded en dat alle benodigde machtigingen zijn toegewezen.

Zie uw door UCX gegenereerde README-notebook en groepsmigratiewerkstroom in de UCX-leesmij voor informatie over het uitvoeren van de werkstroom voor groepsmigratie.

Stap 3. De werkstroom voor tabelmigratie uitvoeren

Met de werkstroom voor tabelmigratie worden tabellen van de Hive-metastore bijgewerkt naar de Unity Catalog-metastore. Externe tabellen in de Hive-metastore worden bijgewerkt als externe tabellen in Unity Catalog, met behulp van SYNC. Beheerde tabellen in de Hive-metastore die zijn opgeslagen in werkruimteopslag (ook wel DBFS-hoofdmap genoemd) worden bijgewerkt als beheerde tabellen in Unity Catalog, met behulp van DEEP CLONE.

Beheerde Hive-tabellen moeten de Delta- of Parquet-indeling hebben om een upgrade uit te voeren. Externe Hive-tabellen moeten een van de gegevensindelingen hebben die worden vermeld in Werken met externe tabellen.

De voorbereidende opdrachten uitvoeren

Tabelmigratie bevat een aantal voorbereidende taken die u uitvoert voordat u de werkstroom voor tabelmigratie uitvoert. U voert deze taken uit met behulp van de volgende Databricks CLI-opdrachten:

• Met create-table-mapping de opdracht, waarmee een CSV-bestand wordt gemaakt dat een doelcatalogus, schema en tabel toe wijst aan elke Hive-tabel die wordt bijgewerkt. Controleer en werk het toewijzingsbestand bij voordat u doorgaat met de migratiewerkstroom.
• De create-uber-principal opdracht, waarmee een service-principal wordt gemaakt met alleen-lezentoegang tot alle opslag die door de tabellen in deze werkruimte wordt gebruikt. De rekenresource voor werkstroomtaken gebruikt deze principal om de tabellen in de werkruimte bij te werken. De inrichting van deze service-principal ongedaan maken wanneer u klaar bent met uw upgrade.
• (Optioneel) De principal-prefix-access opdracht, waarmee de opslagaccounts en toegangsreferenties voor opslag worden geïdentificeerd die worden gebruikt door de Hive-tabellen in de werkruimte.
• (Optioneel) De migrate-credentials opdracht, waarmee opslagreferenties voor Unity Catalog worden gemaakt op basis van de opslagtoegangsreferenties die zijn geïdentificeerd door principal-prefix-access.
• (Optioneel) De migration locations opdracht, waarmee externe locaties van Unity Catalog worden gemaakt op basis van de opslaglocaties die zijn geïdentificeerd door de evaluatiewerkstroom, met behulp van de opslagreferenties die zijn gemaakt door migrate-credentials.
• (Optioneel) De create-catalogs-schemasopdracht, waarmee Unity Catalog-catalogi en schema's worden gemaakt die de bijgewerkte tabellen bevatten.

Zie Tabelmigratieopdrachten in het leesmij-leesmij-bestand voor tabelmigratie voor meer informatie, waaronder aanvullende opdrachten en opties voor tabelmigratie.

De tabelmigratie uitvoeren

Zodra u de voorbereidende taken hebt uitgevoerd, kunt u de werkstroom voor tabelmigratie uitvoeren vanuit het DOOR UCX gegenereerde README-notebook of vanuit werkstromentaken > in de gebruikersinterface van de werkruimte.

De uitvoer van elke werkstroomtaak wordt opgeslagen in Delta-tabellen in het schema dat u tijdens de $inventory_database installatie opgeeft. U kunt deze tabellen gebruiken om verdere analyse en besluitvorming uit te voeren. Mogelijk moet u de werkstroom voor tabelmigratie meerdere keren uitvoeren om ervoor te zorgen dat alle tabellen zijn bijgewerkt.

Zie uw door UCX gegenereerde README-notebook en de werkstroom voor tabelmigratie in de UCX-leesmij voor volledige instructies voor tabelmigratie.

Aanvullende hulpprogramma’s

UCX bevat ook foutopsporingsprogramma's en andere hulpprogramma's om u te helpen slagen met uw migratie. Zie uw door UCX gegenereerde README-notebook en het leesmij-leesmij-bestand van het UCX-project voor meer informatie.

Uw UCX-installatie upgraden

Het UCX-project wordt regelmatig bijgewerkt. Uw UCX-installatie upgraden naar de nieuwste versie:

1. Controleer of UCX is geïnstalleerd.

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

2. Voer de upgrade uit:

   databricks labs upgrade ucx
   

Hulp vragen

Voer voor hulp bij de UCX CLI het volgende uit:

databricks labs ucx --help

Voer voor hulp bij een specifieke UCX-opdracht het volgende uit:

databricks labs ucx <command> --help

Problemen oplossen:

• Voer de opdracht uit --debug om foutopsporingslogboeken in te schakelen.
• Gebruik het notebook voor foutopsporing dat automatisch wordt gegenereerd door UCX.

Als u een probleem of functieaanvraag wilt indienen, dient u een GitHub-probleem in.

Opmerkingen bij de release van UCX

Bekijk het wijzigingenlogboek in de UCX GitHub-opslagplaats.