Migrer de dbx vers des packs

Importante

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.

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 compilation dans la section build d'un fichier de projet deployment.yml.

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

Synchroniser, déployer et exécuter du code

dbx permet de charger du code séparément de la génération de ressources d’espace de travail telles que les travaux Lakeflow.

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 que pour commencer une dbx migration de projet, vous conservez votre dbx projet dans son dossier d’origine et que vous disposez d’un dossier vide distinct dans lequel vous copiez le contenu de votre projet d’origine dbx . 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 avec vos espaces de travail Azure Databricks cibles, par exemple en utilisant l’authentification par jeton d’accès personnel (déconseillée). 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 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 groupé, mais pour vérifier la syntaxe et la mise en forme du fichier et fournir des indicateurs de saisie semi-automatique du 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 Professionnel

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 complétion 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 suggestions de complétion de code.

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

Convertissez les paramètres dans le fichier dbx de votre projet en paramètres équivalents dans le fichier .dbx/project.json de votre bundle. 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 dbx de votre projet conf en les paramètres équivalents dans le fichier databricks.yml de votre bundle. 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 : ou un pipeline MLOps, vous devez vous assurer que votre fichier de configuration de bundle est correct sur le plan syntaxique. Pour ce faire, exécutez la commande bundle validate à la racine du pack :

databricks bundle validate

Pour plus d’informations sur bundle validate, consultez databricks bundle validate.

É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 comme déclaré dans le fichier de configuration du bundle. 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 databricks bundle deploy.

Conseil

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

É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 databricks bundle run.

(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 GitHub Actions.

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

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

Pour les bundles, les configurations de bundle sont par défaut dans un fichier nommé databricks.yml dans le dossier racine du bundle. 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 du fichier précédent conf/project.json de cet exemple ne sont pas pris en charge dans databricks.yml les fichiers 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 dans le dossier du conf projet. Consultez référence du 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 bundles, les paramètres de déploiement sont par défaut dans un fichier nommé databricks.yml dans le dossier racine du bundle. 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'