Konvertieren einer Pipeline in ein Bündelprojekt

Sie können eine vorhandene Pipeline in ein Deklaratives Automatisierungsbundle-Projekt konvertieren. Mit Bundles können Sie Ihre Azure Databricks-Datenverarbeitungskonfiguration in einer einzigen, quellgesteuerten YAML-Datei definieren und verwalten, die eine einfachere Wartung bietet und die automatisierte Bereitstellung für Zielumgebungen ermöglicht.

Ein Lernprogramm, das databricks pipelines Befehle zum Erstellen eines Pipelineprojekts verwendet, dann eine Pipeline bereitstellt und ausführt, finden Sie unter Entwickeln von Pipelines mit deklarativen Automatisierungspaketen.

Übersicht über den Konvertierungsprozess

Diagramm, das die spezifischen Schritte bei der Umwandlung einer vorhandenen Pipeline in ein Bundle zeigt

Die Schritte zum Konvertieren einer vorhandenen Pipeline in ein Bündel sind:

  1. Stellen Sie sicher, dass Sie Zugriff auf eine zuvor konfigurierte Pipeline haben, die Sie in ein Bundle konvertieren möchten.
  2. Erstellen Sie einen Ordner (vorzugsweise in einer quellcodegesteuerten Hierarchie) zum Speichern des Pakets, oder bereiten Sie einen solchen Ordner vor.
  3. Generieren Sie eine Konfiguration für das Bundle aus der vorhandenen Pipeline mithilfe der Databricks CLI.
  4. Überprüfen Sie die generierte Bündelkonfiguration, um sicherzustellen, dass sie abgeschlossen ist.
  5. Verknüpfen Sie das Bündel mit der ursprünglichen Pipeline.
  6. Stellen Sie die Pipeline mithilfe der Bundlekonfiguration in einem Zielarbeitsbereich bereit.

Anforderungen

Bevor Sie beginnen können, benötigen Sie Folgendes:

Schritt 1: Einrichten eines Ordners für Ihr Bundleprojekt

Sie müssen Zugriff auf ein Git-Repository haben, das in Azure Databricks als Git-Ordner konfiguriert ist. Sie erstellen Ihr Bündelprojekt in diesem Repository, das die Quellcodeverwaltung anwendet und sie anderen Mitarbeitern über einen Git-Ordner im entsprechenden Azure Databricks-Arbeitsbereich zur Verfügung stellt. (Weitere Details zu Git-Ordnern finden Sie unter Azure Databricks Git-Ordner.)

  1. Wechseln Sie zum Stamm des geklonten Git-Repositorys auf Ihrem lokalen Computer.

  2. Erstellen Sie an einer geeigneten Stelle in der Ordnerhierarchie einen Ordner speziell für Ihr Bündelprojekt. Beispiel:

    mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle

  3. Ändern Sie Ihr aktuelles Arbeitsverzeichnis in diesen neuen Ordner. Beispiel:

    cd ~/source/my-pipelines/ingestion/events/my-bundle

  4. Initialisieren Sie ein neues Bundle, indem Sie Folgendes ausführen:

    databricks bundle init

    Beantworten Sie die Eingabeaufforderungen. Nach Abschluss des Vorgangs verfügen Sie über eine Projektkonfigurationsdatei namens databricks.yml im neuen Startordner für Ihr Projekt. Diese Datei ist für die Bereitstellung der Pipeline über die Befehlszeile erforderlich. Weitere Informationen zu dieser Konfigurationsdatei finden Sie unter Deklarative Automation Bundles-Konfiguration.

Schritt 2: Generieren der Pipelinekonfiguration

Führen Sie in diesem neuen Verzeichnis in der Ordnerstruktur Ihres geklonten Git-Repositorys den Befehl "Databricks CLI bundle generate" aus, und stellen Sie die ID Ihrer Pipeline wie <pipeline-id>folgt bereit:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

Wenn Sie den generate Befehl ausführen, wird eine Bundlekonfigurationsdatei für Ihre Pipeline im Ordner des Bundles resources erstellt und alle referenzierten Artefakte in den src Ordner heruntergeladen. Das --profile (oder -p Flag) ist optional, aber wenn Sie über ein bestimmtes Databricks-Konfigurationsprofil verfügen (definiert in Ihrer .databrickscfg Datei, die beim Installieren der Databricks CLI erstellt wurde), sollten Sie es lieber anstelle des Standardprofils verwenden, in diesem Befehl angeben. Informationen zu Databricks-Konfigurationsprofilen finden Sie unter Azure Databricks-Konfigurationsprofile.

Tipp

Wenn Sie über ein vorhandenes Spark Declarative Pipelines (SDP)-Projekt verfügen (es verfügt über eine spark-pipeline.yml Datei), können Sie dieses Pipelineprojekt in den src Ordner des Bundles kopieren und dann den databricks pipelines generate Befehl verwenden, um die Bundlekonfiguration dafür zu generieren. Siehe Databricks-Pipelines generieren.

Schritt 3: Überprüfen der Bündelprojektdateien

Nach Abschluss des bundle generate Befehls werden zwei neue Ordner erstellt:

  • resources ist das Projektunterverzeichnis, das Projektkonfigurationsdateien enthält.
  • src ist der Projektordner, in dem Quelldateien wie Abfragen und Notizbücher gespeichert werden.

Mit dem Befehl werden auch einige zusätzliche Dateien erstellt:

  • *.pipeline.yml im Unterverzeichnis resources. Diese Datei enthält die spezifische Konfiguration und Einstellungen für Ihre Pipeline.
  • Quelldateien wie beispielsweise SQL-Abfragen im src Unterverzeichnis, welche aus der bestehenden Pipeline kopiert wurden.
├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Schritt 4: Verbinden Sie die Bundle-Pipeline mit Ihrer vorhandenen Pipeline

Sie müssen die Pipelinedefinition im Bündel mit Ihrer vorhandenen Pipeline verknüpfen oder binden, um sie beim Ändern auf dem neuesten Stand zu halten. Führen Sie dazu den Befehl "Databricks CLI Bundle Deployment Bind" aus:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> ist der Name der Pipeline. Dieser Name sollte mit dem präfixierten Zeichenfolgenwert des Dateinamens für die Pipelinekonfiguration in Ihrem neuen resources Verzeichnis identisch sein. Wenn Sie beispielsweise über eine Pipelinekonfigurationsdatei mit dem Namen ingestion_data_pipeline.pipeline.yml in Ihrem resources Ordner verfügen, müssen Sie ingestion_data_pipeline als Pipelinenamen angeben.

<pipeline-ID> ist die ID für Ihre Pipeline. Es ist dasselbe, das Sie als Teil der Anforderungen für diese Anweisungen kopiert haben.

Schritt 5: Bereitstellen der Pipeline mithilfe Ihres neuen Pakets

Stellen Sie nun Ihr Pipeline-Bundle in Ihrem Zielarbeitsbereich mit dem Befehl bundle deploy des Databricks CLI bereit.

databricks bundle deploy --target <target-name> --profile <profile-name>

Das --target Flag ist erforderlich und muss auf eine Zeichenfolge festgelegt werden, die einem konfigurierten Zielarbeitsbereichsnamen entspricht, z. B. development oder production.

Wenn dieser Befehl erfolgreich ist, verfügen Sie jetzt über ihre Pipelinekonfiguration in einem externen Projekt, das in andere Arbeitsbereiche geladen und ausgeführt werden kann, und sie können problemlos mit anderen Azure Databricks-Benutzern in Ihrem Konto geteilt werden.

Umgebungsübergreifendes Höherstufen mit Zielen

Ein Bundle definiert benannte Bereitstellungsumgebungen, die in databricks.yml als Targets bezeichnet werden und jeweils auf ihren eigenen Arbeitsbereich, Katalog und ihre eigenen Variablenwerte verweisen. Ziele sind, wie man dieselbe Pipeline durch Entwicklung, Staging und Produktion fördert und identischen Quellcode für jede nachfolgende Umgebung bereitstellt, ohne sie zu bearbeiten:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Die mode, die Sie für jedes Ziel festlegen, ändert dessen Bereitstellungsverhalten:

  • mode: development markiert ein Ziel als persönliche Scratch-Bereitstellung. Ressourcen erhalten ein [dev username] Präfix und Zeitpläne werden standardmäßig pausiert, sodass deine Arbeit niemanden anderen beeinflusst.
  • mode: production deaktiviert diese Sicherheitsvoreinstellungen. In Kombination mit run_as können Sie die Pipeline als Dienstprinzipal anstelle eines individuellen Kontos ausführen, sodass Ausführungen nicht fehlschlagen, wenn jemand das Team verlässt oder die Rolle wechselt. Azure Databricks empfiehlt einen Service Principal für Staging und Produktion. service_principal_name verwendet die Anwendungs-ID des Dienstprinzipals, nicht seinen Anzeigenamen. Du kannst die Anwendungs-ID von der Seite des Service Principal in deinen Workspace-Admin-Einstellungen abrufen.

Eine vollständige Übersicht über das Verhalten der einzelnen Modi finden Sie unter Bereitstellungsmodi für Declarative Automation Bundles und Eine Ausführungsidentität für einen Declarative Automation Bundles-Workflow angeben.

Um eine Höherstufung durchzuführen, stellen Sie dasselbe Bundle nacheinander in jedem Ziel bereit, und überprüfen Sie jede Phase:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Anstatt Katalognamen oder Quellpfade pro Umgebung in deinem Transformationscode fest zu kodieren, gib die Werte vom Ziel ein, sodass derselbe Quellcode überall unverändert läuft. Wie du sie einstellst, hängt von deiner Quellsprache ab. Pipeline-Parameter gelten nur für SQL-Quellcode. Für den Python-Quellcode verwenden Sie das Pipeline-Feld configuration und lesen Sie die Werte mit spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Mehr zur Parametrisierung von Pipeline-Code finden Sie unter Use Parameters with pipelines.

CI/CD einrichten

Da eine konvertierte Pipeline vollständig als Bundle (YAML plus Quelldateien in Git) definiert ist, bedeutet das Einrichten von Continuous Integration und Continuous Delivery (CI/CD) dafür, dass die Bundle-Befehle von einem CI-System wie GitHub Actions oder Azure DevOps ausgeführt werden. Bei jedem Pull Request wird eine gute Baseline ausgeführt:

  1. pytest für Ihre durch Komponententests überprüfbaren Transformationsfunktionen. Siehe Unit-Tests für Pipelines.
  2. databricks bundle validate --target <env> um Konfigurationsfehler zu erkennen.
  3. Optional können Sie ein databricks bundle run in einem Scratch-Ziel verwenden, um Erwartungen anhand von Beispieldaten zu testen.

Der folgende GitHub Actions-Workflow stellt beim Zusammenführen in main in der Stagingumgebung bereit und verwendet dabei den OpenID Connect-Verbund (OIDC) anstelle eines gespeicherten Tokens:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Schützen Sie die Produktionsbereitstellung durch eine manuelle Genehmigung (z. B. durch einen zweiten Auftrag, der eine GitHub-Umgebungsgenehmigung erfordert, oder eine separate Phase in Azure DevOps), sodass eine Person jede Höherstufung explizit genehmigt. Der Produktionsauftrag führt databricks bundle deploy --target prod mithilfe eines Dienstprinzipals aus, der auf den Produktionsarbeitsbereich beschränkt ist. Weitere Informationen finden Sie unter CI/CD auf Azure Databricks.

Problembehandlung

Thema Lösung
Fehler "databricks.yml nicht gefunden" beim Ausführen von bundle generate Derzeit erstellt der bundle generate Befehl die Bundlekonfigurationsdatei (databricks.yml) nicht automatisch. Sie müssen die Datei mit databricks bundle init oder manuell erstellen.
Vorhandene Pipelineeinstellungen stimmen nicht mit den Werten in der generierten YaML-Konfiguration überein. Die Pipeline-ID wird nicht in der YML-Datei der Bundlekonfiguration angezeigt. Wenn Sie andere fehlende Einstellungen bemerken, können Sie sie manuell anwenden.

Tipps für Erfolg

  • Verwenden Sie immer die Versionssteuerung. Wenn Sie keine Git-Ordner von Databricks verwenden, speichern Sie Ihre Projektunterverzeichnisse und Dateien in einem Git oder einem anderen versionsgesteuerten Repository oder Dateisystem.
  • Testen Sie Ihre Pipeline in einer Nicht-Produktionsumgebung (z. B. einer "Entwicklungsumgebung" oder "Testumgebung") vor der Bereitstellung in einer Produktionsumgebung. Es ist einfach, versehentlich eine Fehlkonfiguration einzuführen.

Weitere Ressourcen

Weitere Informationen zur Verwendung von Bündeln zum Definieren und Verwalten der Datenverarbeitung finden Sie unter:

  • Last updated on