Aller au contenu principal
Dernière mise à jour le

Convertir un pipeline en projet de bundle

Vous pouvez convertir un pipeline existant en un projet Declarative Automation Bundles. Les bundles vous permettent de définir et de gérer votre configuration de traitement de données Databricks dans un fichier YAML unique à contrôle de source, ce qui facilite la maintenance et permet un déploiement automatisé vers les environnements cibles.

Pour un tutoriel qui utilise les commandes databricks pipelines pour créer un projet de pipelines, puis déploie et exécute un pipeline, consultez Développer des pipelines avec des bundles d’automatisation déclaratifs.

Présentation du processus de conversion​

Diagramme montrant les étapes spécifiques de conversion d'un pipeline existant en bundle

Les étapes à suivre pour convertir un pipeline existant en bundle sont :

  1. Assurez-vous d'avoir accès à un pipeline préalablement configuré que vous souhaitez convertir en bundle.
  2. Créez ou préparez un dossier (de préférence dans une hiérarchie gérée par la source) pour stocker le bundle.
  3. Générez une configuration pour le bundle à partir du pipeline existant, à l'aide de la CLI Databricks.
  4. Examinez la configuration du bundle générée pour vous assurer qu'elle est complète.
  5. Link the bundle au pipeline original.
  6. Déployez le pipeline vers un Workspace cible à l'aide de la configuration du bundle.

Exigences​

Avant de vous start, vous devez avoir :

Étape 1 : Mettre en place un dossier pour votre projet de bundle​

Vous devez avoir accès à un repository Git qui est configuré dans Databricks en tant que dossier Git. Vous créerez votre projet de bundle dans ce repository, ce qui appliquera le contrôle de code source et le rendra disponible à d'autres collaborateurs via un dossier Git dans le workspace Databricks correspondant. (Pour plus de détails sur les dossiers Git, consultez les dossiers Git Databricks.)

  1. Accédez à la racine du repository Git cloné sur votre machine locale.

  2. Dans un emplacement approprié de la hiérarchie des dossiers, créez un dossier spécifiquement pour votre projet de bundle. Par exemple :

    Bash
    mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle

  3. Modifiez votre répertoire de travail actuel en ce nouveau dossier. Par exemple :

    Bash
    cd ~/source/my-pipelines/ingestion/events/my-bundle

  4. Initialisez un nouveau bundle en exécutant :

    Bash
    databricks bundle init

    Répondez aux invites. Une fois terminée, vous disposerez d’un fichier de configuration de projet nommé databricks.yml dans le nouveau dossier d’accueil de votre projet. Ce fichier est requis pour le déploiement de votre pipeline à partir de la ligne de commande. Pour plus de détails sur ce fichier de configuration, consultez la configuration des Declarative Automation Bundles.

Étape 2 : Générer la configuration du pipeline​

À partir de ce nouveau répertoire dans l'arborescence des dossiers de votre repository Git cloné, exécutez la commande bundle generate de la CLI Databricks, en fournissant l'ID de votre pipeline comme <pipeline-id>:

Bash
databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

Lorsque vous exécutez la commande generate, un fichier de configuration de bundle est créé pour votre pipeline dans le dossier resources du bundle et tous les artefacts référencés sont téléchargés dans le dossier src. Le --profile (ou l'indicateur -p) est facultatif, mais si vous avez un profil de configuration Databricks spécifique (défini dans votre fichier .databrickscfg créé lors de l'installation de l'interface de ligne de commande Databricks) que vous préférez utiliser au lieu du profil default, fournissez-le dans cette commande. Pour plus d'informations sur les profils de configuration Databricks, consultez les profils de configuration Databricks.

astuce

Si vous avez un projet Spark Declarative Pipelines (SDP) existant (il contient un fichier spark-pipeline.yml), vous pouvez copier ce projet de pipeline dans le dossier src du bundle, puis utiliser la commande databricks pipelines generate pour générer la configuration du bundle. Voir générer des pipelines Databricks.

Étape 3 : examiner les fichiers du projet groupé​

Lorsque la commande bundle generate est terminée, elle aura créé deux nouveaux dossiers :

  • resources est le sous-répertoire du projet qui contient les fichiers de configuration du projet.
  • src est le dossier de projet où sont stockés les fichiers source, tels que les queries et les notebooks.

La commande crée également des fichiers supplémentaires :

  • *.pipeline.yml sous le sous-répertoire resources. Ce fichier contient la configuration et les paramètres spécifiques de votre pipeline.
  • Fichiers source tels que les requêtes SQL sous le sous-répertoire src, copiés de votre pipeline existant.
├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Étape 4 : liez le pipeline de bundle à votre pipeline existant​

Vous devez link, ou lier , la définition du pipeline dans le bundle à votre pipeline existant afin de le maintenir à jour à mesure que vous apportez des modifications. Pour ce faire, exécutez la commande de liaison de déploiement de bundle de la CLI Databricks :

Bash
databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> est le nom du pipeline. Le nom doit être identique à la valeur de chaîne préfixée du nom de fichier pour la configuration du pipeline dans votre nouveau répertoire resources. Par exemple, si vous avez un fichier de configuration de pipeline nommé ingestion_data_pipeline.pipeline.yml dans votre dossier resources, vous devez fournir ingestion_data_pipeline comme nom de pipeline.

<pipeline-ID> est l'ID de votre pipeline. Il est identique à celui que vous avez copié dans le cadre des exigences de ces instructions.

Étape 5 : Déployer votre pipeline à l'aide de votre nouveau bundle​

Maintenant, déployez votre bundle de pipeline vers votre workspace cible à l'aide de la CLI Databricks commande de déploiement de bundle:

Bash
databricks bundle deploy --target <target-name> --profile <profile-name>

L'indicateur --target est obligatoire et doit être défini sur une chaîne de caractères qui correspond à un nom de workspace cible configuré, tel que development ou production.

Si cette commande réussit, vous disposez maintenant de la configuration de votre pipeline dans un projet externe qui peut être chargé dans d'autres Workspaces et exécuté, et facilement partagé avec d'autres utilisateurs Databricks de votre compte.

Promouvoir entre les environnements avec des cibles​

Un bundle définit des environnements de déploiement nommés targets dans databricks.yml, chacun pointant vers son propre workspace, son catalogue et ses valeurs de variable. Les cibles sont le moyen de promouvoir le même pipeline à travers les environnements de développement, de préproduction et de production, en déployant un code source identique dans chaque environnement successif sans le modifier :

YAML
bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Le mode que vous définissez sur chaque cible modifie son comportement de déploiement :

  • mode: development marque une cible comme étant un déploiement personnel et temporaire. Les Ressources reçoivent un préfixe [dev username] et les plannings sont suspendus par default, afin que votre travail n'affecte personne d'autre.
  • mode: production désactive ces safety default. Combiné avec run_as, cela vous permet d'exécuter le pipeline en tant que service principal plutôt qu'en tant que compte individuel, afin que les exécutions ne soient pas interrompues lorsque quelqu'un quitte l'équipe ou change de rôle. Databricks recommande un service principal pour la staging et la production. service_principal_name utilise l'ID d'application du service principal, et non son nom d'affichage. Vous pouvez récupérer l'ID d'application depuis la page du service principal dans vos paramètres d'administration de workspace.

Pour l'ensemble des comportements de mode, consultez les modes de déploiement des Declarative Automation Bundles et spécifiez une identité d'exécution pour un workflow de Declarative Automation Bundles.

Pour promouvoir, déployez le même bundle vers chaque cible tour à tour, en vérifiant à chaque étape :

Bash
databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Plutôt que de coder en dur les noms de catalogue ou les chemins sources par environnement dans votre code de transformation, transmettez les valeurs depuis la cible afin que la même source s’exécute sans modification partout. La façon dont vous les définissez dépend de votre langue source. Les paramètres du pipeline s’appliquent uniquement au code source SQL. Pour le code source Python, utilisez le champ configuration du pipeline et lisez les valeurs avec spark.conf.get():

YAML
resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Pour en savoir plus sur la paramétrisation du code de pipeline, consultez Utiliser des paramètres avec des pipelines.

Configurer CI/CD​

Comme un pipeline converti est entièrement défini sous forme de bundle (YAML et fichiers sources dans Git), la configuration des fonctionnalités d’intégration et de livraison continues (CI/CD) pour celui-ci implique l’exécution des commandes du bundle à partir d’un système CI tel que GitHub Actions ou Azure DevOps. Sur chaque requête Pull, une bonne exécution de référence s’exécute :

  1. pytest par rapport à vos fonctions de transformation testables unitairement. Voir Tests unitaires pour les pipelines.
  2. databricks bundle validate --target <env> pour détecter les erreurs de configuration.
  3. Optionnellement, un databricks bundle run dans une cible temporaire pour tester les attentes par rapport à l'échantillon de données.

Le flux de travail GitHub Actions suivant se déploie pour staging lors de la Merge vers main, en utilisant la fédération OpenID Connect (OIDC) au lieu d’un jeton stocké :

YAML
# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Protégez le déploiement en production par une approbation manuelle (par exemple, un second job qui nécessite une approbation d’environnement GitHub, ou une étape distincte dans Azure DevOps) afin qu’une personne approuve explicitement chaque promotion. Le job de production exécute databricks bundle deploy --target prod en utilisant un Service Principal limité au workspace de production. Pour en savoir plus, consultez CI/CD sur Databricks.

Dépannage​

Problème

Solutions

Erreur « databricks.yml introuvable » lors de l’exécution bundle generate

Actuellement, la commande bundle generate ne crée pas automatiquement le fichier de configuration du bundle (databricks.yml). Vous devez créer le fichier à l'aide de databricks bundle init ou manuellement.

Les paramètres de pipeline existants ne correspondent pas aux valeurs de la configuration YAML du pipeline généré.

L'ID du pipeline n'apparaît pas dans le fichier YML de configuration du bundle. Si vous remarquez d'autres paramètres manquants, vous pouvez les appliquer manuellement.

Problème

Solutions

Erreur « databricks.yml introuvable » lors de l’exécution bundle generate

Actuellement, la commande bundle generate ne crée pas automatiquement le fichier de configuration du bundle (databricks.yml). Vous devez créer le fichier à l'aide de databricks bundle init ou manuellement.

Les paramètres de pipeline existants ne correspondent pas aux valeurs de la configuration YAML du pipeline généré.

L'ID du pipeline n'apparaît pas dans le fichier YML de configuration du bundle. Si vous remarquez d'autres paramètres manquants, vous pouvez les appliquer manuellement.

Conseils pour la réussite​

  • Utilisez toujours le contrôle de version. Si vous n'utilisez pas les dossiers Git Databricks, stockez les sous-répertoires et les fichiers de votre projet dans un repository Git ou un autre système de fichiers sous gestion de version.
  • Testez votre pipeline dans un environnement hors production (tel qu'un environnement « développement » ou « test ») avant de le déployer dans un environnement de production. Il est facile d'introduire une mauvaise configuration par accident.

Ressources supplémentaires​

Pour plus d'informations sur l'utilisation de bundles pour définir et gérer le traitement des données, voir :

Sur cette page