Partager via

Modèles de projets de packs de ressources Databricks

  • Article

Cet article décrit la syntaxe des modèles de packs de ressources Databricks. Les bundles permettent la gestion par programmation des flux de travail Azure Databricks. Consultez Que sont les packs de ressources Databricks ?

Les modèles de pack permettent aux utilisateurs de créer des packs de manière cohérente et reproductible, en établissant des structures de dossiers, des étapes de génération et des tâches, des tests et d’autres attributs IaC (Infrastructure-as-code) DevOps courants dans un pipeline de déploiement d’environnement de développement.

Par exemple, si vous exécutez régulièrement des travaux Databricks qui nécessitent des packages personnalisés avec une étape de compilation fastidieuse lors de l’installation, vous pouvez accélérer votre boucle de développement en créant un modèle de bundle qui prend en charge les environnements de conteneur personnalisés.

Les modèles de pack définissent la structure de répertoires du pack qui sera créé et incluent un databricks.yml.tmplmodèle de fichier de configurationdatabricks_template_schema.json ainsi qu’un fichier contenant des variables d’invite utilisateur.

Utiliser un modèle de pack par défaut

Pour utiliser un modèle de pack par défaut Azure Databricks afin de créer votre pack, utilisez la commande Databricks CLI bundle init, en spécifiant le nom du modèle par défaut à utiliser. Par exemple, la commande suivante crée un pack en utilisant le modèle de pack Python par défaut :

databricks bundle init default-python

Si vous ne spécifiez pas de modèle par défaut, la commande bundle init présente l’ensemble des modèles disponibles parmi lesquels vous pouvez choisir.

Azure Databricks fournit les modèles de pack par défaut suivants :

Template Description
default-python Un modèle pour utiliser Python avec Databricks. Ce modèle crée un pack avec un travail et un pipeline Delta Live Tables. Reportez-vous à default-python.
default-sql Un modèle pour utiliser SQL avec Databricks. Ce modèle contient un fichier de configuration qui définit un travail qui exécute des requêtes SQL sur un entrepôt SQL. Reportez-vous à default-sql.
dbt-sql Un modèle qui tire parti de dbt-core pour le développement local et de packs pour le déploiement. Ce modèle contient la configuration qui définit un travail avec une tâche dbt ainsi qu’un fichier de configuration qui définit des profils dbt pour les travaux dbt déployés. Reportez-vous à dbt-sql.
mlops-stacks Un modèle de pile complète avancé pour démarrer de nouveaux projets de piles MLOps. Reportez-vous à mlops-stacks et à Packs de ressources Databricks pour des piles MLOps.

Utiliser un modèle de pack personnalisé

Pour utiliser un modèle de pack autre que des modèles de pack par défaut Azure Databricks, passez le chemin d’accès local ou l’URL distante du modèle à la commande Databricks CLI bundle init.

Par exemple, la commande suivante utilise le modèle dab-container-template créé dans le tutoriel Modèle de pack personnalisé :

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Créer un modèle de pack personnalisé

Les modèles de bundle utilisent la syntaxe de création de modèles de package Go. Consultez la documentation du Modèle de package Go.

Au minimum, un projet de modèle de pack doit avoir :

  • Un fichier databricks_template_schema.json à la racine du projet qui définit une variable d’invite utilisateur pour le nom du projet de pack.
  • Un fichier databricks.yml.tmpl qui se trouve dans un dossier template, qui définit la configuration des packs créés avec le modèle. Si votre fichier databricks.yml.tmpl fait référence à des modèles de configuration de *.yml.tmpl supplémentaires, spécifiez l’emplacement de ces modèles dans le mappage include.

Vous pouvez facultativement ajouter des sous-dossiers et des fichiers au dossier template que vous voulez reproduire dans les packs créés par le modèle.

Définir des variables d’invite utilisateur

La première étape de la création d’un modèle de pack de base est de créer un dossier de projet de modèle et un fichier nommé databricks_template_schema.json à la racine du projet. Ce fichier contient les variables pour lesquelles les utilisateurs fournissent des valeurs d’entrée quand ils utilisent le modèle pour créer un pack en utilisant bundle init. Le format de ce fichier suit la spécification de schéma JSON.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Ajoutez ce qui suit au fichier databricks_template_schema.json, puis enregistrez le fichier :

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

Dans ce fichier :

  • project_name est le seul nom de variable d’entrée.
  • default est une valeur par défaut facultative pour le cas où une valeur n’est pas fournie par l’utilisateur avec --config-file dans le cadre de la commande bundle init, ou si elle est remplacée par l’utilisateur sur l’invite de commandes.
  • description est l’invite utilisateur associée à la variable d’entrée pour le cas où une valeur n’est pas fournie par l’utilisateur avec --config-file dans le cadre de la commande bundle init.
  • order est un ordre facultatif dans lequel chaque invite utilisateur s’affiche, pour le cas où une valeur n’est pas fournie par l’utilisateur avec --config-file dans le cadre de la commande bundle init. Si order n’est pas fourni, les invites utilisateur s’affichent dans l’ordre où elles sont listées dans le schéma.
  • success_message est un message facultatif qui s'affiche lorsque le projet est bien créé.

Créer la structure de dossiers

Ensuite, créez le dossier template nécessaire et générez la structure de dossiers dans celui-ci. Cette structure sera reproduite dans les packs créés avec ce modèle. En outre, placez les fichiers que vous voulez inclure dans ces dossiers. Ce modèle de pack de base stocke des fichiers dans un dossier src et inclut un notebook simple.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Ajoutez ce qui suit au fichier simple_notebook.ipynb :

print("Hello World!")

Remplir les fichiers du modèle de configuration

Créez maintenant le fichier databricks.yml.tmpl nécessaire dans le dossier template :

touch basic-bundle-template/template/databricks.yml.tmpl

Remplissez ce fichier avec le code YAML du modèle de configuration de base. Ce modèle de configuration établit le nom du pack, un travail en utilisant le fichier du notebook spécifié et deux environnements cibles pour les packs créés avec ce modèle. Il tire également parti des substitutions de pack, qui est fortement recommandée. Consultez Substitutions de pack.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

Tester un modèle de pack

Enfin, testez votre modèle. Créez un dossier de projet de pack, puis utilisez l’interface CLI Databricks pour initialiser un nouveau pack en utilisant le modèle :

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

À l’invite What is your bundle project name?, tapez my_test_bundle.

Une fois le pack de test créé, le message de réussite du fichier de schéma est affiché. Si vous examinez le contenu du dossier my-test-bundle, vous voyez normalement ceci :

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

Et le fichier databricks.yml est maintenant personnalisé :

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

Partager le modèle

Si vous souhaitez partager ce modèle de bundle avec d’autres personnes, vous pouvez le stocker dans la gestion de version avec n’importe quel fournisseur pris en charge par Git et auquel vos utilisateurs ont accès. Pour exécuter la commande bundle init avec une URL Git, assurez-vous que le fichier databricks_template_schema.json se trouve à l’emplacement racine par rapport à cette URL Git.

Conseil

Vous pouvez placer le fichier databricks_template_schema.json dans un autre dossier, par rapport à la racine du bundle. Dans la commande bundle init, vous pouvez ensuite utiliser l’option --template-dir pour référencer ce dossier, qui contient le fichier databricks_template_schema.json.

Étapes suivantes