Konfiguration für Databricks-Ressourcenpaket

In diesem Artikel wird die Syntax für Databricks Asset Bundle-Konfigurationsdateien beschrieben, die Databricks Asset Bundles definieren. Siehe Was sind Databricks Asset Bundles?.

Informationen zum Erstellen und Arbeiten mit Bündeln finden Sie unter Develop Databricks Asset Bundles.

databricks.yml

Ein Bündel muss eine (und nur eine) Konfigurationsdatei enthalten, die im Stammverzeichnis des Bundleprojektordners benannt databricks.yml ist. databricks.yml ist die Hauptkonfigurationsdatei, die ein Bündel definiert, aber sie kann auf andere Konfigurationsdateien wie Ressourcenkonfigurationsdateien in der include Zuordnung verweisen. Die Bundlekonfiguration wird in YAML ausgedrückt. Weitere Informationen zu YAML finden Sie in der offiziellen YAML-Spezifikation.

Der einfachste databricks.yml definiert den Bündelnamen, der sich innerhalb des erforderlichen Mapping-Bundle der obersten Ebene und einer Zielbereitstellung befindet.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Ausführliche Informationen zu allen Zuordnungen auf oberster Ebene finden Sie unter Zuordnungen.

Spezifikation

Die folgende YAML-Spezifikation stellt Konfigurationsschlüssel der obersten Ebene für Databricks Asset Bundles bereit. Eine Konfigurationsreferenz finden Sie unter Konfigurationsreferenz.

# 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
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# These are any scripts that can be run.
scripts:
  <some-unique-script-name>:
    content: string

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex
    lookup: Map
    type: string # The only valid value is "complex" if the variable is a complex variable, otherwise do not define this key.

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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

Dieser Abschnitt enthält einige grundlegende Beispiele, die Ihnen helfen, zu verstehen, wie Bündel funktionieren und wie die Konfiguration strukturiert wird.

Die folgende Beispielbundlekonfiguration gibt eine lokale Datei mit dem Namen hello.py an, die sich im selben Verzeichnis wie die Bundlekonfigurationsdatei databricks.ymlbefindet. Sie führt dieses Notebook als Job aus und verwendet dabei den remote Cluster mit der angegebenen Cluster-ID. Die URL des Remotearbeitsbereichs und die Anmeldeinformationen für die Arbeitsbereichauthentifizierung werden aus dem lokalen Konfigurationsprofil des Anrufers mit dem Namen DEFAULTgelesen.

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

Das folgende Beispiel fügt ein Ziel mit dem Namen prod hinzu, das eine andere remote Arbeitsbereich-URL und Anmeldeinformationen für den Arbeitsbereich verwendet, die aus dem passenden .databrickscfg-Eintrag der Datei host des Aufrufers mit der angegebenen Arbeitsbereich-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

Verwenden Sie die folgenden Bundlebefehle , um diesen Auftrag innerhalb des dev Ziels zu überprüfen, bereitzustellen und auszuführen. Ausführliche Informationen zum Lebenszyklus eines Bundles finden Sie unter Develop Databricks Asset Bundles.

# 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

So können Sie diesen Auftrag stattdessen im prod-Ziel überprüfen, bereitstellen und ausfü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

Für eine bessere Modularisierung und eine bessere Wiederverwendung von Definitionen und Einstellungen in Bündeln, teilen Sie Ihre Bundlekonfiguration in separate Dateien auf:

# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'

# hello-job.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

# 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 werden die Zuordnungen der obersten Ebene der Bundle-Konfiguration beschrieben. Eine Konfigurationsreferenz finden Sie unter Konfigurationsreferenz.

• Bündel
• Ausführen als
• einschließen
• Skripte
• synchronisieren
• artefakte
• variablen
• Arbeitsbereich
• Berechtigungen
• Ressourcen
• Ziele

Bündel

Eine Bündelkonfigurationsdatei darf nur eine Zuordnung auf oberster Ebene bundle enthalten, die die Inhalte des Bundles und die Azure Databricks-Arbeitsbereichseinstellungen zuordnet.

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 bundle-Wert der name-Zuordnung der obersten Ebene kann jedoch auf der Zielebene nicht außer Kraft gesetzt 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 alle an anderer Stelle in der Paketkonfigurationsdatei definierten Cluster verwendet werden soll. Informationen zum Abrufen der ID eines Clusters finden Sie unter Compute-Ressourcen-URL und -ID.

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

compute_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 alle an anderer Stelle in der Paketkonfigurationsdatei definierten Cluster verwendet werden soll.

Einguss

Sie können Git-Versionssteuerungsdetails abrufen und außer Kraft setzen, die Ihrem Bundle zugeordnet sind. Dies ist nützlich für die Verteilung von Bereitstellungsmetadaten, die später zum Identifizieren von Ressourcen verwendet werden können. Sie können z. B. den Repositoryursprung eines Auftrags nachverfolgen, der von CI/CD bereitgestellt wird.

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

• bundle.git.origin_url, der die Ursprungs-URL des Repo 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 für den aktuellen Branch innerhalb des Repos steht. 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}.

Zum Abrufen oder Überschreiben von Git-Einstellungen muss sich Ihr Paket 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 databricks --version Wert nicht innerhalb der Grenzen befindet, die in der Zuordnung des Bundles databricks_cli_version angegeben sind, tritt ein Fehler auf, wenn databricks bundle validate im Bundle ausgeführt wird. Die folgenden Beispiele veranschaulichen die 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

Ausführen als

Die run_as-Einstellung legt fest, welche user_name oder service_principal_name zum Ausführen des Bundles verwendet werden soll. Sie bietet die Möglichkeit, die Identität, die zum Bereitstellen eines Bündelauftrags oder einer Pipeline verwendet wird, von derjenigen zu trennen, die zum Ausführen des Auftrags oder der Pipeline verwendet wird.

Siehe Angeben einer Ausführungsidentität für einen Databricks Asset Bundles-Workflow.

einschließen

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 nicht standardmäßig Konfigurationsdateien innerhalb des Pakets. Sie müssen das include-Array verwenden, um alle Konfigurationsdateien anzugeben, die in das Bundle aufgenommen werden sollen, abgesehen von der Datei databricks.yml selbst.

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

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

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

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

include:
  - 'bundle*.yml'

Skripte

Die scripts Einstellung gibt Skripts an, die mit bundle run ausgeführt werden können. Jedes benannte Skript in der scripts Zuordnung enthält Inhalte mit Befehlen. Beispiel:

scripts:
  my_script:
    content: uv run pytest -m ${bundle.target}

Weitere Informationen finden Sie unter Ausführen von Skripts.

synchronisieren

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

„include“ und „exclude“

Die Zuordnungen include und exclude innerhalb der sync-Zuordnung geben je nach den folgenden Regeln eine Liste von Dateien oder Ordnern an, die in die Paketbereitstellungen einbezogen oder von diesen ausgeschlossen werden sollen:

• Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore Datei im Stammverzeichnis des Bundles kann die include Zuordnung eine Liste von Dateiglobs, Pfad-Globs oder beides, relativ zum Stammverzeichnis des Bundles, enthalten, die explizit einbezogen werden sollen.
• Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore Datei im Stammverzeichnis des Bündels sowie der Liste der Datei- und Pfad-Globs in der include Zuordnung kann die exclude Zuordnung eine Liste von Datei-Globs, Pfad-Globs oder beides enthalten, relativ zum Stamm des Bundles, um explizit auszuschließen.

Alle Pfade zu angegebenen Ordnern und Dateien sind relativ zum Speicherort der Paketkonfigurationsdatei, in der diese Pfade angegeben werden.

Die Syntax für Datei- und Pfadmuster für include und exclude folgt der Standardmustersyntax .gitignore. Weitere Informationen finden Sie unter gitignore-Musterformat.

Beispiel, 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 angegeben 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“.) Dies ist besonders nützlich, wenn Sie über ein einzelnes Repository verfügen, das mehrere Pakete hostet, und Bibliotheken, Codedateien oder Konfigurationen freigeben möchten.

Angegebene Pfade müssen relativ zu Dateien und Verzeichnissen sein, die in dem Ordner verankert sind, in dem die paths-Zuordnung festgelegt ist. Wenn ein oder mehrere Pfadwerte das Verzeichnis bis zu einem Vorgänger des Paketstamms durchlaufen, wird der Stammpfad dynamisch bestimmt, um sicherzustellen, dass die Ordnerstruktur intakt bleibt. Wenn der Paketstammordner 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/
    ...

artefakte

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 wird für Python-Wheel-Builds benötigt. Um vor der Bereitstellung eine Python-Raddatei zu erstellen, legen Sie diese auf whlfest. Um andere Artefakte zu erstellen, muss diese Einstellung nicht angegeben werden.
• path ist ein optionaler Pfad. Pfade sind relativ zum Speicherort der Bundlekonfigurationsdatei. Bei Python-Wheel-Builds ist es der Pfad zur setup.py Datei der Python-Wheel-Datei. Falls path nicht enthalten ist, versucht die Databricks CLI, die Python-Wheel-Datei im Stammverzeichnis setup.py des Bundles zu finden.
• files ist eine optionale Abbildung, die eine untergeordnete source-Abbildung enthält, mit der Sie die erstellten Artefakte spezifizieren können. Pfade sind relativ zum Speicherort der Bundlekonfigurationsdatei.
• build ist ein optionales Set von nicht standardmäßigen Build-Befehlen, 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. Geben Sie mehrere Buildbefehle in separaten Zeilen an.
• dynamic_version ermöglicht es Bundles, die Radversion basierend auf dem Zeitstempel der Wheel-Datei zu aktualisieren. Neuer Code kann dann eingesetzt werden, ohne die Version in setup.py oder pyproject.toml aktualisieren zu müssen. Diese Einstellung ist nur gültig, wenn type auf whl festgelegt ist.

Im folgenden Beispiel werden Tests ausgeführt und ein Rad erstellt. Ein vollständiges Bundle-Lernprogramm, das zum Erstellen eines Rads verwendet artifacts wird, finden Sie unter Erstellen einer Python-Raddatei mit Databricks Asset Bundles.

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

Eine Beispielkonfiguration, die einen JAR erstellt und in den Unity-Katalog hochlädt, finden Sie unter Bundle, das eine JAR-Datei in unity Cataloghochlädt.

variablen

Die Datei mit den Paketeinstellungen kann eine variables-Zuordnung auf oberster Ebene enthalten, in der benutzerdefinierte Variablen definiert sind. Legen Sie zum Abrufen eines ID-Werts für jede Variable eine optionale Beschreibung, einen Standardwert, oder einen Lookup fest, und geben Sie an, ob es sich bei der benutzerdefinierten Variable um einen komplexen Typ handelt. Verwenden Sie dazu das folgende 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>

Um auf eine benutzerdefinierte Variable innerhalb der Paketkonfiguration zu verweisen, verwenden Sie die Ersetzung ${var.<variable_name>}.

Weitere Informationen zu benutzerdefinierten Variablen und Ersetzungen finden Sie unter Ersetzungen und Variablen in Databricks-Ressourcenpaketen.

Arbeitsbereich

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

Root-Pfad

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.

Artefakt_Pfad

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.

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.

Zustandspfad

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 Zuordnungen von Arbeitsbereichen

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 targets-Zuordnung auf oberster Ebene angegeben werden.

• 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 Paketkonfigurationsdateien portierbarer macht. Wenn Sie die host-Zuordnung festlegen, weist dies die Databricks CLI an, ein übereinstimmendes Profil in Ihrer .databrickscfg-Datei zu finden und dann die Felder dieses Profils zu verwenden, um zu bestimmen, welcher Databricks-Authentifizierungstyp genutzt 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 Befehlszeilenoptionen --profile oder -p) 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-M2M-Authentifizierung (Machine-to-Machine, Computer-zu-Computer) wird die client_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariablen DATABRICKS_CLIENT_ID festlegen. Sie können auch ein Konfigurationsprofil mit dem client_id Wert erstellen und dann den Namen des Profils mit der profile Zuordnung angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie die Befehle 'validate', 'deploy', 'run' und 'destroy' für das Bundle mit der Databricks CLI ausführen). Siehe Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth.

  Hinweis

  Sie können keinen Wert für das Azure Databricks-OAuth-Geheimnis in der Paketkonfigurationsdatei angeben. Legen Sie stattdessen die lokale Umgebungsvariable DATABRICKS_CLIENT_SECRET fest. Oder Sie können den client_secret-Wert zu einem Konfigurationsprofil hinzufügen und anschließend den Namen des Profils mit der profile-Zuordnung angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie Befehle zum Überprüfen, Bereitstellen, Ausführen und Zerstören mit der Databricks CLI ausführen).

• Für die Azure CLI-Authentifizierung wird die azure_workspace_resource_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariablen DATABRICKS_AZURE_RESOURCE_ID festlegen. Sie können auch ein Konfigurationsprofil mit dem azure_workspace_resource_id Wert erstellen und dann den Namen des Profils mit der profile Zuordnung angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie die Befehle 'validate', 'deploy', 'run' und 'destroy' für das Bundle mit der Databricks CLI ausführen). Siehe Authentifizieren mit der Azure CLI.

• 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. Sie können auch 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 angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie die Befehle "validate", "deploy", "run" und "destroy" mit dem Databricks CLI ausführen). Siehe Authentifizierung mit Microsoft Entra-Dienstprinzipalen.

  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. Oder Sie können den azure_client_secret-Wert zu einem Konfigurationsprofil hinzufügen und anschließend den Namen des Profils mit der profile-Zuordnung angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie Befehle zum Überprüfen, Bereitstellen, Ausführen und Zerstören mit der Databricks CLI ausführen).

• Für die Authentifizierung mit 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. Sie können auch 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 angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie die Befehle "validate", "deploy", "run" und "destroy" mit dem Databricks CLI ausführen). Siehe Authentifizieren mit 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. Standardwert: PUBLIC. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariablen ARM_ENVIRONMENT festlegen. Oder Sie können den azure_environment-Wert zu einem Konfigurationsprofil hinzufügen und anschließend den Namen des Profils mit der profile-Zuordnung angeben (oder indem Sie die Optionen --profile oder -p verwenden, wenn Sie Befehle zum Überprüfen, Bereitstellen, Ausführen und Zerstören mit der Databricks CLI ausführen).

• 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. Weitere Informationen finden Sie unter Autorisieren des Zugriffs auf Azure Databricks-Ressourcen.

Erlaubnisse

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 Bündelkonfigurationsdatei werden Berechtigungsstufen für einen Benutzer, eine Gruppe und einen Dienstprinzipal definiert, die auf alle im resources Bundle definierten Ressourcen angewendet werden:

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

Ressourcen

Die resources-Zuordnung gibt Informationen zu den Azure Databricks-Ressourcen an, die vom Paket verwendet werden.

Diese resources-Zuordnung kann als Zuordnung auf oberster Ebene oder als untergeordnetes Element eines oder mehrerer Ziele in der targets-Zuordnung auf oberster Ebene angezeigt werden und null oder einen der unterstützten Ressourcentypen enthalten. Jede Ressourcentypzuordnung enthält eine oder mehrere einzelne Ressourcendeklarationen, die jeweils einen eindeutigen Namen haben müssen. Diese einzelnen Ressourcendeklarationen verwenden die Anforderungsnutzlast der Erstellungsoperation des entsprechenden Objekts, ausgedrückt in YAML, um die Ressource zu definieren. Unterstützte 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 Paketkonfigurationsdateien gefunden werden.

Die folgende Beispielkonfiguration definiert eine Auftragsressource:

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

Weitere Informationen zu Ressourcen, die in Bundles unterstützt werden, sowie allgemeine Konfigurationen und Beispiele finden Sie unter Databricks Asset Bundles-Ressourcen und Bundle-Konfigurationsbeispiele.

Ziele

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-Auftragsdetails 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 Zuordnungen workspace, artifacts und resources auf oberster Ebene werden verwendet, wenn sie nicht in einer targets-Zuordnung angegeben werden. Miteinander in Konflikt stehende Einstellungen werden jedoch durch die 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 Aufträge 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 wird. Das zweite Ziel hat den Namen prod und wird nur verwendet, wenn dieses Ziel für Paketbefehle angegeben wird.

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

„mode“ und „presets“

Zur Vereinfachung der Entwicklung und als bewährte CI/CD-Methoden verfügen Databricks-Ressourcenpakete über Bereitstellungsmodi für Ziele, die Standardverhaltensweisen für Vorproduktions- und Produktionsworkflows festlegen. Das Verhalten kann teilweise auch konfiguriert werden. Ausführliche Informationen finden Sie unter Bereitstellungsmodi für Databricks-Ressourcenpakete.

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

Sie können das Verhalten teilweise mithilfe 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 sind, wird das Standardverhalten durch die Voreinstellungen außer Kraft gesetzt. Einstellungen einzelner Ressourcen setzen die Voreinstellungen außer Kraft. Wenn z. B. ein Zeitplan auf UNPAUSED, die Voreinstellung trigger_pause_status aber auf PAUSED festgelegt ist, wird die Pause im Zeitplan beendet.