Konfiguration für Databricks-Ressourcenpakete

  • Artikel

In diesem Artikel wird die Syntax für Konfigurationsdateien für Databricks-Ressourcenpakete beschrieben, die Databricks-Ressourcenpakete definieren. Weitere Informationen finden Sie unter Was sind Databricks-Ressourcenpakete?.

Eine Paketkonfigurationsdatei muss im YAML-Format ausgedrückt werden und mindestens die bundle-Zuordnung der obersten Ebene enthalten. Jedes Paket muss mindestens eine (und nur eine) Paketkonfigurationsdatei mit dem Namen databricks.yml enthalten. Wenn mehrere Paketkonfigurationsdateien vorhanden sind, muss mithilfe der include-Zuordnung durch die databricks.yml-Datei auf diese verwiesen werden.

Weitere Informationen zu YAML finden Sie in der offiziellen YAML-Spezifikation und im Tutorial.

Informationen zum Erstellen und Arbeiten mit Paketkonfigurationsdateien finden Sie in der Entwicklung von Databricks Asset Bundles.

Übersicht

In diesem Abschnitt finden Sie eine visuelle Darstellung des Schemas von Paketkonfigurationsdateien. Weitere Informationen finden Sie unter Zuordnungen.

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

Beispiele

Hinweis

Konfigurationsbeispiele zur Veranschaulichung von Paketfeatures und gängigen Paketanwendungsfällen finden Sie unter Paketkonfigurationsbeispiele und im Paketbeispielrepository auf GitHub.

Die folgende Beispielpaketkonfiguration gibt eine lokale Datei mit dem Namen hello.py an, die sich im selben Verzeichnis befindet wie diese lokale Paketkonfigurationsdatei mit dem Namen databricks.yml. Sie führt dieses Notebook als Auftrag aus, indem der Remotecluster mit der angegebenen Cluster-ID verwendet wird. Die URL des Remotearbeitsbereichs und die Anmeldeinformationen für die Arbeitsbereichsauthentifizierung werden aus dem lokalen Konfigurationsprofil des Aufrufers mit dem Namen DEFAULT gelesen.

Databricks empfiehlt, nach Möglichkeit die host-Zuordnung anstelle der default-Zuordnung zu verwenden, da Ihre Paketkonfigurationsdateien dadurch portierbarer werden. Durch Festlegen der host-Zuordnung wird die Databricks CLI angewiesen, ein übereinstimmende Profil in Ihrer .databrickscfg-Datei zu suchen und dann die Felder dieses Profils zu verwenden, um zu bestimmen, welcher Databricks-Authentifizierungstyp verwendet werden soll. Wenn mehrere Profile mit einem übereinstimmenden host-Feld in Ihrer .databrickscfg-Datei vorhanden sind, müssen Sie profile verwenden, um die Databricks CLI anzuweisen, welches bestimmte Profil verwendet werden soll. Ein Beispiel finden Sie in der prod-Zieldeklaration weiter unten in diesem Abschnitt.

Mit dieser Technik können Sie die Auftragsdefinitionen und -einstellungen innerhalb des resources-Blocks wiederverwenden und überschreiben:

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

Obwohl die folgende Paketkonfigurationsdatei funktionell gleichwertig ist, ist sie nicht modularisiert, was keine gute Wiederverwendung ermöglicht. Außerdem fügt diese Deklaration eine Aufgabe an den Auftrag an, anstatt den vorhandenen Auftrag zu überschreiben:

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

Im folgenden Beispiel wird ein Ziel mit dem Namen prod hinzugefügt, das eine andere URL des Remotearbeitsbereichs und die Authentifizierungsanmeldeinformationen des Arbeitsbereichs verwendet, die aus dem in der .databrickscfg-Datei des Aufrufers übereinstimmenden host-Eintrag mit der angegebenen Arbeitsbereichs-URL gelesen werden. Dieser Auftrag führt dasselbe Notebook aus, verwendet jedoch einen anderen Remotecluster mit der angegebenen Cluster-ID. Beachten Sie, dass Sie die notebook_task-Zuordnung innerhalb der prod-Zuordnung nicht deklarieren müssen, da sie auf die Verwendung der notebook_task-Zuordnung innerhalb der Zuordnung der obersten Ebene resources zurückfällt, wenn die notebook_task-Zuordnung nicht explizit in der prod-Zuordnung überschrieben wird.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Um diesen Auftrag innerhalb des dev-Ziels zu überprüfen, bereitzustellen und auszuführen:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

Um diesen Auftrag stattdessen im prod-Ziel zu überprüfen, bereitzustellen und auszuführen:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

Im Folgenden sehen Sie das vorherige Beispiel, das jedoch in Komponentendateien aufgeteilt wurde, um noch mehr Modularisierung und bessere Wiederverwendung über mehrere Paketkonfigurationsdateien hinweg zu fördern. Mit diesem Verfahren können Sie nicht nur verschiedene Definitionen und Einstellungen wiederverwenden, sondern auch eine dieser Dateien durch andere Dateien austauschen, die völlig unterschiedliche Deklarationen bieten:

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Zuordnungen

In den folgenden Abschnitten wird die Syntax von Paketkonfigurationsdateien anhand der Zuordnung der obersten Ebene beschrieben.

bundle

Eine Paketkonfigurationsdatei darf nur eine bundle-Zuordnung auf oberster Ebene enthalten, die den Inhalten des Pakets und den Azure Databricks-Arbeitsbereichseinstellungen zugeordnet ist.

Diese bundle-Zuordnung muss eine name-Zuordnung enthalten, die einen programmgesteuerten (oder logischen) Namen für das Paket angibt. Im folgenden Beispiel wird ein Paket mit dem programmgesteuerten (oder logischen) Namen hello-bundle deklariert.

bundle:
  name: hello-bundle

Eine bundle-Zuordnung kann auch ein untergeordnetes Element eines oder mehrerer Ziele in der Zuordnung von Zielen der obersten Ebene sein. Jede dieser untergeordneten bundle-Zuordnungen gibt alle nicht standardmäßigen Überschreibungen auf Zielebene an. Der name-Wert der bundle-Zuordnung auf oberster Ebene kann jedoch nicht auf Zielebene überschrieben werden.

cluster_id

Die bundle-Zuordnung kann über eine untergeordnete cluster_id-Zuordnung verfügen. Mit dieser Zuordnung können Sie die ID eines Clusters angeben, der als Überschreibung für an anderer Stelle in der Paketkonfigurationsdatei definierten Cluster verwendet werden soll. Informationen zum Abrufen der ID eines Clusters finden Sie unter Cluster-URL und -ID.

Die cluster_id-Außerkraftsetzung ist für Szenarien nur für die Entwicklung vorgesehen und wird nur für das Ziel unterstützt, auf das die mode-Zuordnung auf development festgelegt ist. Weitere Informationen zur target-Zuordnung finden Sie unter Ziele.

compute_id

Hinweis

Diese Einstellung ist veraltet. Verwenden Sie stattdessen cluster_id.

Die bundle-Zuordnung kann über eine untergeordnete compute_id-Zuordnung verfügen. Mit dieser Zuordnung können Sie die ID eines Clusters angeben, der als Überschreibung für an anderer Stelle in der Paketkonfigurationsdatei definierten Cluster verwendet werden soll.

Git

Sie können Git-Versionsverwaltungsdetails abrufen und überschreiben, die Ihrem Paket zugeordnet sind. Dies ist nützlich, um Ihre bereitgestellten Ressourcen zu kommentieren. Sie können beispielsweise die Ursprungs-URL Ihres Repositorys in die Beschreibung eines von Ihnen bereitgestellten Machine Learning-Modells einschließen.

Wenn Sie einen bundle-Befehl wie validate, deploy oder run ausführen, füllt der bundle-Befehl die Konfigurationsstruktur des Befehls mit den folgenden Standardeinstellungen auf:

  • bundle.git.origin_url, die die Ursprungs-URL des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git config --get remote.origin.url aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.origin_url}.
  • bundle.git.branch, der den aktuellen Branch innerhalb des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git branch --show-current aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.branch}.
  • bundle.git.commit, der den HEAD-Commit innerhalb des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git rev-parse HEAD aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.commit}.

Zum Abrufen oder Überschreiben von Git-Einstellungen muss sich Ihr Bundle in einem Verzeichnis befinden, das einem Git-Repository zugeordnet ist, z. B. einem lokalen Verzeichnis, das durch Ausführen des git clone-Befehls initialisiert wird. Wenn das Verzeichnis nicht einem Git-Repository zugeordnet ist, sind diese Git-Einstellungen leer.

Sie können die Einstellungen origin_url und branch in der git-Zuordnung Ihrer bundle-Zuordnung auf oberster Ebene bei Bedarf wie folgt überschreiben:

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

Die bundle-Zuordnung kann eine databricks_cli_version-Zuordnung enthalten, die die für das Paket erforderliche Databricks CLI-Version einschränkt. Dies kann Probleme verhindern, die durch die Verwendung von Zuordnungen verursacht werden, die in einer bestimmten Version der Databricks CLI nicht unterstützt werden.

Die Databricks CLI-Version folgt der semantischen Versionsverwaltung, und die databricks_cli_version-Zuordnung unterstützt die Angabe von Versionseinschränkungen. Wenn sich der aktuelle Wert von databricks --version nicht innerhalb der Grenzen befindet, die in der databricks_cli_version-Zuordnung des Pakets angegeben sind, tritt ein Fehler auf, wenn databricks bundle validate im Paket ausgeführt wird. Die folgenden Beispiele veranschaulichen allgemeine Syntax zur Versionseinschränkung:

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

variables

Die Bündel-Einstellungsdatei kann eine variables-Zuordnung auf oberster Ebene enthalten, in der benutzerdefinierte Variablen definiert sind. Legen Sie für jede Variable eine optionale Beschreibung, einen Standardwert und die Angabe fest, ob es sich bei der benutzerdefinierten Variable um einen komplexen Typ oder einen Lookup handelt, um einen ID-Wert abzurufen, und zwar in diesem Format:

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

Hinweis

Bei Variablen wird davon ausgegangen, dass es sich um Variablen vom Typ string handelt, es sei denn, type wird auf complex festgelegt. Weitere Informationen finden Sie unter Definieren einer komplexen Variablen.

Um eine benutzerdefinierte Variable innerhalb der Bundle-Konfiguration zu referenzieren, verwenden Sie die Ersetzung ${var.<variable_name>}.

Weitere Informationen zu benutzerdefinierten Variablen und Ersetzungen finden Sie unter Ersetzungen und Variablen in Databricks Asset Bundles.

workspace

Die Paketkonfigurationsdatei darf nur eine workspace-Zuordnung auf oberster Ebene enthalten, um alle nicht standardmäßigen Azure Databricks-Arbeitsbereichseinstellungen anzugeben, die verwendet werden sollen.

Wichtig

Gültige Databricks-Arbeitsbereichspfade beginnen entweder mit /Workspace oder /Volumes. Benutzerdefinierte Arbeitsbereichspfade werden automatisch mit dem Präfix versehen /Workspace. Wenn Sie also eine Ersetzung des Arbeitsbereichspfads in Ihrem benutzerdefinierten Pfad verwenden, z ${workspace.file_path}. B. müssen Sie den Pfad nicht voranstellen /Workspace .

root_path

Diese workspace-Zuordnung kann eine root_path-Zuordnung enthalten, um einen nicht standardmäßigen Stammpfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

workspace:
  root_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

Standardmäßig verwendet die Databricks CLI für root_path den Standardpfad von /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, der Ersetzungen verwendet.

artifact_path

Diese workspace-Zuordnung kann auch eine artifact_path-Zuordnung enthalten, um einen nicht standardmäßigen Artefaktpfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

workspace:
  artifact_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

Standardmäßig verwendet die Databricks CLI für artifact_path den Standardpfad von ${workspace.root}/artifacts, der Ersetzungen verwendet.

Hinweis

Die artifact_path-Zuordnung unterstützt keine DBFS-Pfade (Databricks File System).

file_path

Diese workspace-Zuordnung kann auch eine file_path-Zuordnung enthalten, um einen nicht standardmäßigen Dateipfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

workspace:
  file_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

Standardmäßig verwendet die Databricks CLI für file_path den Standardpfad von ${workspace.root}/files, der Ersetzungen verwendet.

state_path

Die state_path-Zuordnung ist standardmäßig auf den Standardpfad von ${workspace.root}/state und stellt den Pfad innerhalb Ihres Arbeitsbereichs dar, um Terraform-Statusinformationen zu Bereitstellungen zu speichern.

Andere Arbeitsbereichzuordnungen

Die workspace-Zuordnung kann auch die folgenden optionalen Zuordnungen enthalten, um den zu verwendenden Azure Databricks-Authentifizierungsmechanismus anzugeben. Wenn sie innerhalb dieser workspace-Zuordnung nicht angegeben werden, müssen sie in einer workspace-Zuordnung als untergeordnetes Element eines oder mehrerer Ziele in der Zuordnung der Ziele auf oberster Ebene angegeben werden.

Wichtig

Sie müssen Werte für die folgenden workspace-Zuordnungen für die Azure Databricks-Authentifizierung hartcodieren. Zum Beispiel können Sie keine benutzerdefinierten Variablen für die Werte dieser Zuordnungen mithilfe der ${var.*}-Syntax angeben.

  • Die profile-Zuordnung gibt (oder die Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI geben) den Namen eines Konfigurationsprofils an, das mit diesem Arbeitsbereich für die Azure Databricks-Authentifizierung verwendet werden soll. Dieses Konfigurationsprofil wird dem Profil zugeordnet, das Sie beim Einrichten der Databricks CLI erstellt haben.

    Hinweis

    Databricks empfiehlt, die host-Zuordnung (oder die Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) anstelle der profile-Zuordnung zu verwenden, da diese Ihre Bündelkonfigurationsdateien portierbarer macht. Durch Festlegen der host-Zuordnung wird die Databricks CLI angewiesen, ein übereinstimmende Profil in Ihrer .databrickscfg-Datei zu suchen und dann die Felder dieses Profils zu verwenden, um zu bestimmen, welcher Databricks-Authentifizierungstyp verwendet werden soll. Wenn mehrere Profile mit einem übereinstimmenden host-Feld in Ihrer .databrickscfg-Datei vorhanden sind, dann müssen Sie die profile-Zuordnung (oder die --profile- oder -p-Befehlszeilenoptionen) verwenden, um die Databricks-CLI anzuweisen, welches Profil verwendet werden soll. Ein Beispiel finden Sie in der prod-Zieldeklaration in den Beispielen.

  • Die host-Zuordnung gibt die URL für Ihren Azure Databricks-Arbeitsbereich an. Weitere Informationen finden Sie unter Arbeitsbereichsspezifische URL.

  • Für die OAuth-Computer-zu-Computer-Authentifizierung (M2M) wird die client_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable DATABRICKS_CLIENT_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit dem client_id-Wert erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Weitere Informationen finden Sie unter Authentifizierung des Zugriffs bei Azure Databricks mit einem Dienstprinzipal unter Verwendung von OAuth (OAuth M2M).

    Hinweis

    Sie können keinen Wert für das Azure Databricks-OAuth-Geheimnis in der Bündelkonfigurationsdatei angeben. Legen Sie stattdessen die lokale Umgebungsvariable DATABRICKS_CLIENT_SECRET fest. Alternativ können Sie dem Konfigurationsprofil den client_secret-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

  • Für die Azure CLI-Authentifizierung wird die azure_workspace_resource_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable DATABRICKS_AZURE_RESOURCE_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit dem azure_workspace_resource_id-Wert erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Weitere Informationen finden Sie unter Azure CLI-Authentifizierung.

  • Für die Authentifizierung des Azure-Clientgeheimnisses mit Dienstprinzipalen werden die Zuordnungen azure_workspace_resource_id, azure_tenant_id und azure_client_id verwendet. Alternativ können Sie diese Werte in den lokalen Umgebungsvariablen DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID bzw ARM_CLIENT_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit den Werten azure_workspace_resource_id, azure_tenant_id und azure_client_id erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Weitere Informationen finden Sie unter Microsoft Entra ID-Dienstprinzipalauthentifizierung.

    Hinweis

    Sie können keinen Wert für den geheimen Azure-Clientschlüssel in der Paketkonfigurationsdatei angeben. Legen Sie stattdessen die lokale Umgebungsvariable ARM_CLIENT_SECRET fest. Alternativ können Sie dem Konfigurationsprofil den azure_client_secret-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

  • Für die kennwortlose Authentifizierung der von Azure verwalteten Identitäten werden die Zuordnungen azure_use_msi, azure_client_id und azure_workspace_resource_id verwendet. Alternativ können Sie diese Werte in den lokalen Umgebungsvariablen ARM_USE_MSI, ARM_CLIENT_ID bzw DATABRICKS_AZURE_RESOURCE_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit den Werten azure_use_msi, azure_client_id und azure_workspace_resource_id erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Siehe Authentifizierung von von Azure verwalteten Identitäten.

  • Die azure_environment-Zuordnung gibt den Azure-Umgebungstyp (z. B. Öffentlich, UsGov, China und Deutschland) für eine bestimmte Gruppe von API-Endpunkten an. Der Standardwert ist PUBLIC. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable ARM_ENVIRONMENT festlegen. Alternativ können Sie dem Konfigurationsprofil den azure_environment-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

  • Die azure_login_app_id-Zuordnung ist nicht betriebsbereit und für die interne Verwendung reserviert.

  • Die auth_type-Zuordnung gibt den zu verwendenden Azure Databricks-Authentifizierungstyp an, insbesondere in Fällen, in denen die Databricks CLI einen unerwarteten Authentifizierungstyp ableiten soll. Siehe Authentifizierung des Zugriffs auf Azure Databricks-Ressourcen.

Berechtigungen

Die permissions-Zuordnung auf oberster Ebene gibt eine oder mehrere Berechtigungsstufen an, die auf alle im Paket definierten Ressourcen angewendet werden sollen. Wenn Sie Berechtigungen auf eine bestimmte Ressource anwenden möchten, lesen Sie Definieren von Berechtigungen für eine bestimmte Ressource.

Zulässige Berechtigungsstufen auf oberster Ebene sind CAN_VIEW, CAN_MANAGE und CAN_RUN.

Im folgenden Beispiel in einer Paketkonfigurationsdatei werden Berechtigungsstufen für einen Benutzer/eine Benutzerin, eine Gruppe und einen Dienstprinzipal definiert. Diese Stufen werden auf alle Aufträge, Pipelines, Experimente und Modelle angewendet, die in resources im Paket definiert sind:

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

artifacts

Die artifacts-Zuordnung auf oberster Ebene gibt ein oder mehrere Artefakte an, die automatisch während Paketbereitstellungen erstellt werden und später in Paketausführungen verwendet werden können. Jedes untergeordnete Artefakt unterstützt die folgenden Zuordnungen:

  • type ist erforderlich. Um vor der Bereitstellung eine Python-Wheel-Datei zu erstellen, muss diese Zuordnung auf whl festgelegt werden.
  • path ist ein optionaler relativer Pfad vom Speicherort der Paketkonfigurationsdatei zum Speicherort der setup.py-Datei für die Python-Wheel-Datei. Wenn path nicht enthalten ist, versucht die Databricks CLI, die setup.py-Datei der Python-Wheel-Datei im Stammverzeichnis des Pakets zu finden.
  • files ist eine optionale Zuordnung, die eine untergeordnete source-Zuordnung enthält, mit der Sie nicht standardmäßige Speicherorte für komplexe Buildanweisungen angeben können. Speicherorte werden als relative Pfade vom Speicherort der Paketkonfigurationsdatei aus angegeben.
  • build ist ein optionaler Satz nicht standardmäßiger Buildbefehle, die Sie vor der Bereitstellung lokal ausführen möchten. Bei Python-Wheel-Builds geht die Databricks CLI davon aus, dass sie eine lokale Installation des Python-wheel-Pakets zum Ausführen von Builds finden kann, und führt den Befehl python setup.py bdist_wheel standardmäßig während jeder Paketbereitstellung aus. Um mehrere Buildbefehle anzugeben, trennen Sie jeden Befehl durch doppelte kaufmännische Und-Zeichen (&&).

Weitere Informationen, einschließlich eines Beispielpakets, das artifacts verwendet, finden Sie unter Entwickeln einer Python-Wheel-Datei mit Databricks-Ressourcenpaketen.

Tipp

Sie können die Einstellungen für Artefakte in Paketen definieren, kombinieren und überschreiben, indem Sie die unter Dynamisches Definieren von Artefakteinstellungen in Databricks-Ressourcenpaketen beschriebenen Techniken verwenden.

include

Das include-Array gibt eine Liste der Pfad-Globs an, die Konfigurationsdateien enthalten, die in das Paket eingeschlossen werden sollen. Diese Pfadglobs sind relativ zum Speicherort der Paketkonfigurationsdatei, in der die Pfadglobs angegeben sind.

Die Databricks-CLI enthält keine Konfigurationsdateien standardmäßig innerhalb des Bündels. Sie müssen das include-Array verwenden, um alle Konfigurationsdateien anzugeben, die nicht in die databricks.yml-Datei selbst eingeschlossen werden sollen.

Dieses include-Array kann nur als Zuordnung auf oberster Ebene erscheinen.

Die folgende Beispielkonfiguration enthält drei Konfigurationsdateien. Diese Dateien befinden sich im gleichen Ordner wie die Paketkonfigurationsdatei:

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

Die folgende Beispielkonfiguration enthält alle Dateien, deren Dateinamen mit bundle beginnen und mit .yml enden. Diese Dateien befinden sich im gleichen Ordner wie die Paketkonfigurationsdatei:

include:
  - "bundle*.yml"

resources

Das resources-Mapping gibt Informationen zu den Azure Databricks-Ressourcen an, die vom Bundle verwendet werden.

Dieses resources-Mapping kann als Mapping auf oberster Ebene oder als untergeordnetes Element eines oder mehrerer Ziele im Mapping von Zielen auf oberster Ebene angezeigt und null oder einen der unterstützten Ressourcentypen enthalten. Jedes Ressourcentypmapping enthält eine oder mehrere einzelne Ressourcendeklarationen, die jeweils einen eindeutigen Namen haben müssen. Diese einzelnen Ressourcendeklarationen verwenden die Anforderungsnutzlast des Erstellungsvorgangs für das entsprechende Objekt, ausgedrückt in YAML, um die Ressource zu definieren. Die unterstützten Eigenschaften für eine Ressource sind die unterstützten Felder des entsprechenden Objekts.

Die Anforderungsnutzlasten des Erstellungsvorgangs sind in der Referenz zur Databricks-REST-API dokumentiert. Der databricks bundle schema-Befehl gibt alle unterstützten Objektschemas zurück. Darüber hinaus gibt der databricks bundle validate-Befehl Warnungen zurück, wenn unbekannte Ressourceneigenschaften in Bundlekonfigurationsdateien gefunden werden.

In der folgenden Tabelle sind unterstützte Ressourcentypen für Bundles und Links zu Dokumentationen zu den entsprechenden Nutzlasten aufgeführt.

Ressourcentyp Ressourcenmappings
cluster Clusterzuordnungen: POST /api/2.1/clusters/create
Dashboard Dashboardzuordnungen: POST /api/2.0/preview/sql/dashboards
experiment Experimentmappings: POST /api/2.0/mlflow/experiments/create
Auftrag Auftragsmappings: POST /api/2.1/jobs/create

Weitere Informationen finden Sie unter Auftragsaufgabentypen und Außerkraftsetzung neuer Auftragsclustereinstellungen.
Rohrleitung Pipelinemappings: POST /api/2.0/pipelines
model Modellmappings: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint Endpunktmapping der Modellbereitstellung: POST /api/2.0/serving-endpoints
registered_model (Unity Catalog) Unity-Katalogmodellzuordnungen: POST /api/2.1/unity-catalog/models
schema (Unity Catalog) Schemazuordnungen des Unity-Katalogs: POST /api/2.1/unity-catalog/schemas

Alle Pfade zu Ordnern und Dateien, auf die von Ressourcendeklarationen verwiesen wird, sind relativ zum Speicherort der Bundlekonfigurationsdatei, in der diese Pfade angegeben sind.

cluster

Mit der Clusterressource können Sie allzweckbezogene Cluster erstellen. Das folgende Beispiel erstellt einen Cluster mit dem Namen my_cluster und legt diesen als den Cluster fest, der für die Ausführung des Notebooks in my_job verwendet wird:

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

Dashboard

Mit der Dashboardressource können Sie AI/BI-Dashboards in einem Bündel verwalten. Informationen zu AI/BI-Dashboards finden Sie unter Dashboards.

Das folgende Beispiel enthält und stellt das Beispiel-NYC Taxi Trip Analysis-Dashboard im Databricks-Arbeitsbereich bereit.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

Wenn Sie die Benutzeroberfläche verwenden, um das Dashboard zu ändern, werden Änderungen, die über die Benutzeroberfläche vorgenommen werden, nicht auf die Dashboard-JSON-Datei im lokalen Bundle angewendet, es sei denn, Sie aktualisieren es explizit mit bundle generate. Sie können die --watch Option verwenden, um Änderungen am Dashboard kontinuierlich abzurufen und abzurufen. Siehe Generieren einer Bündelkonfigurationsdatei.

Wenn Sie außerdem versuchen, ein Bundle bereitzustellen, das eine DASHBOARD-JSON-Datei enthält, die sich von der im Remotearbeitsbereich unterscheidet, tritt ein Fehler auf. Um die Bereitstellung zu erzwingen und das Dashboard im Remotearbeitsbereich mit dem lokalen zu überschreiben, verwenden Sie die --force Option. Siehe Bereitstellen eines Bündels.

Auftrag

Im folgenden Beispiel wird ein Auftrag mit dem Ressourcenschlüssel hello-job deklariert:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

pipeline

Im folgenden Beispiel wird eine Pipeline mit dem Ressourcenschlüssel hello-pipeline deklariert:

resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

schema

Mit dem Schemaressourcentyp können Sie Unity-Katalogschemas für Tabellen und andere Ressourcen in Ihren Workflows und Pipelines definieren, die als Teil eines Bündels erstellt wurden. Ein Schema, das sich von anderen Ressourcentypen unterscheidet, weist die folgenden Einschränkungen auf:

  • Der Besitzer einer Schemaressource ist immer der Bereitstellungsbenutzer und kann nicht geändert werden. Wenn run_as im Bündel angegeben ist, wird dies von Vorgängen im Schema ignoriert.
  • Für die schema-Ressource sind nur Felder verfügbar, die der entsprechenden Schemaobjekterstellungs-API werden. Beispielsweise ist enable_predictive_optimization nur in der Update-API verfügbar und wird daher nicht unterstützt.

Im folgenden Beispiel wird eine Pipeline mit dem Ressourcenschlüssel my_pipeline deklariert, die ein Unity Catalog-Schema mit dem Schlüssel my_schema als Ziel erstellt:

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

Eine Zuordnung von Berechtigungen auf oberster Ebene wird von Databricks Asset Bundles nicht unterstützt. Wenn Sie also Berechtigungen für ein Schema festlegen möchten, definieren Sie die Berechtigungen für das Schema innerhalb der schemas Zuordnung:

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

sync

Mit der sync-Zuordnung können Sie konfigurieren, welche Dateien Teil Ihrer Paketbereitstellungen sind.

„include“ und „exclude“

Die include und exclude-Zuordnung innerhalb der sync-Zuordnung gibt eine Liste von Dateien oder Ordnern an, die abhängig von den folgenden Regeln in Paketbereitstellungen eingeschlossen oder davon ausgeschlossen werden sollen:

  • Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore-Datei im Stammverzeichnis des Pakets kann die include-Zuordnung eine Liste von Datei-Globs, Pfad-Globs oder beidem enthalten, relativ zum Stamm des Pakets, die explizit eingeschlossen werden sollen.
  • Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore-Datei im Stammverzeichnis des Pakets sowie der Liste der Datei- und Pfad-Globs in der include-Zuordnung kann die exclude-Zuordnung eine Liste von Datei-Globs, Pfad-Globs oder beidem enthalten, relativ zum Stamm des Pakets, die explizit ausgeschlossen werden sollen.

Alle Pfade zu angegebenen Dateien und Ordnern beziehen sich auf den Speicherort der Paketkonfigurationsdatei, in der sie angegeben werden.

Die Syntax für include Datei exclude- und Pfadmuster folgt der Standardmustersyntax .gitignore. Siehe gitignore Musterformat.

Beispielsweise, wenn die folgende .gitignore-Datei die folgenden Einträge enthält:

.databricks
my_package/dist

Außerdem enthält die Paketkonfigurationsdatei die folgende include-Zuordnung:

sync:
  include:
    - my_package/dist/*.whl

Dann sind alle Dateien im my_package/dist-Ordner mit der Dateierweiterung *.whl enthalten. Alle anderen Dateien im my_package/dist-Ordner sind nicht enthalten.

Wenn allerdings die Paketkonfigurationsdatei auch die folgende exclude-Zuordnung enthält:

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

Dann sind alle Dateien im my_package/dist-Ordner mit der Dateierweiterung *.whl enthalten, mit Ausnahme der Datei namens delete-me.whl. Alle anderen Dateien im my_package/dist-Ordner sind ebenfalls nicht enthalten.

Die sync-Zuordnung kann auch in der targets-Zuordnung für ein bestimmtes Ziel deklariert werden. Alle in einem Ziel deklarierten sync-Zuordnungen werden mit sync-Zuordnungsdeklarationen der obersten Ebene zusammengeführt. Wenn Sie beispielsweise mit dem vorherigen Beispiel fortfahren, wird die folgende include-Zuordnung auf der targets-Ebene mit der include-Zuordnung in der sync-Zuordnung auf oberster Ebene zusammengeführt:

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

Pfade

Die sync-Zuordnung kann eine paths-Zuordnung enthalten, die lokale Pfade zum Synchronisieren mit dem Arbeitsbereich angibt. Die paths-Zuordnung ermöglicht Ihnen das paketübergreifende Freigeben gemeinsamer Dateien und kann zum Synchronisieren von Dateien außerhalb des Paketstamms verwendet werden. (Der Paketstamm ist der Speicherort der Datei databricks.yml.) Das ist besonders hilfreich, wenn Sie ein einzelnes Repository haben, das mehrere Pakete hostet, und Bibliotheken, Codedateien oder Konfigurationen freigeben möchten.

Die angegebenen Pfade müssen sich auf die Dateien und Verzeichnisse beziehen, die in dem Ordner verankert sind, in dem die paths-Zuordnung festgelegt ist. Wenn ein oder mehrere Pfadwerte im Verzeichnis zu einem Vorgänger des Paketstamms aufsteigen, wird der Stammpfad dynamisch bestimmt, um sicherzustellen, dass die Ordnerstruktur intakt bleibt. Wenn der Stammordner des Pakets z. B. my_bundle heißt, synchronisiert diese Konfiguration in databricks.yml den Ordner common auf einer Ebene oberhalb des Paketstamms und den Paketstamm selbst:

sync:
  paths:
    - ../common
    - .

Eine Bereitstellung dieses Pakets ergibt die folgende Ordnerstruktur im Arbeitsbereich:

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

targets

Die targets-Zuordnung gibt einen oder mehrere Kontexte an, in denen Azure Databricks-Workflows ausgeführt werden sollen. Jedes Ziel ist eine eindeutige Sammlung von Artefakten, Azure Databricks-Arbeitsbereichseinstellungen und Azure Databricks-Auftrags- oder Pipelinedetails.

Die targets-Zuordnung besteht aus mindestens einer Zielzuordnung, die jeweils über einen eindeutigen programmgesteuerten (oder logischen) Namen verfügen muss.

Diese targets-Zuordnung ist optional, wird aber dringend empfohlen. Wenn sie angegeben ist, kann sie nur als Zuordnung auf oberster Ebene angezeigt werden.

Die Einstellungen in den Arbeitsbereich-, Artefakt- und Ressourcen-Zuordnungen auf oberster Ebene werden verwendet, wenn sie nicht in einer targets-Zuordnung angegeben sind. Widersprüchliche Einstellungen werden aber von den Einstellungen innerhalb eines Ziels außer Kraft gesetzt.

Ein Ziel kann auch die Werte aller Variablen der obersten Ebene überschreiben.

default

Legen Sie zum Angeben eines Standardwerts für das Ziel für Paketbefehle die default-Zuordnung auf true fest. Dieses Ziel mit dem Namen dev ist beispielsweise das Standardziel:

targets:
  dev:
    default: true

Wenn kein Standardziel konfiguriert ist oder wenn Sie Jobs oder Pipelines innerhalb eines bestimmten Ziels überprüfen, bereitstellen und ausführen möchten, verwenden Sie die Option -t der Paketbefehle.

Die folgenden Befehle dienen zum Überprüfen, Bereitstellen und Ausführen von my_job innerhalb der Ziele dev und prod:

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

Im folgenden Beispiel werden zwei Ziele deklariert. Das erste Ziel hat den Namen dev und ist das Standardziel, das verwendet wird, wenn für Paketbefehle kein Ziel angegeben ist. Das zweite Ziel hat den Namen prod und wird nur dann verwendet, wenn dieses Ziel für Paketbefehle angegeben ist.

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

„mode“ und „presets“

Für eine einfache Entwicklung und als bewährte Methoden für CI/CD verfügen Databricks-Ressourcenpakete über Bereitstellungsmodi für Ziele, die für Vorproduktions- und Produktionsworkflows ein Standardverhalten festlegen. Das Verhalten kann teilweise auch konfiguriert werden. Weitere Informationen finden Sie unter Bereitstellungsmodi für Databricks-Ressourcenpakete.

Tipp

Zum Festlegen von Ausführungsidentitäten für Pakete können Sie für jedes Ziel run_as angeben, wie in Angeben einer Ausführungsidentität für einen Databricks-Ressourcenpaketworkflow beschrieben.

Um anzugeben, dass ein Ziel als Entwicklungsziel behandelt wird, fügen Sie die mode-Zuordnung hinzu, die auf development festgelegt ist. Um anzugeben, dass ein Ziel als Produktionsziel behandelt wird, fügen Sie die mode-Zuordnung hinzu, die auf production festgelegt ist. Beispielsweise wird dieses Ziel mit dem Namen prod als Produktionsziel behandelt:

targets:
  prod:
    mode: production

Teilweise können Sie das Verhalten anhand der presets-Zuordnung anpassen. Eine Liste der verfügbaren Voreinstellungen finden Sie unter Benutzerdefinierte Voreinstellungen. Das folgende Beispiel zeigt ein angepasstes Produktionsziel, bei dem alle Produktionsressourcen mit Präfixen und Tags versehen werden:

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

Wenn sowohl mode als auch presets festgelegt ist, wird das Standardverhalten von den Voreinstellungen außer Kraft gesetzt. Einstellungen einzelner Ressourcen setzen die Voreinstellungen außer Kraft. Wenn z. B. ein Zeitplan auf UNPAUSED, die trigger_pause_status-Voreinstellung aber auf PAUSED festgelegt ist, wird die Pause im Zeitplan beendet.