Configuration de pack de ressources Databricks

Cet article décrit la syntaxe des fichiers de configuration Databricks Asset Bundle, qui définissent les bundles de ressources Databricks. Consultez Que sont les packs de ressources Databricks ?.

Pour créer et utiliser des bundles, consultez Développer des bundles de ressources Databricks.

databricks.yml

Un bundle doit contenir un fichier de configuration (et un seul) nommé databricks.yml à la racine du dossier du projet groupé. 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 les fichiers de configuration de ressources, dans le include mappage. La configuration de bundle est exprimée dans YAML. Pour plus d’informations sur YAML, consultez la spécification YAML officielle.

Le plus simple databricks.yml définit le nom du paquet, qui se trouve dans le mappage de niveau supérieur requis, et un déploiement cible.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Pour plus d’informations sur tous les mappages de niveau supérieur, consultez Mappages.

Caractéristique

La spécification YAML suivante fournit des clés de configuration de niveau supérieur pour les bundles de ressources Databricks. Pour les références de configuration, consultez Référence de configuration.

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

Exemples

Cette section contient quelques exemples de base pour vous aider à comprendre le fonctionnement des bundles et la structure de la configuration.

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 databricks.ymlde configuration de bundle. Il exécute ce notebook en tant que travail à l’aide du cluster distant avec l’ID de cluster spécifié. L’URL de l’espace de travail distant et les informations d’identification d’authentification de l’espace de travail sont lues à 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 portant le nom prod qui utilise une autre URL d’espace de travail distante et des informations d’identification d’authentification de l’espace de travail, qui sont lues à partir de l’entrée correspondante .databrickscfg du fichier de host l’appelant avec l’URL de l’espace de travail spécifiée. Ce travail exécute le même notebook, mais utilise un cluster distant différent avec l’ID de cluster spécifié.

Il convient de noter que vous n’avez pas besoin de déclarer le mappage notebook_task dans le mappage prod, car il revient à utiliser le mappage notebook_task dans le mappage resources de niveau supérieur, si le mappage notebook_task n’est pas explicitement remplacé dans le 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 groupées suivantes pour valider, déployer et exécuter ce travail dans la dev cible. Pour plus d’informations sur le cycle de vie d’un bundle, consultez Développer des bundles de ressources Databricks.

# 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 travail dans la cible prod à la place :

# 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 plus grande modularisation et une meilleure réutilisation des définitions et des paramètres entre les offres groupées, fractionnez 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

Mappages

Les sections suivantes décrivent les mappages principaux de configuration de l'ensemble. Pour les références de configuration, consultez Référence de configuration.

• pack
• run_as
• inclure
• Scripts
• sync
• Artefacts
• variables
• Espace de travail
• autorisations
• ressources
• targets

pack

Un fichier de configuration groupé ne doit contenir qu’un seul mappage de niveau bundle supérieur qui associe le contenu de l’offre groupée et les paramètres d’espace de travail Azure Databricks.

Ce mappage bundle doit contenir un mappage name qui spécifie un nom programmatique (ou logique) pour le pack. L’exemple suivant déclare un pack avec le nom programmatique (ou logique) hello-bundle.

bundle:
  name: hello-bundle

Un mappage bundle peut également être un enfant d’une ou plusieurs cibles dans le mappage de cibles de niveau supérieur. Chacun de ces mappages bundle enfants spécifie les remplacements autres que ceux par défaut au niveau cible. Toutefois, la valeur bundle du mappage name de niveau supérieur ne peut pas être remplacée au niveau cible.

cluster_id

Le mappage bundle peut avoir un mappage enfant cluster_id. Ce mappage vous permet de spécifier l’ID d’un cluster à utiliser comme remplacement pour les clusters définis ailleurs dans le fichier de configuration du pack. Pour plus d’informations sur la récupération de l’ID d’un cluster, consultez l’URL et l’ID des ressources de calcul.

Le remplacement cluster_id est destiné aux scénarios de développement uniquement et n’est pris en charge que pour la cible dont le mappage mode est défini sur development. Pour plus d’informations sur le mappage target, consultez les cibles.

compute_id

Le mappage bundle peut avoir un mappage enfant compute_id. Ce mappage vous permet de spécifier l’ID d’un cluster à utiliser comme remplacement pour les clusters définis ailleurs dans le fichier de configuration du pack.

Git

Vous pouvez récupérer et remplacer les détails du contrôle de version Git associés à votre offre groupée, ce qui est utile pour propager les métadonnées de déploiement qui peuvent être utilisées ultérieurement pour identifier les ressources. Par exemple, vous pouvez retracer l'origine du dépôt d'une tâche déployée par CI/CD.

Chaque fois que vous exécutez une bundle commande telle que validate, deploy ou run, la bundle commande remplit l’arborescence de configuration de la commande avec les paramètres par défaut suivants :

• bundle.git.origin_url, qui représente l’URL d’origine du référentiel. Il s’agit de la même valeur que celle que vous obtiendriez si vous exécutiez la commande git config --get remote.origin.url à partir de votre référentiel cloné. Vous pouvez utiliser des substitutions pour faire référence à cette valeur avec vos fichiers de configuration de pack, en tant que ${bundle.git.origin_url}.
• bundle.git.branch, qui représente la branche actuelle au sein du référentiel. Il s’agit de la même valeur que celle que vous obtiendriez si vous exécutiez la commande git branch --show-current à partir de votre référentiel cloné. Vous pouvez utiliser des substitutions pour faire référence à cette valeur avec vos fichiers de configuration de pack, en tant que ${bundle.git.branch}.

Pour récupérer ou remplacer les paramètres Git, votre pack doit se trouver dans un répertoire associé à un référentiel Git, par exemple un répertoire local qui est initialisé en exécutant la commande git clone. Si le répertoire n’est pas associé à un référentiel Git, ces paramètres Git sont vides.

Vous pouvez remplacer les paramètres origin_url et branch dans le mappage git de votre mappage bundle de niveau supérieur si nécessaire, comme suit :

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

databricks_cli_version

Le mappage bundle peut contenir un mappage databricks_cli_version qui limite la version de l’interface CLI de Databricks requise par le pack. Cela peut éviter les problèmes causés par l’utilisation de mappages non pris en charge dans une certaine version de l’interface CLI de Databricks.

La version de l’interface CLI de Databricks est conforme à la gestion sémantique de version et le mappage databricks_cli_version prend en charge la spécification des contraintes de version. Si la valeur actuelle databricks --version n’est pas dans les limites spécifiées dans le mappage du bundle databricks_cli_version, une erreur se produit lorsque databricks bundle validate est exécuté sur le bundle. Les exemples suivants illustrent une syntaxe de contrainte de version courante :

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

run_as

Le réglage run_as spécifie si user_name ou service_principal_name doit être utilisé pour exécuter le bundle. Il permet de séparer l’identité utilisée pour déployer un travail ou un pipeline de bundle à partir de celui utilisé pour exécuter le travail ou le pipeline.

Consultez le point . Spécifiez une identité d'exécution pour un flux de travail Databricks Asset Bundles.

inclure

Le tableau include spécifie une liste de globs de chemin d’accès qui contiennent des fichiers de configuration à inclure dans le pack. Ces globs de chemin d’accès sont relatifs à l’emplacement du fichier de configuration du pack dans lequel ils sont spécifiés.

L’interface CLI de Databricks n’inclut aucun fichier de configuration par défaut dans le pack. Vous devez utiliser le tableau include pour spécifier tous les fichiers de configuration à inclure dans le pack, autres que le fichier databricks.yml lui-même.

Ce tableau include peut apparaître uniquement sous forme de mappage de niveau supérieur.

La configuration d’exemple suivant inclut trois fichiers de configuration. Ces derniers se trouvent dans le même dossier que le fichier de configuration du pack :

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

La configuration d’exemple suivant inclut tous les fichiers dont le nom de fichier commence par bundle et se termine par .yml. Ces derniers se trouvent dans le même dossier que le fichier de configuration du pack :

include:
  - 'bundle*.yml'

Scripts

Le scripts paramètre spécifie des scripts qui peuvent être exécutés à l’aide bundle runde . Chaque script nommé dans le mappage contient du scripts contenu avec des commandes. Par exemple:

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

Pour plus d’informations, consultez Exécuter des scripts.

Synchronisation

Le mappage sync vous permet de configurer les fichiers qui font partie de vos déploiements de packs.

inclure et exclure

Les mappages include et exclude dans le mappage sync spécifient une liste de fichiers ou de dossiers à inclure dans, ou exclure, des déploiements groupés, en fonction des règles suivantes :

• En fonction d’une liste de globs de fichiers et de chemins d’accès dans un fichier .gitignore à la racine du pack, le mappage include peut contenir une liste de globs de fichiers, de globs de chemins d’accès, ou les deux, relatifs à la racine du pack, pour inclure explicitement.
• En fonction d’une liste de globs de fichier et de chemins d’accès dans un fichier .gitignore à la racine du pack, ainsi que de la liste de globs de fichier et de chemins d’accès dans le mappage include, le mappage exclude peut contenir une liste de globs de fichier, de globs de chemin d’accès ou les deux, par rapport à la racine du bundle, pour exclure explicitement.

Tous les chemins d’accès aux fichiers et aux dossiers spécifiés sont relatifs à l’emplacement du fichier de configuration du pack dans lequel ils sont spécifiés.

La syntaxe du fichier include et exclude et les modèles de chemin d’accès suit celle du modèle .gitignore standard. Consultez Format de modèle gitignore.

Par exemple, si le fichier .gitignore suivant contient les entrées suivantes :

.databricks
my_package/dist

Et le fichier de configuration de pack contient le mappage include suivant :

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

Alors tous les fichiers du dossier my_package/dist avec une extension de fichier de *.whl sont inclus. Les autres fichiers du dossier my_package/dist ne sont pas inclus.

Toutefois, si le fichier de configuration du pack contient également le mappage exclude suivant :

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

Alors tous les fichiers du dossier my_package/dist avec une extension de fichier de *.whl sont inclus, à l’exception du fichier appelé delete-me.whl. Les autres fichiers du dossier my_package/dist ne sont pas inclus non plus.

Le mappage sync peut également être déclaré dans le mappage targets pour une cible spécifique. Tout mappage sync déclaré dans une cible est fusionné avec toute déclaration de mappage sync de niveau supérieur. Par exemple, en reprenant l’exemple précédent, le mappage include suivant au niveau targets fusionne avec le mappage include dans le mappage sync de niveau supérieur :

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

chemins d'accès

Le mappage sync peut contenir un mappage paths qui spécifie des chemins d’accès locaux à synchroniser avec l’espace de travail. Le mappage paths vous permet de partager des fichiers communs entre des packs et on peut l’utiliser pour synchroniser des fichiers situés en dehors de la racine du pack. (La racine du pack est l’emplacement du fichier databricks.yml.) Cela s’avère particulièrement utile lorsque vous disposez d’un référentiel unique qui héberge plusieurs packs et que vous souhaitez partager des bibliothèques, des fichiers de code ou une configuration.

Les chemins d’accès spécifiés doivent être relatifs aux fichiers et répertoires ancrés dans le dossier où le mappage paths est défini. Si une ou plusieurs valeurs de chemin d’accès remontent le répertoire jusqu’à un ancêtre de la racine du pack, le chemin d’accès racine est déterminé de manière dynamique pour s’assurer que la structure de dossiers reste intacte. Par exemple, si le dossier racine du pack est appelé my_bundle, cette configuration dans databricks.yml synchronise le dossier common situé un niveau au-dessus de la racine du pack et la racine du pack elle-même :

sync:
  paths:
    - ../common
    - .

Un déploiement de ce pack se traduit par la structure de dossiers suivante dans l’espace de travail :

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

artefacts

Le mappage artifacts de niveau supérieur spécifie un ou plusieurs artefacts qui sont générés automatiquement pendant les déploiements de packs et qui peuvent être utilisés ultérieurement dans les exécutions de packs. Chaque artefact enfant prend en charge les mappages suivants :

• type est nécessaire pour les builds de roue Python. Pour générer un fichier de roue Python avant le déploiement, définissez-le sur whl. Pour générer d’autres artefacts, ce paramètre n’a pas besoin d’être spécifié.
• path est un chemin facultatif. Les chemins d’accès sont relatifs à l’emplacement du fichier de configuration de bundle. Pour les builds wheel Python, il s’agit du chemin d’accès au fichier setup.py du fichier wheel Python. Si path n’est pas inclus, l’interface CLI de Databricks tente de trouver le fichier setup.py du fichier wheel Python à la racine du pack.
• files est un mappage facultatif qui inclut un mappage enfant source, que vous pouvez utiliser pour définir les artefacts générés. Les chemins d’accès sont relatifs à l’emplacement du fichier de configuration de bundle.
• build est un ensemble facultatif de commandes de build autres que celles par défaut que vous souhaitez exécuter localement avant le déploiement. Pour les builds de fichiers wheels Python, l’interface CLI de Databricks suppose qu’elle peut trouver une installation locale du package wheel Python pour exécuter des builds, et qu’elle exécute le python setup.py bdist_wheel de la commande par défaut pendant chaque déploiement de pack. Spécifiez plusieurs commandes de build sur des lignes distinctes.
• dynamic_version permet aux bundles de mettre à jour la version de wheel en fonction de l’horodatage du fichier wheel. Le nouveau code peut ensuite être déployé sans avoir à mettre à jour la version dans setup.py ou pyproject.toml. Ce paramètre n’est valide que lorsqu’il type est défini sur whl.

L’exemple de configuration suivant exécute des tests et génère une roue. Pour obtenir un didacticiel complet sur l’offre groupée qui utilise artifacts pour générer une roue, consultez Générer un fichier de roue Python à l’aide de Bundles de ressources Databricks.

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

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

Pour obtenir un exemple de configuration qui génère un fichier JAR et le charge dans le catalogue Unity, consultez Bundle qui charge un fichier JAR dans le catalogue Unity.

Variables

Le fichier de paramètres des packs peut contenir un mappage variables de niveau supérieur dans lequel sont définies des variables personnalisées. Pour chaque variable, vous pouvez définir une description facultative et une valeur par défaut si la variable personnalisée est un type complexe, ou effectuer une recherche pour récupérer une valeur d’ID en utilisant le format suivant :

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>

Pour référencer une variable personnalisée dans la configuration du pack, utilisez la substitution ${var.<variable_name>}.

Pour plus d’informations sur les personnalisées et les substitutions personnalisées, consultez Substitutions et variables dans les packs de ressources Databricks.

espace de travail

Le fichier de configuration de pack ne peut contenir qu’un seul mappage workspace de niveau supérieur pour spécifier les paramètres d’espace de travail Azure Databricks autres que ceux par défaut à utiliser.

chemin_racine

Ce mappage workspace peut contenir un mappage root_path pour spécifier un chemin racine autre que celui par défaut à utiliser dans l’espace de travail pour les déploiements et les exécutions de flux de travail, par exemple :

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

Par défaut, pour root_path, l’interface CLI de Databricks utilise le chemin par défaut de /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, qui utilise des substitutions.

chemin_de_l'artifact

Ce mappage workspace peut également contenir un mappage artifact_path pour spécifier un chemin d’artefact autre que celui par défaut à utiliser dans l’espace de travail pour les déploiements et les exécutions de flux de travail, par exemple :

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

Par défaut, pour artifact_path, l’interface CLI de Databricks utilise le chemin par défaut de ${workspace.root}/artifacts, qui utilise des substitutions.

chemin de fichier

Ce mappage workspace peut également contenir un mappage file_path pour spécifier un chemin de fichier autre que celui par défaut à utiliser dans l’espace de travail pour les déploiements et les exécutions de flux de travail, par exemple :

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

Par défaut, pour file_path, l’interface CLI de Databricks utilise le chemin par défaut de ${workspace.root}/files, qui utilise des substitutions.

chemin_d'état

Le mappage state_path correspond par défaut au chemin par défaut de ${workspace.root}/state et représente le chemin dans votre espace de travail pour stocker les informations d’état de Terraform sur les déploiements.

Autres mappages d’espaces de travail

Le mappage workspace peut également contenir les mappages facultatifs suivants pour spécifier le mécanisme d’authentification Azure Databricks à utiliser. S’ils ne sont pas spécifiés dans ce mappage workspace, ils doivent l’être dans un mappage workspace en tant qu’enfant d’une ou plusieurs des cibles dans le mappage des cibles de niveau supérieur.

• Le mappage profile (ou les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de pack avec l’interface CLI de Databricks) spécifie le nom d’un profil de configuration à utiliser avec cet espace de travail pour l’authentification Azure Databricks. Ce profil de configuration est mappé à celui que vous avez créé lors de la configuration de l’interface CLI de Databricks.

  Remarque

  Databricks vous recommande d’utiliser le mappage host (ou les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de pack avec l’interface CLI de Databricks) à la place du mappage profile. Cela facilite le portage de vos fichiers de configuration de pack. La configuration du mappage host indique à l’interface CLI Databricks de rechercher un profil qui correspond dans votre fichier .databrickscfg, puis d’utiliser les champs du profil pour déterminer le type d’authentification Databricks à utiliser. S’il existe plusieurs profils avec un champ host correspondant dans votre fichier .databrickscfg, vous devez utiliser le mappage profile (ou les options de ligne de commande --profile ou -p) pour indiquer à l’interface CLI de Databricks le profil à utiliser. Pour obtenir un exemple, consultez la déclaration de la cible prod dans les exemples.

• Le mappage host spécifie l’URL de votre espace de travail Azure Databricks. Consultez URL par espace de travail.

• Pour l’authentification OAuth M2M (machine à machine), on utilise le mappage client_id. On peut également définir cette valeur dans la variable d’environnement locale DATABRICKS_CLIENT_ID. Vous pouvez également créer un profil de configuration avec la valeur client_id, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction avec l’interface CLI Databricks). Consultez Autoriser l’accès au principal de service à Azure Databricks avec OAuth.

  Remarque

  Vous ne pouvez pas spécifier de valeur du secret OAuth Azure Databricks dans le fichier de configuration du pack. À la place, définissez le DATABRICKS_CLIENT_SECRET de la variable d’environnement locale. Vous pouvez également ajouter la valeur client_secret à un profil de configuration, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de l’offre groupée avec l’interface CLI Databricks).

• Pour l’authentification de l’interface CLI Azure, on utilise le mappage azure_workspace_resource_id. On peut également définir cette valeur dans la variable d’environnement locale DATABRICKS_AZURE_RESOURCE_ID. Vous pouvez également créer un profil de configuration avec la valeur azure_workspace_resource_id, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction avec l’interface CLI Databricks). Consultez s’authentifier auprès d’Azure CLI.

• Pour l’authentification par clé secrète de client Azure auprès des principaux de service, on utilise les mappages azure_workspace_resource_id, azure_tenant_id et azure_client_id. Vous pouvez également définir ces valeurs dans les variables d’environnement locales DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID et ARM_CLIENT_ID respectivement. Vous pouvez également créer un profil de configuration avec les valeurs azure_workspace_resource_id, azure_tenant_id et azure_client_id, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l'exécution des commandes de validation, de déploiement, d'exécution et de destruction avec l'interface CLI Databricks). Consultez s’authentifier auprès des principaux de service Microsoft Entra.

  Remarque

  Vous ne pouvez pas spécifier de valeur du secret de client Azure dans le fichier de configuration du pack. À la place, définissez le ARM_CLIENT_SECRET de la variable d’environnement locale. Vous pouvez également ajouter la valeur azure_client_secret à un profil de configuration, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de l’offre groupée avec l’interface CLI Databricks).

• Pour l’authentification des identités gérée par Azure, on utilise les mappages azure_use_msi, azure_client_id et azure_workspace_resource_id. Vous pouvez également définir ces valeurs dans les variables d’environnement locales ARM_USE_MSI, ARM_CLIENT_ID et DATABRICKS_AZURE_RESOURCE_ID respectivement. Vous pouvez également créer un profil de configuration avec les valeurs azure_use_msi, azure_client_id et azure_workspace_resource_id, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l'exécution des commandes de validation, de déploiement, d'exécution et de destruction avec l'interface CLI Databricks). Consultez Authentifier avec des identités managées Azure.

• Le mappage azure_environment spécifie le type d’environnement Azure (par exemple Public, UsGov, Chine et Allemagne) pour un ensemble spécifique de points de terminaison d’API. La valeur par défaut est PUBLIC. On peut également définir cette valeur dans la variable d’environnement locale ARM_ENVIRONMENT. Vous pouvez également ajouter la valeur azure_environment à un profil de configuration, puis spécifier le nom du profil avec le mappage profile (ou en utilisant les options --profile ou -p lors de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de l’offre groupée avec l’interface CLI Databricks).

• Le mappage azure_login_app_id n’est pas opérationnel et est réservé à un usage interne.

• Le mappage auth_type spécifie le type d’authentification Azure Databricks à utiliser, en particulier dans les cas où l’interface CLI de Databricks déduit un type d’authentification inattendu. Consultez le “Autoriser l’accès aux ressources Azure Databricks”.

autorisations

Le mappage permissions de niveau supérieur spécifie un ou plusieurs niveaux d’autorisation à appliquer à toutes les ressources définies dans le pack. Si vous souhaitez appliquer des autorisations à une ressource spécifique, consultez Définir des autorisations pour une ressource spécifique.

Les niveaux d’autorisation de niveau supérieur autorisés sont CAN_VIEW, CAN_MANAGE et CAN_RUN.

L’exemple suivant dans un fichier de configuration groupé définit les niveaux d’autorisation d’un utilisateur, d’un groupe et d’un principal de service, qui sont appliqués à toutes les ressources définies dans resources le bundle :

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

ressources

Le mappage resources spécifie des informations sur les ressources Azure Databricks utilisées par le pack.

Ce mappage resources peut apparaître comme un mappage de niveau supérieur ou il peut s’agir d’un enfant d’une ou plusieurs des cibles dans le mappage de cibles de niveau supérieur, et inclut aucun ou l’un des types de ressources pris en charge. Chaque mappage de type de ressources comprend une ou plusieurs déclarations de ressources individuelles, qui doivent toutes porter un nom unique. Ces déclarations de ressources individuelles utilisent la charge utile de requête de l’opération de création de l’objet correspondant, exprimée en YAML, pour définir la ressource. Les propriétés prises en charge pour une ressource sont les champs pris en charge par l’objet correspondant.

Les charges utiles de la requête d’opération de création sont documentées dans la référence de l’API REST Databricks et la commande databricks bundle schema génère tous les schémas d’objet pris en charge. En outre, la commande databricks bundle validate retourne des avertissements si des propriétés de ressources inconnues sont trouvées dans les fichiers de configuration du pack.

L’exemple de configuration suivant définit une ressource de travail :

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

Pour plus d’informations sur les ressources prises en charge dans les packs, ainsi que sur la configuration et les exemples courants, consultez Ressources des packs de ressources Databricks et Exemples de configuration de pack.

cibles

Le mappage targets spécifie un ou plusieurs contextes dans lesquels exécuter des flux de travail Azure Databricks. Chaque cible est une collection unique d’artefacts, de paramètres d’espace de travail Azure Databricks et de détails sur le travail ou le pipeline Azure Databricks.

Le mappage targets se compose d’un ou plusieurs mappages cibles, qui doivent chacun avoir un nom programmatique (ou logique) unique.

Ce mappage targets est facultatif, mais vivement recommandé. Si spécifié, il peut apparaître uniquement comme un mappage de niveau supérieur.

Les paramètres de l’espace de travail de niveau supérieur, des artefacts et des mappages de ressources sont utilisés s’ils ne sont pas spécifiés dans un mappage targets, mais tous les paramètres en conflit sont remplacés par les paramètres au sein d’une cible.

Une cible peut également remplacer les valeurs de toutes les variables de niveau supérieur.

par défaut

Pour spécifier une cible par défaut pour les commandes de pack, définissez le mappage default sur true. Par exemple, cette cible appelée dev est celle par défaut :

targets:
  dev:
    default: true

Si une cible par défaut n’est pas configurée ou si vous souhaitez valider, déployer et exécuter des travaux ou des pipelines au sein d’une cible spécifique, utilisez l’option -t des commandes de pack.

Les commandes suivante valident, déploient et exécutent my_job dans les cibles dev et 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

L’exemple suivant déclare deux cibles. La première s’appelle dev et est la cible par défaut utilisée lorsqu’aucune cible n’est spécifiée pour les commandes de pack. La deuxième s’appelle prod et est utilisée uniquement lorsque cette cible est spécifiée pour les commandes de pack.

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

mode et présélections

Pour faciliter le développement et les bonnes pratiques CI/CD, les packs de ressources Databricks fournissent des modes de déploiement pour les cibles qui définissent des comportements par défaut pour les flux de travail de préproduction et de production. Certains comportements sont également configurables. Pour en savoir plus, consultez Modes de déploiement d’un pack de ressources Databricks.

Pour spécifier qu’une cible est traitée comme une cible de développement, ajoutez le mappage mode défini sur development. Pour spécifier qu’une cible est traitée comme une cible de production, ajoutez le mappage mode défini sur production. Par exemple, cette cible appelée prod est traitée comme une cible de production :

targets:
  prod:
    mode: production

Vous pouvez personnaliser certains des comportements à l’aide du mappage presets. Pour obtenir la liste des présélections disponibles, consultez Présélections personnalisées. L’exemple suivant montre une cible de production personnalisée qui préfixe et balise toutes les ressources de production :

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

Si mode et presets sont tous deux définis, les présélections remplacent le comportement du mode par défaut. Les paramètres des ressources individuelles remplacent les présélections. Par exemple, si une planification est définie sur UNPAUSED, mais que la présélection trigger_pause_status est elle définie sur PAUSED, la planification reprend.