Migrer de dbx vers des packs

Importante

Databricks vous recommande d’utiliser des Bundles d'Automatisation Déclaratifs au lieu de 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 Databricks Labs vers des offres groupées d’automatisation déclarative. Consultez Présentation de dbx by Databricks Labs et Qu’est-ce que les bundles Automation déclaratifs ?.

Avant de migrer, notez les limitations et comparaisons de fonctionnalités suivantes entre dbx Databricks Labs et les Paquets d'Automation Déclaratifs.

Comparaison de fonctionnalités

Avant de migrer, prenez note de la manière dont les fonctionnalités de dbx par Databricks Labs sont implémentées dans les bundles d'automatisation déclaratifs.

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 offres groupées permettent aux utilisateurs de générer, déployer et exécuter des fichiers de roue 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 précédentes et les comparaisons de fonctionnalités entre dbx par Databricks Labs et les bundles d'Automation déclaratifs, vous êtes prêt à migrer depuis dbx vers les bundles.

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 Automation déclaratifs 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 de Azure Databricks cibles, par exemple en utilisant Authentification par jeton d’accès (hérité). Pour d’autres types d’authentification Azure Databricks, consultez Authentication 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 utiliser votre IDE non seulement 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 de bundle à l’aide de l’interface CLI Databricks pour exécuter la bundle schema commande et redirigez 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 groupé dans le répertoire actif. 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 de bundle se trouve dans un autre chemin, remplacez bundle_config_schema.json par le chemin complet de 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 de bundle à l’aide de l’interface CLI Databricks pour exécuter la bundle schema commande et redirigez 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 de bundle à l’aide de l’interface CLI Databricks pour exécuter la bundle schema commande et redirigez 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 ou un pipeline MLOps, vous devez vous assurer que votre fichier de configuration de bundle est syntaxiquement correct. 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 des pipelines définis par l’offre groupée à 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 bundle pour CI/CD avec GitHub

Si vous utilisez GitHub pour CI/CD, vous pouvez utiliser GitHub Actions pour exécuter les commandes databricks bundle deploy et databricks bundle run automatiquement, en fonction d’événements de flux de travail 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 référence de fichier du 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 la configuration des Bundles d'Automation déclaratifs.

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 la configuration des Bundles d'Automation déclaratifs.

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'