Substitutions et variables dans les packs de ressources Databricks

Les packs de ressources Databricks prennent en charge les substitutions et les variables personnalisées, ce qui rend vos fichiers de configuration de pack plus modulaires et réutilisables. Les substitutions et les variables personnalisées permettent la récupération dynamique des valeurs afin que les paramètres puissent être déterminés au moment du déploiement et de l’exécution d’un pack.

Substitutions

Vous pouvez utiliser des substitutions pour récupérer les valeurs des paramètres qui changent en fonction du contexte du déploiement et de l’exécution du pack.

Par exemple, lorsque vous exécutez la commande bundle validate --output json, vous pouvez voir un graphique comme celui-ci :

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Les substitutions peuvent être utilisées pour faire référence aux valeurs du pack name, du pack target et des champs userName de l’espace de travail pour construire l’espace de travail root_path dans le fichier de configuration du pack :

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Vous pouvez également créer des substitutions pour les ressources nommées. Par exemple, pour le pipeline configuré avec le nom my_pipeline, ${resources.pipelines.my_pipeline.target} est la substitution de la valeur de la cible de my_pipeline.

Pour déterminer les substitutions valides, vous pouvez utiliser la hiérarchie de schéma documentée dans la référence de l’API REST ou utiliser la sortie de la commande bundle schema.

Voici quelques substitutions couramment utilisées :

• ${bundle.name}
• ${bundle.target} # Use this substitution instead of ${bundle.environment}
• ${workspace.host}
• ${workspace.current_user.short_name}
• ${workspace.current_user.userName}
• ${workspace.file_path}
• ${workspace.root_path}
• ${resources.jobs.<job-name>.id}
• ${resources.models.<model-name>.name}
• ${resources.pipelines.<pipeline-name>.name}

Variables personnalisées

Vous pouvez définir des variables personnalisées simples et complexes dans votre pack pour permettre la récupération dynamique des valeurs nécessaires à de nombreux scénarios. Les variables personnalisées sont déclarées dans les fichiers de configuration de votre pack au sein du mappage variables. Consultez Variables.

L’exemple de configuration suivant définit les variables my_cluster_id et my_notebook_path :

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Si vous ne fournissez pas de valeur default pour une variable dans le cadre de cette déclaration, vous devez la définir lors de l’exécution de commandes groupées, via une variable d’environnement ou ailleurs dans vos fichiers de configuration du pack, comme décrit dans Définir la valeur d’une variable.

Pour référencer une variable personnalisée dans la configuration du pack, utilisez la substitution de variable ${var.<variable_name>}. Par exemple, pour référencer des variables my_cluster_id et my_notebook_path :

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Définir la valeur d’une variable

Si vous n’avez pas fourni de valeur default pour une variable, ou si vous souhaitez remplacer temporairement la valeur default d’une variable, fournissez la nouvelle valeur temporaire de la variable à l’aide d’une des approches suivantes :

• Fournissez la valeur de la variable dans le cadre d’une commande bundle telle que validate, deployou run. Pour ce faire, utilisez l’option --var="<key>=<value>", où <key> est le nom de la variable et <value> est la valeur de la variable. Par exemple, dans le cadre de la commande bundle validate, pour fournir la valeur de 1234-567890-abcde123 à la variable nommée my_cluster_idet pour fournir la valeur de ./hello.py à la variable nommée my_notebook_path, exécutez :

  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"
  
  # Or:
  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
  

• Fournissez la valeur de la variable en définissant une variable d’environnement. Le nom de la variable d’environnement doit commencer par BUNDLE_VAR_. Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation. Par exemple, pour fournir la valeur de 1234-567890-abcde123 à la variable nommée my_cluster_id, et pour fournir la valeur de ./hello.py à la variable nommée my_notebook_path, exécutez la commande suivante avant d’appeler une commande bundle telle que validate, deployou run :

  Pour Linux et macOS :

  export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
  

  Pour Windows :

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
  

  Vous pouvez également fournir la valeur de la variable dans le cadre d’une commande bundle telle que validate, deployou run, par exemple pour Linux et macOS :

  BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
  

  Ou pour Windows :

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
  

• Indiquez la valeur de la variable dans vos fichiers de configuration de pack. Pour ce faire, utilisez un mappage variables dans le mappage targets, en suivant ce format :

  variables:
    <variable-name>: <value>
  

  Par exemple, pour fournir des valeurs pour les variables nommées my_cluster_id et my_notebook_path pour deux cibles distinctes :

  targets:
    dev:
      variables:
        my_cluster_id: 1234-567890-abcde123
        my_notebook_path: ./hello.py
    prod:
      variables:
        my_cluster_id: 2345-678901-bcdef234
        my_notebook_path: ./hello.py
  

Dans les exemples précédents, l’interface CLI Databricks recherche des valeurs pour les variables my_cluster_id et my_notebook_path dans l’ordre suivant, en s’arrêtant quand elle trouve une valeur pour chaque variable correspondante, et en ignorant les autres emplacements de cette variable :

1. dans toutes les options --var spécifiées dans le cadre de la commande bundle.
2. dans les variables d’environnement définies qui commencent par BUNDLE_VAR_.
3. Dans tous les mappages variables, parmi les mappages targets dans vos fichiers de configuration de pack.
4. N’importe quelle valeur default pour la définition de cette variable, parmi les mappages variables de niveau supérieur dans vos fichiers de configuration de pack.

Définir une variable complexe

Une variable personnalisée est supposée être de type chaîne, sauf si vous la définissez comme une variable complexe. Pour définir une variable personnalisée avec un type complexe pour votre pack, définissez type sur complex dans la configuration de votre pack.

Dans l’exemple suivant, les paramètres de cluster sont définis dans une variable complexe personnalisée nommée my_cluster :

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

Récupérer la valeur d’ID d’un objet

Pour les alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principalet warehouse types d’objets, vous pouvez définir un lookup pour votre variable personnalisée pour récupérer l’ID d’un objet nommé au format suivant :

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Si une recherche est définie pour une variable, l’ID de l’objet portant le nom spécifié est utilisé comme valeur de la variable. Cela garantit que l’ID résolu correct de l’objet est toujours utilisé pour la variable.

Par exemple, dans la configuration suivante, ${var.my_cluster_id} sera remplacé par l’ID du cluster 12.2 partagé.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}