Migrieren von dbx zu Bündeln

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 Asset Bundles?.

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

Merkmalsvergleich

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 Unterstützung für Jinja-Templating bieten. 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.

Bundles bieten Unterstützung für die Wiederverwendung von Konfigurationen mit Go-Vorlagen. 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 Projektdatei deployment.yml 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 Lakeflow-Aufträgen.

Bundles 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 für den Beginn einer dbx-Projektmigration Ihr dbx-Projekt in seinem ursprünglichen Ordner belassen und einen separaten, leeren Ordner anlegen, 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 Authentifizierung mit persönlichem Zugriffstoken (veraltet). Weitere Azure Databricks-Authentifizierungstypen finden Sie unter "Authentication for the Databricks CLI".

Schritt 2: Erstellen der Bundlekonfigurationsdatei

Wenn Sie eine IDE wie Visual Studio Code, PyCharm Professional oder IntelliJ IDEA Ultimate verwenden, die Unterstützung für YAML-Dateien und JSON-Schemadateien bereitstellt, können Sie Ihre IDE nicht nur verwenden, um die Bündelkonfigurationsdatei zu erstellen, sondern die Syntax und Formatierung der Datei zu überprüfen und Codeabschlusshinweise wie folgt bereitzustellen.

Visual Studio Code

Fügen Sie yaML-Sprachserverunterstützung zu Visual Studio Code 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, und schließen Sie dann die JSON-Schemazuordnung ab, indem Sie die Anweisungen unter Konfigurieren eines benutzerdefinierten JSON-Schemas befolgen.
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, und schließen Sie dann die JSON-Schemazuordnung ab, indem Sie die Anweisungen unter Konfigurieren eines benutzerdefinierten JSON-Schemas befolgen.
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 Datei Ihres dbx Projekts .dbx/project.json in die entsprechenden Einstellungen in der Datei Ihres Bundles databricks.yml . 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 Ordner Ihres dbx Projekts conf in die entsprechenden Einstellungen in der Datei Ihres Bundles databricks.yml . Ausführliche Informationen finden Sie unter Konvertieren von dbx-Bereitstellungseinstellungen in databricks.yml.

Schritt 5: Validieren des Bündels

Before you deploy artifacts or run a Azure Databricks job, a :, or an MLOps pipeline, you should make sure that your bundle configuration Datei is syntactically correct. Führen Sie dazu den bundle validate-Befehl aus dem Bündelstamm aus:

databricks bundle validate

Weitere Informationen über bundle validatefinden Sie unter „databricks bundle validate“.

Schritt 6: Bereitstellen des Bündels

Um alle angegebenen lokalen Artefakte für den Remotearbeitsbereich bereitzustellen, führen Sie den bundle deploy-Befehl aus dem Stammverzeichnis des Bundle 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 -t Option (oder --target) zusammen mit dem Namen des Ziels an, wie in der Bundlekonfigurationsdatei deklariert. Beispielsweise für ein Ziel, das mit dem Namen „development“ deklariert wird:

databricks bundle deploy -t development

Weitere Informationen zu bundle deploy finden Sie unter databricks bundle deploy.

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. Siehe Databricks Bundle-Bereitstellungsbindung.

Schritt 7: Das Bundle ausführen

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 zu bundle run finden Sie unter databricks bundle run.

(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. Siehe GitHub-Aktionen.

Konvertieren von dbx-Projekteinstellungen in databricks.yml

Bei dbx befinden sich die Projekteinstellungen standardmäßig in einer Datei namens project.json im Projektordner .dbx. Siehe Project-Dateireferenz.

Bei Bündeln befinden sich Bündelkonfigurationen standardmäßig in einer Datei, die im Stammordner des Bündels benannt databricks.yml ist. Siehe Databricks Asset Bundle-Konfiguration.

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 Ordner des conf Projekts. Siehe Referenz zur Bereitstellungsdatei. 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, die im Stammordner des Bundles benannt databricks.yml ist. Siehe Databricks Asset Bundle-Konfiguration.

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'