Aller au contenu principal
Dernière mise à jour le

Migrer de dbx vers des bundles

important

Databricks recommande d'utiliser les Declarative Automation Bundles au lieu de dbx par Databricks Labs. Les articles associés concernant dbx ont été retirés et pourraient ne pas être mis à jour.

Cet article décrit comment migrer les projets pour dbx de Databricks Labs vers les Bundles d'automatisation déclaratifs. Consultez Introduction à dbx par Databricks Labs et Que sont les Declarative Automation Bundles ?.

Avant de migrer, prenez note des limitations et des comparaisons de fonctionnalités suivantes entre dbx de Databricks Labs et les Declarative Automation Bundles.

Comparaisons de fonctionnalités​

Avant de migrer, notez comment les fonctionnalités suivantes pour dbx par Databricks Labs sont implémentées dans Declarative Automation Bundles.

Templates et projets​

dbx fournir un support pour le templating Jinja. Vous pouvez inclure des Template Jinja dans la configuration du déploiement et transmettre des variables d'environnement soit en ligne, soit par le biais d'un fichier de variables. Bien que non recommandé, dbx offre également un support expérimental pour les fonctions utilisateur personnalisées.

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

Gestion de la création​

dbx fournit un support de build via pip wheel, Poetry et Flit. Les utilisateurs peuvent spécifier l'option de build dans la section build du fichier deployment.yml d'un projet.

Les bundles permettent aux utilisateurs de créer, déployer et exécuter des fichiers Python wheel. Les utilisateurs peuvent exploiter l'entrée whl intégrée dans le fichier databricks.yml d'un bundle.

Synchroniser, déployer et exécuter le code​

dbx permet d'upload du code séparément de la génération de Ressources de Workspace telles que les Lakeflow Jobs.

Les bundles effectuent l'upload de code et créent ou mettent à jour des Ressources Workspace en même temps. Cela simplifie les déploiements et évite les conditions de blocage pour les Jobs déjà en cours.

Migrez un projet dbx vers un bundle​

Après avoir pris note des limitations précédentes et des comparaisons de fonctionnalités entre dbx de Databricks Labs et les Declarative Automation Bundles, vous êtes prêt à migrer de dbx vers les bundles.

Databricks vous recommande, pour commencer une migration de projet dbx, de conserver votre projet dbx dans son dossier d’origine et de disposer d’un dossier vierge distinct dans lequel vous copiez le contenu de votre projet dbx d’origine. Ce dossier distinct sera votre nouveau bundle. Vous pourriez rencontrer des problèmes inattendus si vous commencez à convertir votre projet dbx dans son dossier d’origine en un bundle, puis faites des erreurs ou voulez start over depuis le début,

Étape 1 : Installer et configurer la CLI Databricks​

Les bundles d'automatisation 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é la version 0.218.0 ou supérieure de Databricks CLI, passez à l'étape 2.

remarque

Les bundles ne sont pas compatibles avec les versions 0.18 et antérieures de Databricks CLI.

  1. Installez ou mettez à jour la CLI Databricks à la version 0,218.0 ou supérieure. Consultez Installer ou mettre à jour la Databricks CLI.
  2. Configurez le CLI Databricks pour l'authentification avec vos workspaces Databricks cibles, par exemple en utilisant l'Authentification par jeton d'accès personnel (héritée). Pour d'autres types d'authentification Databricks, consultez Authentification pour le CLI Databricks.

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

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 de bundle, mais aussi pour vérifier la syntaxe et le formatage du fichier et fournir des suggestions d'achèvement de code, comme suit.

  1. Ajoutez la prise en charge du serveur de langage YAML à Visual Studio Code, par exemple en installant l'extension YAML depuis le Visual Studio Code Marketplace.

  2. Générez le fichier de schéma JSON de configuration de bundle en utilisant l'interface CLI de 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 actuel, comme suit :

    Bash
    databricks bundle schema > bundle_config_schema.json

  3. Utilisez Visual Studio Code pour créer ou ouvrir un fichier de configuration de bundle dans le répertoire actuel. Par convention, ce fichier est nommé databricks.yml.

  4. Ajoutez le commentaire suivant au début du fichier de configuration de votre bundle :

    YAML
    # 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 chemin différent, remplacez bundle_config_schema.json par le chemin complet de votre fichier de schéma.

  1. Utilisez les fonctionnalités du 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.

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

Convertissez les paramètres de votre fichier .dbx/project.json du projet dbx aux paramètres équivalents de votre fichier databricks.yml du bundle. Pour plus de détails, 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 aux paramètres équivalents du fichier databricks.yml de votre bundle. Pour plus de détails, consultez Conversion des paramètres de déploiement dbx en databricks.yml.

Étape 5 : Valider le bundle​

Avant de déployer des artefacts ou d'exécuter un Databricks Job ou un MLOps pipeline, vous devez vous assurer que votre fichier de configuration de bundle est syntaxiquement correct. Pour ce faire, exécutez la commande bundle validate à partir de la racine du bundle :

Bash
databricks bundle validate

Pour des informations sur bundle validate, consultez databricks bundle validate.

Étape 6 : Déployer le bundle​

Pour déployer des artefacts locaux spécifiés vers le workspace distant, exécutez la commande bundle deploy depuis la racine du bundle. Si aucune option de commande n'est spécifiée, la cible par default déclarée dans le fichier de configuration du bundle est utilisée :

Bash
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 tel que déclaré dans le fichier de configuration du bundle. Par exemple, pour une cible déclarée avec le nom development:

Bash
databricks bundle deploy -t development

Pour plus d'informations sur bundle deploy, consultez le déploiement de bundle databricks.

astuce

Vous pouvez Link des jobs et des pipelines définis par des bundles à des jobs et des pipelines existants dans le Workspace Databricks pour les maintenir synchronisés. Voir la liaison de déploiement d'ensemble Databricks.

Étape 7 : Exécutez le bundle​

Pour exécuter un Job ou un pipeline spécifique, exécutez la commande bundle run à partir de la racine du bundle. Vous devez spécifier le job ou le pipeline déclaré dans le fichier de configuration du bundle. Si l'option -t n'est pas spécifiée, la cible default telle que déclarée dans le fichier de configuration du bundle est utilisée. Par exemple, pour exécuter un job nommé hello_job dans le contexte de la cible default :

Bash
databricks bundle run hello_job

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

Bash
databricks bundle run -t development hello_job

Pour information sur bundle run, consultez databricks bundle run.

(Facultatif) Étape 8 : configurez le bundle pour le CI/CD avec GitHub​

Si vous utilisez GitHub pour le 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 workflow GitHub spécifiques et d'autres critères. See GitHub Actions.

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

Pour dbx, les paramètres du projet sont par default dans un fichier nommé project.json dans le dossier .dbx du projet. Voir référence de fichier de projet.

Pour les bundles, les configurations des bundles sont par default dans un fichier nommé databricks.yml au sein du dossier racine du bundle. Consultez la configuration des Declarative Automation Bundles.

Pour un fichier conf/project.json avec le contenu d'exemple suivant :

JSON
{
  "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 :

YAML
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 conf/project.json précédent de cet exemple ne sont pas pris en charge dans les fichiers databricks.yml et ne disposent d’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 pas de solutions 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 default dans un fichier au sein du dossier conf du projet. Consultez la référence du fichier de déploiement. Le fichier de paramètres de déploiement a par default l'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 default dans un fichier nommé databricks.yml au sein du dossier racine du bundle. Consultez la configuration des Declarative Automation Bundles.

Pour un fichier conf/deployment.yml avec le contenu d'exemple suivant :

YAML
build:
  python: 'pip'

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

Le fichier databricks.yml correspondant est le suivant :

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

targets:
  default:
    workspace:
      # See an example "workspace" mapping in the preceding section.
    resources:
      jobs:
        workflow1:
          tasks:
            - task_key: task1
              python_wheel_task:
                package_name: some-pkg
                entry_point: some-ep

L’objet suivant dans le fichier conf/deployment.yml précédent de cet exemple n’est pas pris en charge dans les fichiers databricks.yml et n’a pas de solutions de contournement :

Les objets et fonctionnalités supplémentaires autorisés suivants dans les fichiers conf/deployment.yml ne sont pas pris en charge dans les fichiers databricks.yml et n'ont pas de solutions de contournement, sauf indication contraire :

  • access_control_list
  • custom (utilisez des ancres YAML standard à la place)
  • deployment_config
  • Format Lakeflow Jobs 2.0 (utilisez plutôt le format Jobs 2.1)
  • dbx Fonctionnalités Jinja
  • Propriétés basées sur le nom
Sur cette page