Freigeben über

Databricks-Ressourcenbundlevorlagen

  • Artikel

In diesem Artikel wird die Syntax für Vorlagen für Databricks-Ressourcenbundles beschrieben, die mit der Databricks CLI-Version 0.205 und höher funktionieren. Pakete ermöglichen die programmgesteuerte Verwaltung von Azure Databricks-Workflows. Weitere Informationen finden Sie unter Was sind Databricks-Ressourcenpakete?

Bündelvorlagen ermöglichen es Benutzern, Bündel auf konsistente, wiederholbare Weise zu erstellen, indem Ordnerstrukturen, Buildschritte und Aufgaben, Tests und andere DevOps-IaC-Attribute (Infrastructure-as-Code) erstellt werden, die in der Entwicklungsumgebungsbereitstellungspipeline immer gleich sind.

Wenn Sie beispielsweise Databricks-Aufträge, die benutzerdefinierte Pakete mit einem zeitaufwendigen Kompilierungsschritt bei der Installation erfordern, routinemäßig ausführen, können Sie ihre Entwicklungsschleife beschleunigen, indem Sie eine Bundlevorlage erstellen, die benutzerdefinierte Containerumgebungen unterstützt.

Bündelvorlagen definieren die Verzeichnisstruktur des Bündels, das erstellt wird, und sie enthalten eine databricks.yml.tmpl-Konfigurationsdateivorlage sowie eine databricks_template_schema.json-Datei mit Benutzeraufforderungsvariablen.

Erstellen eines Pakets basierend auf einer Vorlage

In diesem Abschnitt wird beschrieben, wie Sie eine Bündelvorlage verwenden, entweder eine Azure Databricks-Standardbundlevorlage oder eine benutzerdefinierte Bündelvorlage.

Verwenden einer standardmäßigen Paketvorlage

Wenn Sie eine Standardpaketvorlage für Azure Databricks zum Erstellen Ihres Bündels verwenden möchten, verwenden Sie den Befehl Databricks CLIbundle init, der den Namen der zu verwendenden Standardvorlage angibt. Mit dem folgenden Befehl wird beispielsweise ein Bündel mithilfe der standardmäßigen Python-Bündelvorlage erstellt:

databricks bundle init default-python

Wenn Sie keine Standardvorlage angeben, stellt der bundle init-Befehl die Gruppe der verfügbaren Vorlagen dar, aus denen Sie auswählen können.

Azure Databricks stellt die folgenden Standardbundlevorlagen bereit:

Template Beschreibung
default-python Eine Vorlage für die Verwendung von Python mit Databricks. Diese Vorlage erstellt ein Bündel mit einem Auftrag und einer Delta Live Tables-Pipeline. Weitere Informationen unter default-python.
default-sql Eine Vorlage für die Verwendung von SQL mit Databricks. Diese Vorlage enthält eine Konfigurationsdatei, die einen Auftrag definiert, der SQL-Abfragen in einem SQL Warehouse ausführt. Weitere Informationen unter default-sql.
dbt-sql Eine Vorlage, die DBT-Core für lokale Entwicklung und Bundles für die Bereitstellung nutzt. Diese Vorlage enthält die Konfiguration, die einen Auftrag mit einer DBT-Aufgabe definiert, sowie eine Konfigurationsdatei, die DBT-Profile für bereitgestellte DBT-Aufträge definiert. Weitere Informationen unter dbt-sql.
mlops-stacks Eine erweiterte Vollstapelvorlage zum Starten neuer MLOps Stacks-Projekte. Weitere Informationen unter mlops-stacks und Databricks Asset Bundles for MLOps Stacks.

Verwenden einer benutzerdefinierten Bündelvorlage

Um eine andere Bündelvorlage als die Standardbündelvorlagen von Azure Databricks zu verwenden, übergeben Sie den lokalen Pfad oder die Remote-URL der Vorlage an den Databricks CLIbundle init-Befehl.

Der folgende Befehl verwendet beispielsweise die dab-container-template-Vorlage, die im Tutorial für benutzerdefinierte Bündelvorlagen erstellt wurde:

   databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Erstellen einer Paketvorlage

Paketvorlagen verwenden die Go-Paketvorlagensyntax. Weitere Informationen finden Sie in der Dokumentation zu Go-Paketvorlagen.

Ein Bündelvorlagenprojekt muss mindestens folgendes aufweisen:

  • Eine databricks_template_schema.json-Datei im Projektstamm, die eine Benutzeraufforderungsvariable für den Projektnamen des Bündels definiert.
  • Eine databricks.yml.tmpl-Datei in einem template-Ordner, der die Konfiguration für alle Bündel definiert, die mit der Vorlage erstellt wurden. Wenn Ihre databricks.yml.tmpl-Datei auf weitere *.yml.tmpl-Konfigurationsvorlagen verweist, geben Sie den Speicherort dieser Vorlagen in der include-Zuordnung an.

Sie können optional Unterordner und Dateien zu dem template-Ordner hinzufügen, den Sie in Bündeln spiegeln möchten, die von der Vorlage erstellt wurden.

Definieren von Benutzeraufforderungsvariablen

Der erste Schritt beim Erstellen einer einfachen Bündelvorlage besteht darin, einen Vorlagenprojektordner und eine im Projektstamm benannte databricks_template_schema.json-Datei zu erstellen. Diese Datei enthält die Variablen, für die Benutzer Eingabewerte bereitstellen, wenn sie die Vorlage zum Erstellen eines Bündels mit bundle init verwenden. Dieses Dateiformat folgt der JSON Schema Specification.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Fügen Sie der databricks_template_schema.json-Datei den folgenden Code hinzu und speichern Sie sie:

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

In dieser Datei gilt Folgendes:

  • project_name ist der einzige Eingabevariablennamen.
  • default ist ein optionaler Standardwert, wenn ein Wert nicht vom Benutzer mit --config-file als Teil des Befehls bundle init bereitgestellt oder vom Benutzer an der Eingabeaufforderung überschrieben wird.
  • description ist die Benutzereingabeaufforderung für die zugehörige Eingabevariable, wenn kein Wert vom Benutzer mit --config-file als Teil des bundle init-Befehls bereitgestellt wird.
  • order ist eine optionale Reihenfolge, in der jede Benutzeraufforderung angezeigt wird, wenn kein Wert vom Benutzer mit --config-file als Teil des bundle init-Befehls bereitgestellt wird. Wenn order nicht angegeben wird, werden Benutzeraufforderungen in der Reihenfolge angezeigt, in der sie im Schema aufgeführt sind.
  • success_message ist eine optionale Meldung, die bei erfolgreicher Projekterstellung angezeigt wird.

Erstellen der Ordnerstruktur

Erstellen Sie als Nächstes den erforderlichen template-Ordner und erstellen Sie die Ordnerstruktur darin. Diese Struktur wird von Bündeln gespiegelt, die mit dieser Vorlage erstellt wurden. Fügen Sie außerdem alle Dateien ein, die Sie in diese Ordner aufnehmen möchten. Diese einfache Bündelvorlage speichert Dateien in einem src-Ordner und enthält ein einfaches Notebook.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Fügen Sie der simple_notebook.ipynb-Datei folgenden Code hinzu:

print("Hello World!")

Auffüllen von Konfigurationsvorlagendateien

Erstellen Sie nun die erforderliche databricks.yml.tmpl-Datei im template-Ordner:

touch basic-bundle-template/template/databricks.yml.tmpl

Füllen Sie diese Datei mit der basisbasierten Konfigurationsvorlage YAML auf. Diese Konfigurationsvorlage richtet den Bündelnamen, einen Auftrag mithilfe der angegebenen Notebook-Datei und zwei Zielumgebungen für Bündel ein, die mit dieser Vorlage erstellt wurden. Sie verwendet auch Bündelersetzungen, die dringend empfohlen werden. Weitere Informationen unter Bündelersetzungen.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

Testen der Bündelvorlage

Testen Sie schließlich Ihre Vorlage. Erstellen Sie einen neuen Projektordner für Bündel, und verwenden Sie dann die Databricks CLI, um ein neues Bündel mithilfe der Vorlage zu initialisieren:

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

Geben Sie für die Eingabeaufforderung What is your bundle project name?my_test_bundle ein.

Sobald das Testbündel erstellt wurde, wird die Erfolgsmeldung aus der Schemadatei ausgegeben. Wenn Sie den Inhalt des my-test-bundle-Ordners untersuchen, sollte Folgendes angezeigt werden:

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

Und die databricks.yml-Datei ist jetzt angepasst:

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

Freigeben der Vorlage

Wenn Sie diese Paketvorlage für andere Personen freigeben möchten, können Sie sie in der Versionskontrolle bei jedem Anbieter speichern, den Git unterstützt und auf den Ihre Benutzer*innen Zugriff haben. Um den Befehl bundle init mit einer Git-URL auszuführen, stellen Sie sicher, dass sich die Datei databricks_template_schema.json in einem Stammspeicherort relativ zu dieser Git-URL befindet.

Tipp

Sie können die databricks_template_schema.json-Datei in einem anderen Ordner relativ zum Stamm des Pakets ablegen. Dann können Sie die Option --template-dir des Befehls bundle init verwenden, um auf den Ordner zu verweisen, der die Datei databricks_template_schema.json enthält.

Nächste Schritte