Configuration de pack de ressources Databricks

Article
11/18/2024

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

Un fichier de configuration de pack doit être exprimé au format YAML et doit contenir au minimum le mappage de pack de niveau supérieur. Chaque pack doit comprendre au minimum (et un seul) fichier de configuration de pack nommé databricks.yml. S’il existe plusieurs fichiers de configuration de bundle, ils doivent être référencés par le fichier databricks.yml à l’aide du mappage include.

Pour plus d’informations sur YAML, consultez la spécification et le tutoriel YAML officiels.

Pour créer et utiliser des fichiers de configuration de packs, consultez Développement de packs de ressources Databricks.

Présentation

Cette section fournit une représentation visuelle du schéma du fichier de configuration de pack. Pour plus d’informations, consultez Mappages.

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

Exemples

Remarque

Pour obtenir des exemples de configuration illustrant les fonctionnalités de bundle et les cas d’utilisation courants d’un bundle, consultez Exemples de configuration de bundle et le référentiel d’exemples de bundles dans GitHub.

L’exemple de configuration de bundle suivant spécifie le déploiement à distance d’un fichier local nommé hello.py qui se trouve dans le même répertoire que ce fichier de configuration de pack local nommé databricks.yml. 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.

Databricks vous recommande d’utiliser le mappage host au lieu du mappage default dans la mesure du possible, car cela rend vos fichiers de configuration de pack plus facilement portables. La définition du mappage host indique à l’interface CLI Databricks de rechercher 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 dans votre fichier .databrickscfg, vous devez utiliser le profile pour indiquer à l’interface CLI Databricks quel profil spécifique utiliser. Pour obtenir un exemple, consultez la déclaration cible prod plus loin dans cette section.

Cette technique vous permet de réutiliser et de remplacer les définitions et paramètres de tâche dans le bloc resources :

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

Bien que le fichier de configuration de pack suivant soit équivalent fonctionnellement, il n’est pas modularisé, ce qui ne permet pas une bonne réutilisation. En outre, cette déclaration ajoute une tâche au travail plutôt que de remplacer le travail existant :

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

L’exemple suivant ajoute une cible portant le nom prod qui utilise une autre URL d’espace de travail distant et des informations d’identification d’authentification de l’espace de travail, qui sont lues à partir de l’entrée host correspondant du fichier .databrickscfg de l’appelant avec l’URL de l’espace de travail spécifiée. Ce travail exécute le même notebook, mais utilise un autre cluster distant avec l’ID de cluster spécifié. Notez 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

Pour valider, déployer et exécuter ce travail dans la cible dev :

# 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

Voici l’exemple précédent, mais divisé en fichiers de composants pour encore plus de modularisation et une meilleure réutilisation à travers plusieurs fichiers de configuration de pack. Cette technique vous permet non seulement de réutiliser différents paramètres et définitions, mais vous pouvez également remplacer l’un de ces fichiers avec d’autres fichiers qui fournissent des déclarations complètement différentes :

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

Mappages

Les sections suivantes décrivent la syntaxe du fichier de configuration de pack, par mappage de niveau supérieur.

bundle
variables
workspace
autorisations
artifacts
inclure
resources
synchronisation
cibles

bundle

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

Ce mappage bundle doit contenir un mappage name qui spécifie un nom programmatique (ou logique) pour le bundle. L’exemple suivant déclare un bundle 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 name du mappage bundle 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 groupement à 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 groupement, consultez URL et ID du groupement.

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

Remarque

Ce paramètre est déconseillé. Utilisez cluster_id à la place.

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

git

Vous pouvez récupérer et substituer les détails du contrôle de version Git associés à votre offre groupée. Cela est utile pour annoter vos ressources déployées. Par exemple, vous pouvez inclure l’URL d’origine de votre référentiel dans la description d’un modèle Machine Learning que vous déployez.

Chaque fois que vous exécutez une commande bundle telle que validate, deploy ou run, la commande bundle 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}.
bundle.git.commit, qui représente la validation HEAD dans le référentiel. Il s’agit de la même valeur que celle que vous obtiendriez si vous exécutiez la commande git rev-parse HEAD à 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.commit}.

Pour récupérer ou remplacer les paramètres Git, votre bundle 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 Databricks requise par l’offre groupée. Cela peut empêcher les problèmes causés par l’utilisation de mappages non pris en charge dans une certaine version de l’interface CLI Databricks.

La version de l’interface CLI Databricks est conforme au contrôle de version sémantique et le mappage databricks_cli_version prend en charge la spécification des contraintes de version. Si la valeur databricks --version actuelle n’est pas dans les limites spécifiées dans le mappage databricks_cli_version de l’offre groupée, une erreur se produit lorsque databricks bundle validate est exécuté sur l’offre groupée. 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

variables

Le fichier de paramètres des bundles peut contenir un mappage variables de niveau supérieur dans lequel des variables personnalisées sont définies. 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>

Remarque

Les variables sont supposées être de type string, sauf si type est défini sur complex. Consultez Définir une variable complexe.

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

Pour plus d’informations sur les variables personnalisées et les substitutions, 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.

Important

Les chemins d’accès d’espace de travail Databricks valides commencent par l’un ou l’autre /Workspace ./Volumes Les chemins d’accès d’espace de travail personnalisés sont automatiquement préfixés /Workspace. Par conséquent, si vous utilisez une substitution de chemin d’accès d’espace de travail dans votre chemin personnalisé tel que ${workspace.file_path}, vous n’avez pas besoin /Workspace de vous ajouter au chemin d’accès.

root_path

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 Databricks utilise le chemin d’accès par défaut de /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, qui utilise des substitutions.

artifact_path

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 Databricks utilise le chemin d’accès par défaut de ${workspace.root}/artifacts, qui utilise des substitutions.

Remarque

Le mappage artifact_path ne prend pas en charge les chemins DBFS (Système de fichiers Databricks).

file_path

Ce mappage workspace peut également contenir un mappage file_path pour spécifier un chemin d’accès au 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 Databricks utilise le chemin d’accès par défaut de ${workspace.root}/files, qui utilise des substitutions.

state_path

Le mappage state_path correspond par défaut au chemin d’accès par défaut de ${workspace.root}/state et représente le chemin d’accès 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.

Important

Vous devez coder des valeurs en dur pour les mappages workspace suivants pour l’authentification Azure Databricks. Par exemple, vous ne pouvez pas spécifier de variables personnalisées pour les valeurs de ces mappages à l’aide de la syntaxe ${var.*}.

Le mappage profile (ou les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI) 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 Databricks.

Remarque

Databricks vous recommande d’utiliser le mappage host (ou les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI) à la place du mappage profile, car cela rend vos fichiers config de bundle plus portables. La définition du mappage host indique à l’interface CLI Databricks de rechercher un profil correspondant dans votre fichier .databrickscfg, puis d’utiliser les champs de ce 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 Databricks CLI 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), le mappage client_id est utilisé. Vous pouvez é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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI). Consultez Authentifier l’accès à Azure Databricks avec un principal de service à l’aide d’OAuth (OAuth M2M).

Remarque

Vous ne pouvez pas spécifier de valeur de secret OAuth Azure Databricks dans le fichier config de bundle. À 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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI).
Pour l’authentification Azure CLI, le azure_workspace_resource_id de mappage est utilisé. Vous pouvez également définir cette valeur dans la DATABRICKS_AZURE_RESOURCE_ID de la variable d’environnement locale. 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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI). Consultez Authentification Azure CLI.
Pour l’authentification par clé secrète client Azure auprès des principaux de service, les mappages azure_workspace_resource_id, azure_tenant_idet azure_client_id sont utilisés. 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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI). Consultez Authentification du principal de service MS Entra.

Remarque

Vous ne pouvez pas spécifier une valeur de clé secrète 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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI).
Pour l’authentification des identités managées Azure, les mappages azure_use_msi, azure_client_id et azure_workspace_resource_id sont utilisés. 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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI). Consultez Authentification 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. Vous pouvez é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 utiliser les options --profile ou -p au moment de l’exécution des commandes de validation, de déploiement, d’exécution et de destruction de bundle avec l’interface Databricks CLI).
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 Databricks déduit un type d’authentification inattendu. Consultez Authentifier 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 bundle. 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_MANAGEet CAN_RUN.

L’exemple suivant, dans un fichier de configuration groupé, définit les niveaux d’autorisation pour un utilisateur, un groupe et un principal de service, qui sont appliqués à tous les travaux, pipelines, expériences et modèles définis dans resources dans 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

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 bundles et qui peuvent être utilisés ultérieurement dans les exécutions de bundles. Chaque artefact enfant prend en charge les mappages suivants :

type est obligatoire. Pour générer un fichier wheel Python avant le déploiement, ce mappage doit être défini sur whl.
path est un chemin relatif facultatif entre l’emplacement du fichier de configuration du pack et l’emplacement du fichier setup.py du wheel Python. Si path n’est pas inclus, CLI Databricks tentera de trouver le fichier setup.py du wheel Python dans la racine du pack.
files est un mappage facultatif comprenant un mappage source enfant que vous pouvez utiliser pour spécifier des emplacements autres que les emplacements par défaut à inclure pour les instructions de build complexes. Les emplacements sont spécifiés en tant que chemins d’accès relatifs à partir de l’emplacement du fichier de configuration du pack.
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 wheel Python, l’interface CLI 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 bundle. Pour spécifier plusieurs commandes de build, séparez chaque commande à l’aide de doubles esperluettes (&&).

Pour plus d’informations, notamment un exemple de pack qui utilise artifacts, consultez Développer un fichier wheel Python à l’aide de packs de ressources Databricks.

Conseil

Vous pouvez définir, combiner et remplacer les paramètres des artefacts dans des bundles à l’aide des techniques décrites dans Définir dynamiquement les paramètres d’artefact dans les bundles de ressources Databricks.

inclure

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

L’interface CLI 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 bundle, 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 de l’exemple suivant inclut trois fichiers de configuration. Ces fichiers 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 de l’exemple suivant inclut tous les fichiers dont le nom de fichier commence par bundle et se termine par .yml. Ces fichiers se trouvent dans le même dossier que le fichier de configuration du pack :

include:
  - "bundle*.yml"

ressources

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

Ce mappage resources peut apparaître sous la forme d’un mappage de niveau supérieur, ou il peut s’agir d’un enfant d’une ou de plusieurs des cibles dans le mappage des cibles de niveau supérieur, et comprend zéro ou un des types de ressources pris en charge. Chaque mappage de type de ressource 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 la 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 de l’objet correspondant.

Les charges utiles de la requête de l’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 ressource inconnues sont trouvées dans les fichiers de configuration de l’offre groupée.

Le tableau suivant répertorie les types de ressources pris en charge pour les offres groupées et les liens vers la documentation sur les charges utiles correspondantes.

Type de ressource	Mappages des ressources
cluster	Mappages de cluster : POST /api/2.1/clusters/create
tableau de bord	Mappages de tableaux de bord : POST /api/2.0/lakeview/dashboards
expérience	Mappages d’expériences : POST /api/2.0/mlflow/experiments/create
travail	Mappages de travaux : POST /api/2.1/jobs/create Pour plus d’informations, consultez types de tâches de travail et remplacer les nouveaux paramètres de cluster de travaux.
pipeline	Mappages de pipelines : POST /api/2.0/pipelines
modèle	Mappages de modèles : POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	Mappages de points de terminaison de service de modèle : POST /api/2.0/service-endpoints
registered_model (Unity Catalog)	Mappages de modèles de catalogue Unity : POST /api/2.1/unity-catalog/models
schema (Unity Catalog)	Mappages de schémas de catalogue Unity : POST /api/2.1/unity-catalog/schemas

Tous les chemins d’accès aux dossiers et aux fichiers référencés par les déclarations de ressources sont relatifs à l’emplacement du fichier de configuration du bundle dans lequel ces chemins d’accès sont spécifiés.

cluster

La ressource de cluster vous permet de créer des clusters à usage général. L’exemple suivant crée un groupement nommé my_cluster et le définit comme le groupement à utiliser pour exécuter le Notebook dans my_job :

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

La ressource de tableau de bord vous permet de gérer les tableaux de bord IA/BI dans un bundle. Pour plus d’informations sur les tableaux de bord IA/BI, consultez Tableaux de bord.

L’exemple suivant inclut et déploie l’exemple de tableau de bord NyC Taxi Trip Analysis dans l’espace de travail Databricks.

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}

Si vous utilisez l’interface utilisateur pour modifier le tableau de bord, les modifications apportées via l’interface utilisateur ne sont pas appliquées au fichier JSON du tableau de bord dans le bundle local, sauf si vous la mettez explicitement à jour à l’aide bundle generatede . Vous pouvez utiliser l’option --watch pour interroger et récupérer en continu les modifications apportées au tableau de bord. Consultez Générer un fichier de configuration groupé.

En outre, si vous tentez de déployer un bundle qui contient un fichier JSON de tableau de bord différent de celui de l’espace de travail distant, une erreur se produit. Pour forcer le déploiement et remplacer le tableau de bord dans l’espace de travail distant avec l’espace de travail local, utilisez l’option --force . Consultez Déployer un bundle.

travail

L’exemple suivant déclare un travail avec la clé de ressource de hello-job :

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

L’exemple suivant déclare un pipeline avec la clé de ressource de hello-pipeline :

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

schéma

Le type de ressource de schéma vous permet de définir des schémas catalogue Unity pour les tables et d’autres ressources de vos flux de travail et pipelines créés dans le cadre d’un bundle. Un schéma, différent des autres types de ressources, présente les limitations suivantes :

Le propriétaire d’une ressource de schéma est toujours l’utilisateur de déploiement et ne peut pas être modifié. Si run_as est spécifié dans le bundle, il est ignoré par les opérations sur le schéma.
Seuls les champs pris en charge par l’API de création d’objet Schemas correspondante sont disponibles pour la ressource schema. Par exemple, enable_predictive_optimization n’est pas pris en charge, car il n’est disponible que sur l’API de mise à jour.

L’exemple suivant déclare un pipeline avec la clé de ressource my_pipeline qui crée un schéma Unity Catalog avec la clé my_schema comme cible :

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.

Un mappage d’octrois de niveau supérieur n’est pas pris en charge par les bundles de ressources Databricks. Par conséquent, si vous souhaitez définir des subventions pour un schéma, définissez les subventions pour le schéma dans le mappage schemas :

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"

synchronisation

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

inclure et exclure

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

Sur la base d’une liste de globs de fichiers et de chemins d’accès dans un fichier .gitignore dans la racine du bundle, le mappage include peut contenir une liste de globs de fichiers, de chemins d’accès ou les deux, relatifs à la racine du bundle, à inclure explicitement.
Sur la base d’une liste de globs de fichiers et de chemins d’accès dans un fichier .gitignore dans la racine du bundle, plus la liste de globs de fichiers et de chemins d’accès dans le mappage include, le mappage exclude peut contenir une liste de globs de fichiers, de chemins d’accès ou les deux, relatifs à la racine du bundle, à exclure explicitement.

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

La syntaxe des modèles de fichier include et exclude de chemin suit la syntaxe de modèle .gitignore standard. Voir 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 nommé delete-me.whl. Les autres fichiers du dossier my_package/dist ne sont pas non plus inclus.

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 peut être utilisé 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 est 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 parcourent le répertoire vers un ancêtre de la racine de pack, le chemin racine est déterminé dynamiquement pour s’assurer que la structure de dossiers reste intacte. Par exemple, si le dossier racine du pack est nommé my_bundle, cette configuration dans databricks.yml synchronise le dossier common situé un niveau au-dessus de la racine du pack et la racine de pack elle-même :

sync:
  paths:
    - ../common
    - .

Un déploiement de ce pack entraîne la structure de dossiers suivante dans l’espace de travail :

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

objectifs

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 de targets est facultatif, mais fortement 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.

default

Pour spécifier une cible par défaut pour les commandes groupées, définissez le mappage default sur true. Par exemple, cette cible nommée dev est la cible 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 groupées.

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 cible a le nom dev et est la cible par défaut utilisée lorsqu’aucune cible n’est spécifiée pour les commandes groupées. La deuxième cible a le nom prod et est utilisée uniquement lorsque cette cible est spécifiée pour les commandes groupées.

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

mode et présélections

Pour faciliter le développement et les meilleures pratiques CI/CD, Databricks Asset Bundles fournit 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 du pack de ressources Databricks.

Conseil

Pour définir des identités d’exécution pour des packs, vous pouvez spécifier run_as pour chaque cible, comme décrit dans Spécifier une identité d’exécution pour un flux de travail de packs 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 nommé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 étiquette 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 définie sur PAUSED, la planification est redémarrée.

Partager via

Configuration de pack de ressources Databricks

Présentation

Exemples

Mappages

bundle

cluster_id

compute_id

git

databricks_cli_version

variables

espace de travail

root_path

artifact_path

file_path

state_path

Autres mappages d’espaces de travail

autorisations

artefacts

inclure

ressources

cluster

dashboard

travail

pipeline

schéma

synchronisation

inclure et exclure

chemins d’accès

objectifs

default

mode et présélections

Commentaires

Ressources supplémentaires