Freigeben über

Verwenden der UCX-Hilfsprogramme zum Upgrade Ihres Arbeitsbereichs auf Unity Catalog

  • Artikel

In diesem Artikel wird UCX vorgestellt, ein Databricks Labs-Projekt, das Tools bereitstellt, mit denen Sie Ihren Nicht-Unity Catalog-Arbeitsbereich auf Unity Catalog aktualisieren können.

Hinweis

UCX wird, wie alle Projekte im GitHub-Konto von databrickslabs, nur zu Ihrer Erkundung zur Verfügung gestellt und wird von Databricks nicht formell mit Vereinbarungen zum Servicelevel (SLAs) unterstützt. Es wird so bereitgestellt, wie es ist. Wir übernehmen keine Garantien irgendwelcher Art. Erstellen Sie kein Databricks-Support-Ticket für Probleme, die sich aus der Verwendung dieses Projekts ergeben. Erstellen Sie stattdessen ein GitHub-Issue. Issues werden geprüft, wenn es die Zeit erlaubt, aber es gibt keine formellen SLAs für den Support.

Das UCX-Projekt bietet die folgenden Migrationstools und Workflows:

  1. Bewertungsworkflow, um Ihre Migration zu planen.
  2. Gruppenmigrationsworkflow, um die Gruppenmitgliedschaft von Ihrem Arbeitsbereich auf Ihr Databricks-Konto zu aktualisieren und Berechtigungen zu den neuen Gruppen auf Kontoebene zu migrieren.
  3. Tabellenmigrationsworfklow, damit Sie Tabellen, die im Hive-Metastore Ihres Arbeitsbereichs registriert sind auf den Unity Catalog-Metastore upgraden können. Dieser Workflow hilft Ihnen auch beim Migrieren der Speicherorte und Anmeldeinformationen, die für den Zugriff auf diese Speicherorte erforderlich sind.

Diese Abbildung zeigt den gesamten Migrationsflow. Der Migrationsworkflow und Hilfsprogramme sind anhand ihrer Namen gekennzeichnet:

UCX-Migrationsworkflows (Diagramm)

Hinweis

Der Codemigrationsworkflow, der in der Abbildung dargestellt wird, befindet sich noch in der Entwicklung und ist noch nicht verfügbar.

Voraussetzungen

Bevor Sie UCX installieren und die UCX-Workflows ausführen können, muss Ihre Umgebung die folgenden Anforderungen erfüllen.

Pakete, die auf dem Computer, auf dem Sie UCX ausführen, installiert sein müssen:

  • Databricks CLI v0.213 oder höher. Weitere Informationen finden Sie unter Installieren oder Aktualisieren der Databricks CLI.

    Sie müssen über eine Databricks-Konfigurationsdatei mit Konfigurationsprofilen für den Arbeitsbereich und das Databricks-Konto verfügen.

  • Python 3.10 oder höher.

  • Wenn Sie den UCX-Workflow ausführen möchten, der die von Hive-Tabellen in Ihrem Arbeitsbereich verwendeten Speicherorte identifiziert (empfohlen, aber nicht erforderlich), müssen Sie die CLI für Ihren Cloud-Speicheranbieter (Azure CLI oder AWS CLI) auf dem Computer installiert haben, auf dem Sie die UCX-Workflows ausführen.

Netzwerkzugriff:

  • Netzwerkzugriff von dem Computer, auf dem die UCX-Installation läuft, auf den Azure Databricks-Arbeitsbereich, den Sie migrieren möchten.
  • Netzwerkzugriff auf das Internet von dem Computer aus, auf dem die UCX-Installation ausgeführt wird. Dies ist für den Zugriff auf pypi.org und github.com erforderlich.
  • Netzwerkzugriff von Ihrem Azure Databricks-Arbeitsbereich auf pypi.org, um die Pakete databricks-sdk und pyyaml herunterzuladen.

Databricks-Rollen und -Berechtigungen:

  • Azure Databricks-Rollen Kontoadmin und Arbeitsbereichsadmin für die Benutzerin oder den Benutzer, die oder der die UCX-Installation ausführt. Sie können die Installation nicht als Dienstprinzipal ausführen.

Weitere Voraussetzungen für Databricks:

  • Ein Unity Catalog-Metastore, der für jede Region erstellt wird, in der sich ein Arbeitsbereich befindet, den Sie upgraden möchten, wobei jeder dieser Azure Databricks-Arbeitsbereiche mit einem Unity Catalog-Metastore verbunden ist.

    Wie Sie feststellen können, ob Sie bereits einen Unity Catalog-Metastore in den entsprechenden Arbeitsbereichsregionen haben, wie Sie einen Metastore erstellen, wenn dies nicht der Fall ist, und wie Sie einen Unity Catalog-Metastore an einen Arbeitsbereich anhängen, erfahren Sie in Schritt 1: Bestätigen, dass Ihr Arbeitsbereich für Unity Catalog aktiviert ist, im Artikel „Unity Catalog-Einrichtung“. Als Alternative bietet UCX ein Hilfsprogramm für die Zuweisung von Unity Catalog-Metastores zu Arbeitsbereichen, das Sie nach der Installation von UCX verwenden können.

    Das Anhängen eines Unity Catalog-Metastores an einen Arbeitsbereich ermöglicht auch den Identitätsverbund, bei dem Sie die Benutzerverwaltung auf der Ebene des Azure Databricks-Kontos zentralisieren, was ebenfalls eine Voraussetzung für die Verwendung von UCX ist. Weitere Informationen finden Sie unter Aktivieren des Identitätsverbunds.

  • Wenn Ihr Arbeitsbereich einen externen Hive-Metastore (z. B. AWS Glue) anstelle des standardmäßigen arbeitsbereichslokalen Hive-Metastores verwendet, müssen Sie einige Voreinstellungen vornehmen. Weitere Informationen finden Sie unter Externe Hive-Metastore-Integration im databrickslabs/ucx-Repository.

  • Ein Pro- oder Serverless-SQL-Warehouse, das auf dem Arbeitsbereich ausgeführt wird, auf dem Sie UCX-Workflows ausführen, und das zum Rendern des vom Bewertungsworkflow generierten Berichts erforderlich ist.

Installieren von UCX

Verwenden Sie zum Installieren von UCX die Databricks CLI:

databricks labs install ucx

Sie werden aufgefordert, Folgendes auszuwählen:

  1. Das Databricks-Konfigurationsprofil für den Arbeitsbereich, den Sie upgraden möchten. Die Konfigurationsdatei muss auch ein Konfigurationsprofil für das übergeordnete Databricks-Konto des Arbeitsbereichs enthalten.

  2. Einen Namen für die Bestandsdatenbank, in der die Ausgabe der Migrationsworkflows gespeichert wird. Normalerweise ist es in Ordnung, die Standardeinstellung zu wählen, nämlich ucx.

  3. Ein SQL-Warehouse zum Ausführen des Installationsprozesses.

  4. Eine Liste der arbeitsbereichslokalen Gruppen, die Sie zu Kontogruppen migrieren möchten. Wenn Sie dafür die Standardeinstellung (<ALL>) wählen, wird jede vorhandene Kontogruppe, deren Name mit einer arbeitsbereichslokalen Gruppe übereinstimmt, als Ersatz für diese arbeitsbereichslokale Gruppe behandelt und erbt alle ihre Arbeitsbereichsberechtigungen, wenn Sie den Gruppenmigrationsworkflow nach der Installation ausführen.

    Sie haben die Möglichkeit, die Zuordnung von Arbeitsbereichsgruppen zu Kontengruppen zu ändern, nachdem Sie das Installationsprogramm ausgeführt haben und bevor Sie die Gruppenmigration durchführen. Weitere Informationen finden Sie unter Lösun g von Gruppennamen-Konflikten im UCX-Repository.

  5. Wenn Sie über einen externen Hive-Metastore verfügen, wie z. B. AWS Glue, haben Sie die Möglichkeit, eine Verbindung zu diesem herzustellen oder nicht. Weitere Informationen finden Sie unter Externe Hive-Metastore-Integration im databrickslabs/ucx-Repository.

  6. Ob das generierte README-Notebook geöffnet werden soll.

Wenn die Installation abgeschlossen ist, werden ein README-Notebook, Dashboards, Datenbanken, Bibliotheken, Aufträge und andere Ressourcen in Ihrem Arbeitsbereich bereitgestellt.

Weitere Informationen finden Sie in den Installationshinweisen in der Readme-Datei des Projekts. Sie können UCX auch auf allen Arbeitsbereichen in Ihrem Databricks-Konto installieren.

Öffnen des README-Notebooks

Jede Installation erstellt ein README-Notebook, das eine detaillierte Beschreibung aller Workflows und Aufgaben mit Quicklinks zu Workflows und Dashboards bereitstellt. Weitere Informationen finden Sie unter Readme-Notebook.

Schritt 1. Ausführen des Bewertungsworkflows

Der Bewertungsworkflow bewertet die Kompatibilität von Gruppenidentitäten, Speicherorten, Speicheranmeldeinformationen, Zugriffskontrollen und Tabellen im aktuellen Arbeitsbereich mit Unity Catalog und liefert die notwendigen Informationen für die Planung der Migration zu Unity Catalog. Die Aufgaben im Beurteilungsworkflow können parallel oder nacheinander ausgeführt werden, je nach den festgelegten Abhängigkeiten. Nach Abschluss des Bewertungsworkflows wird ein Bewertungs-Dashboard mit den Ergebnissen und gemeinsamen Empfehlungen erstellt.

Die Ausgabe jeder Workflow-Aufgabe wird in Delta-Tabellen in dem $inventory_database-Schema gespeichert, das Sie bei der Installation angeben. Sie können diese Tabellen zur weiteren Analyse und Entscheidungsfindung mit Hilfe eines Bewertungsberichts verwenden. Sie können den Bewertungsworkflow mehrmals ausführen, um sicherzustellen, dass alle inkompatiblen Entitäten identifiziert und berücksichtigt werden, bevor Sie mit der Migration beginnen.

Sie können den Bewertungsworkflow über das von UCX generierte README-Notebook und die Azure Databricks-Benutzeroberfläche (Workflows > Aufträge > [UCX] Bewertung) auslösen oder den folgenden Databricks CLI-Befehl ausführen:

databricks labs ucx ensure-assessment-run

Ausführliche Anweisungen finden Sie unter Bewertungsworkflow.

Schritt 2. Ausführen des Gruppenmigrationsworkflows

Der Gruppenmigrationsworkflow aktualisiert arbeitsbereichslokale Gruppen zu Kontogruppen, um Unity Catalog zu unterstützen. Er stellt sicher, dass die entsprechenden Kontogruppen im Arbeitsbereich verfügbar sind und repliziert alle Berechtigungen. Außerdem werden alle unnötigen Gruppen und Berechtigungen aus dem Arbeitsbereich entfernt. Die Aufgaben im Gruppenmigrationsworkflow hängen von der Ausgabe des Bewertungsworkflows ab.

Die Ausgabe jeder Workflow-Aufgabe wird in Delta-Tabellen in dem $inventory_database-Schema gespeichert, das Sie bei der Installation angeben. Sie können diese Tabellen für weitere Analysen und Entscheidungen verwenden. Sie können den Gruppenmigrationsworkflow mehrmals ausführen, um sicherzustellen, dass alle Gruppen erfolgreich aktualisiert und alle erforderlichen Berechtigungen zugewiesen wurden.

Informationen zur Ausführung des Gruppenmigrationsworkflows finden Sie in Ihrem von UCX generierten README-Notebook und unter Gruppenmigrationsworkflow in der UCX-Readme.

Schritt 3. Ausführen des Tabellenmigrationsworkflows

Der Tabellenmigrationsworkflow aktualisiert Tabellen aus dem Hive-Metastore in den Unity Catalog-Metastore. Externe Tabellen im Hive-Metastore werden mit SYNC als externe Tabellen im Unity Catalog aktualisiert. Verwaltete Tabellen im Hive-Metastore, die im Arbeitsbereichsspeicher (auch bekannt als DBFS-Root) gespeichert sind, werden mit DEEP CLONE als verwaltete Tabellen im Unity Catalog aktualisiert.

Die von Hive verwalteten Tabellen müssen im Delta- oder Parquet-Format vorliegen, um aktualisiert zu werden. Externe Hive-Tabellen müssen in einem der unter Externe Tabellen aufgeführten Datenformate vorliegen.

Ausführen der vorbereitenden Befehle

Die Tabellenmigration umfasst eine Reihe von vorbereitenden Aufgaben, die Sie ausführen, bevor Sie den Workflow für die Tabellenmigration starten. Sie führen diese Aufgaben mit den folgenden Databricks CLI-Befehlen aus:

  • Der Befehl create-table-mapping, mit dem eine CSV-Datei erstellt wird, die jeder zu aktualisierenden Hive-Tabelle einen Unity Catalog-Zielkatalog, ein Schema und eine Tabelle zuordnet. Sie sollten die Zuordnungsdatei überprüfen und aktualisieren, bevor Sie mit dem Migrationsworkflow fortfahren.
  • Der Befehl create-uber-principal, der ein Dienstprinzipal mit schreibgeschütztem Zugriff auf den gesamten von den Tabellen in diesem Arbeitsbereich verwendeten Speicher erstellt. Die Computeressource für den Workflow-Auftrag verwendet dieses Prinzip, um die Tabellen im Arbeitsbereich zu aktualisieren. Entfernen Sie dieses Dienstprinzipal, wenn Sie mit dem Upgrade fertig sind.
  • (Optional) Der Befehl principal-prefix-access, der die von den Hive-Tabellen im Arbeitsbereich verwendeten Speicherkonten und Speicherzugriffsberechtigungen identifiziert.
  • (Optional) Der Befehl migrate-credentials, der Unity Catalog Speicherzugangsdaten aus den durch principal-prefix-access identifizierten Speicherzugangsdaten erstellt.
  • (Optional) Der Befehl migration locations, mit dem externe Speicherorte von Unity Catalog aus den vom Bewertungsworkflow identifizierten Speicherorten erstellt werden, unter Verwendung der mit migrate-credentials erstellten Speicheranmeldeinformationen.
  • (Optional) Der Befehl create-catalogs-schemas, der Unity Catalog Kataloge und Schemata erstellt, die die aktualisierten Tabellen enthalten werden.

Ausführliche Informationen, einschließlich zusätzlicher Befehle und Optionen für die Tabellenmigration, finden Sie unter Befehle für die Tabellenmigration in der UCX-Readme-Datei.

Ausführen des Tabellenmigration

Sobald Sie die vorbereitenden Aufgaben ausgeführt haben, können Sie den Tabellenmigrationsworkflow über das von UCX generierte README-Notebook oder über Workflows > Aufträge in der Benutzeroberfläche des Arbeitsbereichs ausführen.

Die Ausgabe jeder Workflow-Aufgabe wird in Delta-Tabellen in dem $inventory_database-Schema gespeichert, das Sie bei der Installation angeben. Sie können diese Tabellen für weitere Analysen und Entscheidungen verwenden. Möglicherweise müssen Sie den Tabellenmigrationsworkflow mehrmals ausführen, um sicherzustellen, dass alle Tabellen erfolgreich aktualisiert wurden.

Eine vollständige Anleitung zur Tabellenmigration finden Sie in Ihrem von UCX generierten README-Notebook und unter Tabellenmigrationsworkflow in der UCX-Readme-Datei.

Weitere Tools

UCX enthält auch Debugging-Tools und andere Hilfsprogramme, die Ihnen bei der erfolgreichen Migration helfen. Weitere Informationen finden Sie in Ihrem von UCX generierten README-Notebook und in der Readme-Datei des UCX-Projekts.

Upgrade Ihrer UCX-Installation

Das UCX-Projekt wird regelmäßig aktualisiert. So aktualisieren Sie Ihre UCX-Installation auf die neueste Version:

  1. Vergewissern Sie sich, dass UCX installiert ist.

    databricks labs installed

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

  2. Ausführen des Upgrades:

    databricks labs upgrade ucx

Hilfe erhalten

Hilfe zum UCX CLI erhalten Sie, indem Sie folgenden Befehl ausführen:

databricks labs ucx --help

Hilfe zu einem bestimmten UCX-Befehl erhalten Sie, indem Sie folgenden Befehl ausführen:

databricks labs ucx <command> --help

So beheben Sie Probleme:

Um ein Problem zu melden oder ein Feature anzufordern, erstellen Sie ein GitHub-Issue.

UCX-Versionshinweise

Weitere Informationen finden Sie unter changelog im UCX GitHub-Repository.