Migrer de dbx vers des packs

Article
10/09/2024

Important

Databricks vous recommande d’utiliser les packs de ressources Databricks plutôt que dbx par Databricks Labs. Les articles associés concernant dbx ont été retirés et peuvent ne pas être mis à jour.

Cet article explique comment migrer des projets pour dbx de Databricks Labs vers des packs de ressources Databricks. Consultez Présentation de dbx de Databricks Labs et Que sont les packs de ressources Databricks ?.

Avant de procéder à la migration, notez les limitations et comparaisons de fonctionnalités suivantes entre dbx de Databricks Labs et les packs de ressources Databricks.

Limites

La fonctionnalité suivante prise en charge dans dbx de Databricks Labs est limitée, n’existe pas ou nécessite des solutions de contournement dans les packs de ressources Databricks.

La création d’artefacts JAR n’est pas prise en charge dans les packs.
La notation FUSE des chemins d’espace de travail n’est pas prise en charge dans les packs (par exemple, /Workspace/<path>/<filename>). Toutefois, vous pouvez indiquer aux packs de générer des chemins d’espace de travail de style FUSE pendant les déploiements en utilisant une notation de type /Workspace/${bundle.file_path}/<filename>.

Comparaison de fonctionnalités

Avant de procéder à la migration, notez la façon dont les fonctionnalités suivantes pour dbx de Databricks Labs sont implémentées dans les packs de ressources Databricks.

Modèles et projets

dbx fournit une prise en charge du templating Jinja. Vous pouvez inclure des modèles Jinja dans la configuration du déploiement, et passer des variables d’environnement inline ou dans un fichier de variables. Bien que ce ne soit pas recommandé, dbx fournit également une prise en charge expérimentale des fonctions utilisateur personnalisées.

Les packs prennent en charge les modèles Go pour la réutilisation de la configuration. Les utilisateurs peuvent créer des packs basés sur des modèles prédéfinis. Il y a une parité presque complète pour le templating, à l’exception des fonctions utilisateur personnalisées.

Gestion de la génération

dbx fournit une prise en charge de la génération avec pip wheel, Poetry et Flit. Les utilisateurs peuvent spécifier l’option de génération dans la section build du fichier deployment.yml d’un projet.

Les packs permettent aux utilisateurs de générer, déployer et exécuter des fichiers wheel Python. Les utilisateurs peuvent tirer parti de l’entrée whl intégrée dans le fichier databricks.yml d’un pack.

Synchroniser, déployer et exécuter du code

dbx permet de charger du code séparément de la génération des ressources d’espace de travail, comme les travaux Azure Databricks.

Les packs chargent toujours du code, et créent ou mettent à jour des ressources d’espace de travail en même temps. Cela simplifie les déploiements et évite les conditions de blocage pour les travaux déjà en cours.

Migrer un projet dbx vers un pack

Après avoir noté les limitations et comparaisons de fonctionnalités précédentes entre dbx de Databricks Labs et les packs de ressources Databricks, vous êtes prêt à migrer de dbx vers les packs.

Databricks recommande pour commencer une migration de projet dbx que vous conserviez votre projet dbx dans son dossier d’origine et que vous ayez un dossier vide distinct où copier le contenu de votre projet dbx d’origine. Ce dossier distinct est votre nouveau pack. Vous pouvez rencontrer des problèmes inattendus si vous commencez à convertir en pack votre projet dbx dans son dossier d’origine, puis que vous faites des erreurs ou voulez recommencer à partir du début,

Étape 1 : Installer et configurer l’interface CLI Databricks

Les bundles de ressources Databricks sont généralement disponibles dans Databricks CLI version 0.218.0 et versions ultérieures. Si vous avez déjà installé et configuré Databricks CLI version 0.218.0 ou ultérieure, passez à l’étape 2.

Remarque

Les packs ne sont pas compatibles avec l’interface CLI Databricks version 0.18 ou antérieure.

Installez ou mettez à jour Databricks CLI version 0.218.0 ou ultérieure. Consultez Installer ou mettre à jour l’interface CLI Databricks.
Configurez l’interface CLI Databricks pour l’authentification dans vos espaces de travail Azure Databricks cibles, par exemple en utilisant l’authentification par jeton d’accès personnel Azure Databricks. Pour voir les autres types d’authentification Azure Databricks, consultez Authentification pour l’interface CLI Databricks.

Étape 2 : créer le fichier de configuration du pack

Si vous utilisez un environnement de développement intégré (IDE) tel que Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate qui prend en charge les fichiers YAML et les fichiers de schéma JSON, vous pouvez non seulement utiliser votre IDE pour créer le fichier de configuration du pack, mais aussi pour vérifier la syntaxe et la mise en forme du fichier et fournir des conseils de saisie semi-automatique de code, comme suit.

Visual Studio Code

Ajoutez la prise en charge du serveur de langage YAML à Visual Studio Code, par exemple en installant l’extension YAML à partir de la place de marché Visual Studio Code.
Générez le fichier de schéma JSON de configuration du pack de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la sortie vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :
```
databricks bundle schema > bundle_config_schema.json
```
Utilisez Visual Studio Code pour créer ou ouvrir un fichier de configuration de pack dans le répertoire actuel. Par convention, ce fichier est nommé databricks.yml.
Ajoutez le commentaire suivant au début de votre fichier de configuration du pack :
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Remarque

Dans le commentaire précédent, si votre fichier de schéma JSON de configuration du pack de ressources Databricks se trouve dans un chemin d’accès différent, remplacez bundle_config_schema.json par le chemin d’accès complet à votre fichier de schéma.
Utilisez les fonctionnalités de serveur de langage YAML que vous avez ajoutées précédemment. Pour plus d’informations, consultez la documentation de votre serveur de langage YAML.

PyCharm Professional

Générez le fichier de schéma JSON de configuration du pack de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la sortie vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :
```
databricks bundle schema > bundle_config_schema.json
```
Configurez PyCharm pour reconnaître le fichier de schéma JSON de configuration du pack, puis effectuez la mise en correspondance du schéma JSON en suivant les instructions fournies dans Configurer un schéma JSON personnalisé.
Utilisez PyCharm pour créer ou ouvrir un fichier de configuration du pack. Par convention, ce fichier est nommé databricks.yml. Au fur et à mesure de votre frappe, PyCharm vérifie la syntaxe et le format du schéma JSON et fournit des conseils de saisie semi-automatique de code.

IntelliJ IDEA Ultimate

Générez le fichier de schéma JSON de configuration du pack de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la sortie vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :
```
databricks bundle schema > bundle_config_schema.json
```
Configurez IntelliJ IDEA pour reconnaître le fichier de schéma JSON de configuration du pack, puis effectuez la mise en correspondance du schéma JSON en suivant les instructions fournies dans Configurer un schéma JSON personnalisé.
Utilisez IntelliJ IDEA pour créer ou ouvrir un fichier de configuration du pack. Par convention, ce fichier est nommé databricks.yml. Au fur et à mesure de votre frappe, IntelliJ IDEA vérifie la syntaxe et le format du schéma JSON et fournit des conseils de saisie semi-automatique de code.

Étape 3 : Convertir les paramètres du projet dbx en databricks.yml

Convertissez les paramètres du fichier .dbx/project.json de votre projet dbx en paramètres équivalents dans le fichier databricks.yml de votre pack. Pour plus d’informations, consultez Conversion des paramètres de projet dbx en databricks.yml.

Étape 4 : Convertir les paramètres de déploiement dbx en databricks.yml

Convertissez les paramètres du dossier conf de votre projet dbx en paramètres équivalents dans le fichier databricks.yml de votre pack. Pour plus d’informations, consultez Conversion des paramètres de déploiement dbx en databricks.yml.

Étape 5 : Valider le pack

Avant de déployer des artefacts ou d’exécuter un travail Azure Databricks, un pipeline Delta Live Tables ou un pipeline MLOps, vous devez vérifier que votre fichier de configuration de pack a une syntaxe correcte. Pour ce faire, exécutez la commande bundle validate à la racine du pack :

databricks bundle validate

Pour plus d’informations sur bundle validate, consultez Valider un bundle.

Étape 6 : Déployer le pack

Pour déployer des artefacts locaux spécifiés dans l’espace de travail distant, exécutez la commande bundle deploy à la racine du pack. Si aucune option de commande n’est spécifiée, la cible par défaut déclarée dans le fichier de configuration du pack est utilisée :

databricks bundle deploy

Pour déployer les artefacts dans le contexte d’une cible spécifique, spécifiez l’option -t (ou --target) ainsi que le nom de la cible déclaré dans le fichier de configuration du pack. Par exemple, pour une cible déclarée avec le nom development :

databricks bundle deploy -t development

Pour plus d’informations sur bundle deploy, consultez Déployer un bundle.

Conseil

Vous pouvez lier des travaux et des pipelines définis par bundle à des travaux et pipelines existants dans l’espace de travail Azure Databricks pour les synchroniser. Consultez Lier des ressources de bundle.

Étape 7 : Exécuter le pack

Pour exécuter un travail ou un pipeline spécifique, exécutez la commande bundle run à la racine du pack. Vous devez spécifier la tâche ou le pipeline déclaré dans le fichier de configuration du pack. Si l’option -t n’est pas spécifiée, la cible par défaut déclarée dans le fichier de configuration du pack est utilisée. Par exemple, pour exécuter un travail nommé hello_job dans le contexte de la cible par défaut :

databricks bundle run hello_job

Pour exécuter un travail nommé hello_job dans le contexte d’une cible déclarée avec le nom development :

databricks bundle run -t development hello_job

Pour plus d’informations sur bundle run, consultez Exécuter un bundle.

(Facultatif) Étape 8 : Configurer le pack pour CI/CD avec GitHub

Si vous utilisez GitHub pour CI/CD, vous pouvez utiliser GitHub Actions pour exécuter automatiquement les commandes databricks bundle deploy et databricks bundle run, en fonction d’événements de workflow GitHub spécifiques et d’autres critères. Consultez Exécuter un flux de travail CI/CD avec un pack de ressources Databricks et GitHub Actions.

Conversion des paramètres de projet dbx en databricks.yml

Pour dbx, les paramètres de projet sont par défaut dans un fichier nommé project.json dans le dossier .dbx du projet. Consultez Informations de référence sur le fichier projet.

Pour les packs, les configurations de pack sont par défaut dans un fichier nommé databricks.yml d dossier racine du pack. Consultez Configuration du pack de ressources Databricks.

Pour un fichier conf/project.json avec l’exemple de contenu suivant :

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

Le fichier databricks.yml correspondant est le suivant :

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Les objets suivants dans le fichier conf/project.json précédent de l’exemple ne sont pas pris en charge dans les fichiers databricks.yml et n’ont aucune solution de contournement :

inplace_jinja_support
storage_type

Les objets supplémentaires autorisés suivants dans les fichiers conf/project.json ne sont pas pris en charge dans les fichiers databricks.yml et n’ont aucune solution de contournement :

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Conversion des paramètres de déploiement dbx en databricks.yml

Pour dbx, les paramètres de déploiement sont par défaut dans un fichier au sein du dossier conf du projet. Consultez informations de référence sur le fichier de déploiement. Le fichier des paramètres de déploiement a par défaut un des noms de fichier suivants :

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

Pour les packs, les paramètres de déploiement sont par défaut dans un fichier nommé databricks.yml dans le dossier racine du pack. Consultez Configuration du pack de ressources Databricks.

Pour un fichier conf/deployment.yml avec l’exemple de contenu suivant :

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"