Migrieren von dbx zu Bündeln

Artikel
10/09/2024

Wichtig

Databricks empfiehlt, Databricks-Ressourcenbündel anstelle von dbx von Databricks Labs zu verwenden. Verwandte Artikel über dbx wurden eingestellt und werden möglicherweise nicht aktualisiert.

In diesem Artikel wird beschrieben, wie Sie Projekte für dbx von Databricks Labs zu Databricks-Ressourcenbündeln migrieren. Siehe Einführung in dbx von Databricks Labs und Was sind Databricks-Ressourcenbündel?.

Beachten Sie vor der Migration die folgenden Einschränkungen und Funktionsvergleiche zwischen dbx von Databricks Labs und Databricks-Ressourcenbündeln.

Begrenzungen

Die folgende Funktionalität, die in dbx von Databricks Labs unterstützt wird, ist eingeschränkt, ist nicht vorhanden oder erfordert Problemumgehungen in Databricks-Ressourcenbündeln.

Das Erstellen von JAR-Artefakten wird in Bündeln nicht unterstützt.
FUSE-Notation für Arbeitsbereichspfade wird in Bündeln nicht unterstützt (z. B /Workspace/<path>/<filename>). Sie können jedoch Bündel anweisen, Arbeitsbereichspfade im FUSE-Stil während der Bereitstellungen mithilfe von Notation wie z. B. /Workspace/${bundle.file_path}/<filename> zu generieren.

Vergleich der Features

Bevor Sie migrieren, beachten Sie, wie die folgenden Features für dbx von Databricks Labs in Databricks-Ressourcenbündeln implementiert werden.

Vorlagen und Projekte

dbx bieten Unterstützung für Jinja-Vorlagenerstellung. Sie können Jinja-Vorlagen in die Bereitstellungskonfiguration einschließen und Umgebungsvariablen entweder inline oder über eine Variablendatei übergeben. Obwohl nicht empfohlen, bietet dbx auch experimentelle Unterstützung für benutzerdefinierte Benutzerfunktionen.

Bündel bieten Unterstützung für Go-Vorlagen für die Wiederverwendung der Konfiguration. Benutzer können Bündel basierend auf vordefinierten Vorlagen erstellen. Es gibt fast vollständige Parität für Vorlagenerstellung, mit Ausnahme von benutzerdefinierten Benutzerfunktionen.

Buildverwaltung

dbx bietet Build-Unterstützung durch pip wheel, Poesie und Flit. Benutzer können die Buildoption im „build“-Abschnitt der „deployment.yml“-Datei eines Projekts angeben.

Bündel ermöglichen Benutzern das Erstellen, Bereitstellen und Ausführen von Python-Wheel-Dateien. Benutzer können den integrierten whl-Eintrag in der „databricks.yml“-Datei eines Bündels nutzen.

Synchronisieren, Bereitstellen und Ausführen von Code

dbx ermöglicht das Hochladen von Code getrennt von der Generierung von Arbeitsbereichsressourcen wie Azure Databricks-Aufträgen.

Bündel laden immer Code hoch und erstellen oder aktualisieren Arbeitsbereichsressourcen gleichzeitig. Dies vereinfacht Bereitstellungen und verhindert das Blockieren von Bedingungen für Aufträge, die bereits ausgeführt werden.

Migrieren eines dbx-Projekts zu einem Bündel

Nachdem Sie die vorstehenden Einschränkungen und Funktionsvergleiche zwischen dbx von Databricks Labs und Databricks-Ressourcenbündeln zur Kenntnis genommen haben, sind Sie bereit, von dbx zu Bündeln zu migrieren.

Databricks empfiehlt, dass Sie, um eine dbx-Projektmigration zu starten, Ihr dbx-Projekt in seinem ursprünglichen Ordner belassen und einen separaten, leeren Ordner haben, in den Sie den Inhalt Ihres ursprünglichen dbx-Projekts kopieren. Dieser separate Ordner wird Ihr neues Bündel sein. Es können unerwartete Probleme auftreten, wenn Sie mit der Konvertierung Ihres dbx-Projekts in seinem ursprünglichen Ordner in ein Bündel beginnen und dann einige Fehler machen oder von vorne beginnen möchten,

Schritt 1: Installieren und Einrichten der Databricks CLI

Databricks Asset Bundles sind allgemein in Databricks CLI Version 0.218.0 und höher verfügbar. Wenn Sie die Databricks CLI Version 0.218.0 oder höher bereits installiert und eingerichtet haben, fahren Sie mit Schritt 2 fort.

Hinweis

Bundles sind nicht kompatibel mit Version 0.18 und früheren Versionen der Databricks-Befehlszeilenschnittstelle.

Installieren oder aktualisieren Sie die Databricks CLI Version 0.218.0 oder höher. Siehe Installieren oder Aktualisieren der Databricks CLI.
Richten Sie die Databricks CLI für die Authentifizierung mit Ihren Azure Databricks-Zielarbeitsbereichen ein, z. B. mithilfe der Azure Databricks-Authentifizierung mit persönlichem Zugriffstoken. Weitere Azure Databricks-Authentifizierungstypen finden Sie unter Authentifizierung für die Databricks CLI.

Schritt 2: Erstellen der Bundlekonfigurationsdatei

Wenn Sie eine IDE wie Visual Studio Code, PyCharm Professional oderIntelliJ IDEA Ultimate verwenden, die Unterstützung für YAML-Dateien und JSON-Schemadateien bereitstellt, können Sie Ihre IDE nicht nur zum Erstellen der Bundlekonfigurationsdatei nutzen, sondern auch zum Überprüfen der Syntax und Formatierung der Datei und wie folgt zum Bereitstellen von Codeabschlusshinweisen.

Visual Studio Code

Fügen Sie Visual Studio Code-Unterstützung für YAML-Sprachserver hinzu, z. B. durch Installieren der YAML-Erweiterung aus dem Visual Studio Code Marketplace.
Generieren Sie die JSON-Schemadatei der Databricks-Ressourcenbundlekonfiguration, indem Sie die Databricks-CLI verwenden, um den Befehl bundle schema auszuführen und die Ausgabe an eine JSON-Datei umzuleiten. Generieren Sie beispielsweise wie folgt eine Datei namens „bundle_config_schema.json“ im aktuellen Verzeichnis:
```
databricks bundle schema > bundle_config_schema.json
```
Verwenden Sie Visual Studio Code, um eine Bundlekonfigurationsdatei im aktuellen Verzeichnis zu erstellen oder zu öffnen. Grundsätzlich heißt diese Datei databricks.yml.
Fügen Sie am Anfang Ihrer Bundlekonfigurationsdatei den folgenden Kommentar hinzu:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Hinweis

Wenn sich die JSON-Schemadatei ihrer Databricks-Ressourcenbundlekonfiguration in einem anderen Pfad befindet, ersetzen Sie bundle_config_schema.json im vorherigen Kommentar durch den vollständigen Pfad zu Ihrer Schemadatei.
Verwenden Sie die YAML-Sprachserverfunktionen, die Sie zuvor hinzugefügt haben. Weitere Informationen finden Sie in der Dokumentation Ihres YAML-Sprachservers.

PyCharm Professional

Generieren Sie die JSON-Schemadatei der Databricks-Ressourcenbundlekonfiguration, indem Sie die Databricks-CLI verwenden, um den Befehl bundle schema auszuführen und die Ausgabe an eine JSON-Datei umzuleiten. Generieren Sie beispielsweise wie folgt eine Datei namens „bundle_config_schema.json“ im aktuellen Verzeichnis:
```
databricks bundle schema > bundle_config_schema.json
```
Konfigurieren Sie PyCharm, um die JSON-Schemadatei der Bundlekonfiguration zu erkennen. Schließen Sie dann die JSON-Schemazuordnung ab, indem Sie die Anweisungen unter Konfigurieren eines benutzerdefinierten JSON-Schemasbefolgen.
Verwenden Sie PyCharm, um eine Bundlekonfigurationsdatei zu erstellen oder zu öffnen. Grundsätzlich heißt diese Datei databricks.yml. Während der Eingabe sucht PyCharm nach JSON-Schemasyntax und -formatierung und stellt Codeabschlusshinweise bereit.

IntelliJ IDEA Ultimate

Generieren Sie die JSON-Schemadatei der Databricks-Ressourcenbundlekonfiguration, indem Sie die Databricks-CLI verwenden, um den Befehl bundle schema auszuführen und die Ausgabe an eine JSON-Datei umzuleiten. Generieren Sie beispielsweise wie folgt eine Datei namens „bundle_config_schema.json“ im aktuellen Verzeichnis:
```
databricks bundle schema > bundle_config_schema.json
```
Konfigurieren Sie IntelliJ IDEA, um die JSON-Schemadatei der Bundlekonfiguration zu erkennen. Schließen Sie dann die JSON-Schemazuordnung ab, indem Sie die Anweisungen unter Konfigurieren eines benutzerdefinierten JSON-Schemasbefolgen.
Verwenden Sie IntelliJ IDEA, um eine Bundlekonfigurationsdatei zu erstellen oder zu öffnen. Grundsätzlich heißt diese Datei databricks.yml. Während der Eingabe sucht IntelliJ IDEA nach JSON-Schemasyntax und -formatierung und stellt Codeabschlusshinweise bereit.

Schritt 3: Konvertieren von dbx-Projekteinstellungen in databricks.yml

Konvertieren Sie die Einstellungen in der .dbx/project.json-Datei Ihres dbx-Projekts in die entsprechenden Einstellungen in der databricks.yml-Datei Ihres Bündels. Ausführliche Informationen finden Sie unter Konvertieren von dbx-Projekteinstellungen in databricks.yml.

Schritt 4: Konvertieren von dbx-Bereitstellungseinstellungen in databricks.yml

Konvertieren Sie die Einstellungen im conf-Ordner Ihres dbx-Projekts in die entsprechenden Einstellungen in der databricks.yml-Datei Ihres Bündels. Ausführliche Informationen finden Sie unter Konvertieren von dbx-Bereitstellungseinstellungen in databricks.yml.

Schritt 5: Validieren des Bündels

Bevor Sie Artefakte bereitstellen oder einen Azure Databricks-Auftrag, eine Delta Live Tables-Pipeline oder eine MLOps-Pipeline ausführen, sollten Sie sicherstellen, dass die Bundlekonfigurationsdatei syntaktisch korrekt ist. Führen Sie dazu den bundle validate-Befehl aus dem Bündelstamm aus:

databricks bundle validate

Informationen zu bundle validate finden Sie unter Überprüfen eines Bundles.

Schritt 6: Bereitstellen des Bündels

Um alle angegebenen lokalen Artefakte für den Remote-Arbeitsbereich bereitzustellen, führen Sie den bundle deploy-Befehl aus dem Bündelstamm aus. Wenn keine Befehlsoptionen angegeben sind, wird das in der Bundlekonfigurationsdatei deklarierte Standardziel verwendet:

databricks bundle deploy

Um die Artefakte im Kontext eines bestimmten Ziels bereitzustellen, geben Sie die Option -t oder --target zusammen mit dem Namen des Ziels an, der in der Bundlekonfigurationsdatei deklariert ist. Beispielsweise für ein Ziel, das mit dem Namen „development“ deklariert wird:

databricks bundle deploy -t development

Informationen zu bundle deploy finden Sie unter Bereitstellen eines Bundles.

Tipp

Sie können bundledefinierte Aufträge und Pipelines mit vorhandenen Aufträgen und Pipelines im Azure Databricks-Arbeitsbereich verknüpfen, um sie synchron zu halten. Weitere Informationen finden Sie unter Binden von Bundleressourcen.

Schritt 7: Ausführen des Bündels

Um einen bestimmten Auftrag oder eine bestimmte Pipeline auszuführen, führen Sie den bundle run-Befehl aus dem Bündelstamm aus. Sie müssen den in der Bundlekonfigurationsdatei deklarierten Auftrag oder die dort deklarierte Pipeline angeben. Wenn die Option -t nicht angegeben ist, wird das in der Bundlekonfigurationsdatei deklarierte Standardziel verwendet. So führen Sie beispielsweise einen Auftrag namens „hello_job“ im Kontext des Standardziels aus:

databricks bundle run hello_job

So führen Sie einen Auftrag namens „hello_job“ im Kontext eines Ziels aus, das mit dem Namen „development“ deklariert wurde:

databricks bundle run -t development hello_job

Weitere Informationen finden bundle runSie unter Ausführen eines Auftrags oder einer Pipeline.

(Optional) Schritt 8: Konfigurieren des Bündels für CI/CD mit GitHub

Wenn Sie GitHub für CI/CD verwenden, können Sie GitHub-Aktionen verwenden, um die databricks bundle deploy- und databricks bundle run-Befehle automatisch basierend auf bestimmten GitHub-Workflowereignissen und anderen Kriterien auszuführen. Weitere Informationen finden Sie unter Ausführen eines CI/CD-Workflows mit einem Databricks-Ressourcenpaket und GitHub Actions.

Konvertieren von dbx-Projekteinstellungen in databricks.yml

Für dbx befinden sich die Projekteinstellungen standardmäßig in einer Datei mit dem Namen project.json im .dbx-Ordner des Projekts. Siehe Projekt-Dateireferenz.

Bei Bundles befinden sich die Bundlekonfigurationen standardmäßig in einer Datei mit dem Namen databricks.yml im Stammordner des Bundle. Weitere Informationen finden Sie unter Konfiguration für Databricks-Ressourcenpakete.

Für eine conf/project.json-Datei mit folgendem Beispielinhalt:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

Die entsprechende databricks.yml-Datei lautet wie folgt:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Die folgenden Objekte in der vorherigen conf/project.json-Datei dieses Beispiels werden in databricks.yml-Dateien nicht unterstützt und weisen keine Problemumgehungen auf:

inplace_jinja_support
storage_type

Die folgenden zusätzlichen zulässigen Objekte in conf/project.json-Dateien werden in databricks.yml-Dateien nicht unterstützt und weisen keine Problemumgehungen auf:

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Konvertieren von dbx-Bereitstellungseinstellungen in databricks.yml

Für dbx sind die Bereitstellungseinstellungen standardmäßig in einer Datei im conf-Ordner des Projekts. Siehe Bereitstellungsdateireferenz. Die Bereitstellungseinstellungsdatei hat standardmäßig einen der folgenden Dateinamen:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

Bei Bündeln befinden sich die Bereitstellungseinstellungen standardmäßig in einer Datei mit dem Namen databricks.yml im Stammordner des Bündels. Weitere Informationen finden Sie unter Konfiguration für Databricks-Ressourcenpakete.

Für eine conf/deployment.yml-Datei mit folgendem Beispielinhalt:

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"