Convertir un pipeline en projet groupé

Vous pouvez convertir un pipeline existant en projet Declarative Automation Bundles . Les offres groupées vous permettent de définir et de gérer votre configuration de traitement des données Azure Databricks dans un seul fichier YAML contrôlé par la source qui facilite la maintenance et permet un déploiement automatisé dans des environnements cibles.

Pour un didacticiel qui utilise databricks pipelines les commandes pour créer un projet de pipelines, puis pour déployer et exécuter un pipeline, consultez Développer des pipelines avec des bundles d'automatisation déclaratifs.

Vue d’ensemble du processus de conversion

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

1. Vérifiez que vous avez accès à un pipeline précédemment configuré que vous souhaitez convertir en bundle.
2. Créez ou préparez un dossier (de préférence dans une hiérarchie contrôlée par la source) pour stocker le bundle.
3. Générez une configuration pour l’offre groupée à partir du pipeline existant, à l’aide de l’interface CLI Databricks.
4. Passez en revue la configuration de bundle générée pour vous assurer qu’elle est terminée.
5. Lier le bundle au pipeline d’origine.
6. Déployez le pipeline sur un espace de travail cible à l’aide de la configuration du bundle.

Spécifications

Avant de commencer, vous devez avoir :

• L’interface CLI Databricks installée sur votre ordinateur de développement local. Databricks CLI version 0.218.0 ou ultérieure est nécessaire pour utiliser des bundles d'automatisation déclarative.
• l’ID d’un pipeline déclaratif existant que vous allez gérer avec un bundle. Pour savoir comment obtenir cet ID, consultez Obtenir une définition de pipeline existante à l’aide de l’interface utilisateur.
• Autorisation pour l'espace de travail Azure Databricks où le pipeline existant fonctionne. Pour configurer l’authentification et l’autorisation pour vos appels d’interface CLI Databricks, consultez Autoriser l’accès aux ressources Azure Databricks.
• Pour obtenir le jeu complet de privilèges requis pour créer, exécuter, actualiser et afficher des pipelines et leur sortie, consultez Gérer les identités, les autorisations et les privilèges des pipelines.

Étape 1 : Configurer un dossier pour votre projet groupé

Vous devez avoir accès à un référentiel Git configuré dans Azure Databricks en tant que dossier Git. Vous allez créer votre projet groupé dans ce référentiel, qui applique le contrôle de code source et le rendre disponible pour d’autres collaborateurs via un dossier Git dans l’espace de travail Azure Databricks correspondant. (Pour plus d’informations sur les dossiers Git, consultez dossiers Git Azure Databricks.)

1. Accédez à la racine du référentiel Git cloné sur votre ordinateur local.

2. À un emplacement approprié dans la hiérarchie des dossiers, créez un dossier spécifiquement pour votre projet groupé. Par exemple:

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

3. Remplacez votre répertoire de travail actuel par ce nouveau dossier. Par exemple:

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

4. Initialisez un nouveau bundle en exécutant :

   databricks bundle init
   

   Répondez aux invites. Une fois l’opération terminée, vous disposez 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 d’informations sur ce fichier de configuration, consultez Configuration des bundles d'automatisation déclarative.

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

À partir de ce nouveau répertoire dans l’arborescence de dossiers de votre dépôt Git cloné, exécutez la commande Databricks CLI de génération du paquet, en fournissant l’ID de votre pipeline <pipeline-id>.

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

Lorsque vous exécutez la generate commande, elle crée un fichier de configuration groupé pour votre pipeline dans le dossier du resources bundle et télécharge tous les artefacts référencés dans le src dossier. Le --profile (ou -p l’indicateur) est facultatif, mais si vous avez un profil de configuration Databricks spécifique (défini dans votre .databrickscfg fichier créé lorsque vous avez installé l’interface CLI Databricks) que vous préférez utiliser au lieu du profil par défaut, fournissez-le dans cette commande. Pour plus d’informations sur les profils de configuration Databricks, consultez profils de configuration Azure Databricks.

Étape 3 : Passer en revue les fichiers projet groupés

Une fois la commande bundle generate terminée, elle a créé deux nouveaux dossiers :

• resources est le sous-répertoire de projet qui contient des fichiers de configuration de projet.
• src est le dossier du projet dans lequel les fichiers sources, tels que les requêtes et les notebooks, sont stockés.

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

• *.pipeline.yml dans le sous-répertoire resources. Ce fichier contient la configuration et les paramètres spécifiques de votre pipeline.
• Fichiers sources tels que les requêtes SQL dans le sous-répertoire src, copiés depuis 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 : Lier le pipeline du bundle à votre pipeline existant

Vous devez associer (ou lier) la définition du pipeline dans le bundle à votre pipeline existant afin de le maintenir à jour au fur et à mesure que vous apportez des modifications. Pour ce faire, exécutez la commande Databricks CLI bundle deployment bind :

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

<pipeline-name> est le nom du pipeline. Ce nom doit être identique à la valeur de chaîne préfixée du nom de fichier de 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 en tant que nom de pipeline.

<pipeline-ID> correspond à l’ID de votre pipeline. Il est identique à celui que vous avez copié dans le cadre des conditions requises pour ces instructions.

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

À présent, déployez votre bundle de pipelines sur votre espace de travail cible à l’aide de la commande de déploiement du bundle Cli Databricks :

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

L’indicateur --target est requis et doit être défini sur une chaîne qui correspond à un nom d’espace de travail 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 espaces de travail et exécutés, et facilement partagé avec d’autres utilisateurs Azure Databricks dans votre compte.

Promouvoir entre les environnements à l’aide de cibles

Un ensemble définit des environnements de déploiement nommés appelés cibles dans databricks.yml, chacun pointant vers ses propres valeurs d’espace de travail, catalogue et variable. Les cibles vous permettent de faire passer le même pipeline par les environnements de développement, de préproduction et de production, en déployant le même code source dans chaque environnement successif sans le modifier :

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 indique qu’une cible est un déploiement personnel et ponctuel. Les ressources reçoivent un [dev username] préfixe et les plannings sont mis en pause par défaut, donc votre travail n’affecte personne d’autre.
• mode: production désactive ces paramètres de sécurité par défaut. Combiné à run_as, cela vous permet de gérer le pipeline en tant que principal de service plutôt que comme compte individuel, afin que les runs ne se rompent pas quand quelqu’un quitte l’équipe ou change de rôle. Azure Databricks recommande un principal de service pour la préproduction et la production. service_principal_name prend l’ID de l’application du principal de service, et non son nom affiché. Vous pouvez récupérer l’ID de l’application depuis la page du principal du service dans les paramètres d’administration de votre espace de travail.

Pour l’ensemble complet des comportements de mode, voir Déclarative Automation Bundles modes de déploiement et Spécifier un identité d’exécution pour un flux de travail Declarative Automation Bundles.

Pour promouvoir, déployez le même paquet à chaque cible à tour de rôle, en vérifiant à chaque étape :

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 catalogues ou les chemins de source par environnement dans votre code de transformation, faites entrer les valeurs depuis la cible afin que la même source s’exécute partout sans modification. La façon dont vous les définissez dépend de votre langue d’origine. Les paramètres du pipeline s’appliquent uniquement au code source SQL. Pour le code source Python, utilisez le champ pipeline configuration et lisez les valeurs avec spark.conf.get():

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 des pipelines, voir Utiliser les paramètres avec les pipelines.

Configurez CI/CD

Parce qu’un pipeline converti est défini entièrement comme un bundle (YAML plus fichiers sources dans Git), mettre en place une intégration continue et une livraison continue (CI/CD) implique d’exécuter les commandes bundle depuis un système CI tel que GitHub Actions ou Azure DevOps. Pour chaque requête pull, une bonne base de référence exécute :

1. pytest contre vos fonctions de transformation testables par des tests unitaires. Consultez tests unitaires pour les pipelines.
2. databricks bundle validate --target <env> pour détecter les erreurs de configuration.
3. Éventuellement, un databricks bundle run dans une cible temporaire pour vérifier les résultats attendus sur des données d’exemple.

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

# .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

Verrouillez le déploiement en production derrière une approbation manuelle (par exemple, un second poste nécessitant une approbation de l’environnement GitHub, ou une étape séparée dans Azure DevOps) afin qu’une personne approuve explicitement chaque promotion. Le travail de production exécute databricks bundle deploy --target prod à l’aide d’un principal de service associé à l’espace de travail de production. Pour en savoir plus, voir CI/CD sur Azure Databricks.

Résolution des problèmes

Conseils pour la réussite

• Utilisez toujours le contrôle de version. Si vous n’utilisez pas de dossiers Databricks Git, stockez les sous-répertoires et fichiers de votre projet dans un référentiel git ou un autre système de fichiers contrôlé par la version.
• Testez votre pipeline dans un environnement hors production (par exemple, un environnement de « développement » ou de « 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 d’offres groupées pour définir et gérer le traitement des données, consultez :

• Que sont les ensembles d'automatisation déclarative ?
• Développez des pipelines avec des bundles d'Automatisation déclaratifs. Cette rubrique traite de la création d’un bundle pour un nouveau pipeline plutôt que pour un pipeline existant, avec des fichiers sources à version contrôlée que vous fournissez pour le traitement.