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.

Remplacements

Vous pouvez utiliser des substitutions pour récupérer des valeurs de paramètres susceptibles de changer en fonction du contexte du déploiement et de l’exécution du bundle. Par exemple, les substitutions peuvent être utilisées pour faire référence aux valeurs des champs bundle name, bundle target, et espace de travail userName pour construire l’espace de travail root_path dans le fichier de configuration du bundle :

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Si someone@example.com avait déployé ce paquet, il serait déployé sur le chemin racine /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Vous pouvez également créer des substitutions pour les ressources nommées. Par exemple, pour la définition de pipeline suivante, vous pouvez utiliser ${resources.pipelines.my_pipeline.target} pour la valeur de la cible du pipeline :

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Pour déterminer les substitutions valides, utilisez la référence de configuration de bundle, la référence de configuration des ressources ou la hiérarchie de schéma des objets correspondants documentés dans la référence de l’API REST ou la sortie de la bundle schema commande.

Voici quelques substitutions couramment utilisées :

• ${bundle.name}
• ${bundle.target} # Use this substitution instead of ${bundle.environment}
• ${workspace.host}
• ${workspace.current_user.domain_friendly_name}
• ${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 vos fichiers de configuration de bundle dans le mappage variables ou dans un fichier variable-overrides.json. Pour plus d’informations sur le mappage de variables, consultez les 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 default valeur 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, ailleurs dans vos fichiers de configuration de bundle ou dans le .databricks/bundle/<target>/variable-overrides.json fichier du projet de bundle. Consultez Définir la valeur d’une variable.

Référencer une variable

Pour référencer une variable personnalisée dans la configuration de votre pack, utilisez la variable substitution${var.<variable_name>}. Par exemple, la configuration suivante référence les 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 défini de default valeur pour une variable ou si vous souhaitez remplacer temporairement la default valeur d’une variable, fournissez la nouvelle valeur temporaire de la variable à l’aide de l’une des approches suivantes.

• Fournissez la valeur de la variable dans le cadre d’une bundle commande telle que validate, deployou run. Pour ce faire, utilisez l’option --var="<key>=<value>", où <key> se trouve le nom de la variable et <value> 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"
  

  Ou bien, fournissez la valeur de la variable dans le cadre d'une commande bundle telle que validate, deploy ou 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"
  

• Fournissez la valeur de la variable dans vos fichiers de configuration de paquet à l’aide du mappage variables au sein du mappage targets, en suivant ce format :

  variables:
    <variable-name>: <value>
  

  Par exemple, pour définir 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
  

• Fournissez la valeur de la variable dans le .databricks/bundle/<target>/variable-overrides.json fichier en utilisant le format suivant :

  {
    "<variable-name>": "<variable-value>"
  }
  

  Par exemple, pour fournir des valeurs pour les variables nommées my_cluster_id et my_notebook_path pour la cible de développement, créez un fichier .databricks/bundle/dev/variable-overrides.json et définissez son contenu sur :

  {
    "my_cluster_id": "1234-567890-abcde123",
    "my_notebook_path": "./hello.py"
  }
  

  Vous pouvez également définir des variables complexes dans le fichier variable-overrides.json.

Ordre de précédence

L’interface CLI Databricks recherche des valeurs pour les variables dans l’ordre suivant, en s’arrêtant lorsqu’elle trouve une valeur pour une 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 le fichier variables-overrides.json, s’il existe.
4. Dans tous les mappages variables, parmi les mappages targets dans vos fichiers de configuration de pack.
5. Toute default valeur de la définition de cette variable, parmi les mappages de niveau variables supérieur au sein de vos fichiers de configuration groupés.

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 bundle dans votre configuration de bundle, définissez type sur complex.

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

Vous pouvez également définir une variable complexe dans le fichier .databricks/bundle/<target>/variable-overrides.json, comme illustré dans l’exemple suivant :

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

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

Pour les types d’objets alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal et warehouse, vous pouvez définir une lookup pour votre variable personnalisée pour récupérer l’ID d’un objet nommé à l’aide de ce format :

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}

Substitution de sortie et valeurs de variables

Pour vous assurer que vos substitutions et variables sont correctement spécifiées et analysées par databricks Asset Bundles, exécutez databricks bundle validate. Voir databricks bundle validate. Pour afficher les valeurs qui seront utilisées lorsque vous déployez un bundle, utilisez l’option --output json suivante :

databricks bundle validate --output json

Par exemple, pour un bundle avec la variable my_cluster_id définie et utilisée dans une tâche de travail :

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

La sortie du databricks bundle validate schéma est la suivante :

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}