Configuration des Declarative Automation Bundles
Cet article décrit la syntaxe des fichiers de configuration de bundle, qui définissent les Bundles d'Automatisation Déclarative (anciennement connus sous le nom de Databricks Asset Bundles). Consultez Que sont les Declarative Automation Bundles ?
Pour créer et travailler avec des bundles, consultez Développer des Declarative Automation Bundles.
Pour la référence de configuration de bundle, consultez la référence de configuration.
databricks.yml
Un bundle doit contenir un (et un seul) fichier de configuration nommé databricks.yml à la racine du dossier de projet du bundle. databricks.yml est le fichier de configuration principal qui définit un bundle, mais il peut référencer d'autres fichiers de configuration, tels que des fichiers de configuration de ressources, dans le mapping include. La configuration du bundle est exprimée en YAML. Pour plus d'informations sur YAML, consultez la spécification YAML officielle.
Le databricks.yml le plus simple définit le nom du bundle, qui est un mappage de niveau supérieur requis, et un déploiement cible.
bundle:
name: my_bundle
targets:
dev:
default: true
Pour plus de détails sur toutes les mappings de haut niveau, consultez la référence de configuration.
La prise en charge de Python pour les Declarative Automation Bundles vous permet de définir des ressources en Python. Voir Configuration de bundle en Python.
Spécification
La spécification YAML suivante fournit des clés de configuration de haut niveau pour les Declarative Automation Bundles. Pour une référence de configuration complète, consultez Référence de configuration et les Ressources Declarative Automation Bundles.
# 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 workspace settings if not otherwise overridden in
# the targets top-level mapping.
workspace:
artifact_path: string
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:
alerts:
<unique-alert-name>:
# alert settings
apps:
<unique-app-name>:
# app settings
catalogs:
<unique-catalog-name>:
# catalog settings
clusters:
<unique-cluster-name>:
# cluster settings
dashboards:
<unique-dashboard-name>:
# dashboard settings
database_catalogs:
<unique-database-catalog-name>:
# database catalog settings
database_instances:
<unique-database-instance-name>:
# database instance settings
experiments:
<unique-experiment-name>:
# experiment settings
jobs:
<unique-job-name>:
# job settings
model_serving_endpoints:
<unique-model-serving-endpoint-name>:
# model_serving_endpoint settings
pipelines:
<unique-pipeline-name>:
# pipeline settings
postgres_branches:
<unique-postgres-branch-name>:
# postgres branch settings
postgres_endpoints:
<unique-postgres-endpoint-name>:
# postgres endpoint settings
postgres_projects:
<unique-postgres-project-name>:
# postgres project settings
quality_monitors:
<unique-quality-monitor-name>:
# quality monitor settings
registered_models:
<unique-registered-model-name>:
# registered model settings
schemas:
<unique-schema-name>:
# schema settings
secret_scopes:
<unique-secret-scope-name>:
# secret scopes settings
sql_warehouses:
<unique-sql-warehouse-name>:
# sql warehouse settings
synced_database_tables:
<unique-synced-database-table-name>:
# synced database table settings
volumes:
<unique-volume-name>:
# volumes settings
# 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:
# artifact build settings for this target
bundle:
# bundle settings for this target
default: boolean
git: Map
mode: string
permissions:
# permissions for this target
presets:
<preset>: <value>
resources:
# resource settings for this target
sync:
# sync settings for this target
variables:
<defined-variable-name>: <non-default-value> # value for this target
workspace:
# workspace settings for this target
run_as:
# run_as settings for this target
Exemples
Cette section contient quelques exemples de base pour vous aider à comprendre comment les bundles fonctionnent et comment structurer la configuration.
Pour des exemples de configuration qui illustrent les fonctionnalités des bundles et les cas d'utilisation courants des bundles, consultez les exemples de configuration de bundles et le repository d'exemples de bundles sur GitHub.
L'exemple de configuration de bundle suivant spécifie un fichier local nommé hello.py qui se trouve dans le même répertoire que le fichier de configuration de bundle databricks.yml. Il exécute ce Notebook en tant que Job en utilisant le cluster distant avec l'ID de cluster spécifié. L'URL du Workspace distant et les identifiants d'authentification du Workspace sont lus à partir du profil de configuration local de l'appelant nommé DEFAULT.
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
L'exemple suivant ajoute une cible nommée prod qui utilise une URL Workspace distante différente et des identifiants d'authentification Workspace, qui sont lus à partir de l'entrée host correspondante du fichier .databrickscfg de l'appelant avec l'URL Workspace spécifiée. Ce Job exécute le même Notebook mais utilise un cluster distant différent avec l'ID de cluster spécifié.
Databricks vous recommande d'utiliser le mappage host au lieu du mappage default chaque fois que possible, car cela rend vos fichiers de configuration de bundle plus portables. La définition du mappage host demande à l'interface CLI Databricks de trouver un profil correspondant dans votre fichier .databrickscfg, puis d'utiliser les champs de ce profil pour déterminer le type d'authentification Databricks à utiliser. Si plusieurs profils avec un champ host correspondant existent, vous devez utiliser l'option --profile sur les commandes de bundle pour spécifier un profil à utiliser.
Veuillez noter que vous n'avez pas besoin de déclarer le mappage notebook_task au sein du mappage prod, car il reviendra à l'utilisation du mappage notebook_task au sein du mappage resources de niveau supérieur, si le mappage notebook_task n'est pas explicitement remplacé au sein du mappage prod.
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
Utilisez les commandes de bundle suivantes pour valider, déployer et exécuter ce job au sein de la cible dev. Pour plus de détails sur le cycle de vie d'un bundle, consultez Développer les Declarative Automation 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
Pour valider, déployer et exécuter ce job dans la cible prod plutôt :
# 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
Pour une meilleure modularisation et une meilleure réutilisation des définitions et des paramètres entre les bundles, divisez votre configuration de bundle en fichiers distincts :
# 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