Bonnes pratiques du développeur sur Databricks

Cette page fournit les meilleures pratiques pour votre cycle de vie de Data Engineering et de développement, y compris le contrôle de version, la gestion de l'environnement, les outils de développement et les déploiements gérés.

Contrôle de source

Contrôler la version de tous les fichiers

L'automatisation déclarative repose sur l'idée que si quelque chose n'est pas sous gestion de versions, cela n'existe pas. Par conséquent, Databricks recommande de gérer les versions de presque tous les fichiers, notamment :

• Tous les Notebooks et fichiers sources (.py, .sql)
• Fichiers de configuration de bundle (databricks.yml et remplacements YAML spécifiques à l'environnement)

Cependant, ne commit pas :

• Générez des artefacts, tels que les fichiers .jar ou .whl. Au lieu de cela, upload les binaires compilés vers les volumes Unity Catalog pendant l'intégration continue. Consultez upload JAR.
• Jetons ou identifiants. Utilisez une gestion des secrets au niveau du workspace, basée sur un gestionnaire de secrets cloud (tel que AWS Secrets Manager ou Azure Key Vault), et synchronisez les valeurs dans les Secret Scope Databricks. Voir Gestion des secrets.
• Exemples de données locales et fichiers avec PII. Utilisez .gitignore pour les exclure.

Repository unique

Databricks vous recommande d'utiliser un seul repository pour tout votre code (code source et fichiers de configuration), car cela facilite la collaboration, le partage du code et des bonnes pratiques, tant pour les humains que pour l'IA. Si vous avez plusieurs bundles pour des cycles de vie de déploiement séparés, gardez-les dans un seul repository.

La seule exception à la recommandation d'un seul repository se trouve dans les secteurs d'activité réglementés où plusieurs repository sont nécessaires à des fins de confidentialité.

Stratégie de branchement basée sur le tronc

Pour minimiser les conflits de Merge et s'assurer que la Branch principale est toujours dans un état déployable, utilisez une stratégie de branchement basée sur un tronc commun.

Un workflow simple serait :

1. Développez en local ou dans le Workspace et déployez vers un Workspace de développement Databricks pour tester les modifications.
2. Créez une branch de fonctionnalité à courte durée de vie pour les mises à jour du contrôle de version et synchronisez régulièrement vos modifications locales ou de Workspace.
3. Une fois les tests terminés, Merge la Branch de fonctionnalités dans la Branch principale.
4. CI/CD déploie automatiquement la Branch principale vers un Workspace de staging et les tests automatisés sont déclenchés.
5. Lorsque les tests et les vérifications de staging réussissent, le CI/CD déploie la main Branch vers un workspace de production.

Ces étapes sont décrites dans le diagramme suivant :

Configuration du Workspace

Isoler les environnements de workspace

Isolez les environnements de Workspace pour minimiser l'impact d'un déploiement échoué. Par exemple :

• Petites équipes (jusqu'à 5 data engineers) : Start avec deux Workspaces (développement et production) dans un seul compte cloud.
• Équipes en croissance (plus de 5 data engineers) : Passer à trois workspaces (développement, préproduction et production). L'environnement de préproduction doit être fonctionnellement représentatif de la production — même configuration de bundle, schéma et intégrations critiques — même s'il est réduit.
• **Secteurs d'activité réglementés** (banque, santé, défense) : Isolez physiquement les Workspaces et les comptes cloud pour prévenir les fuites de données. La gestion de l'isolation via les limites IAM et Unity Catalog au sein d'un seul compte est possible mais offre une posture de sécurité moins robuste.

Pour les Workspace de production, utilisez le Serverless compute avec des politiques réseau si possible. Sinon, configurez les comptes cloud pour utiliser des sous-réseaux privés ou des réseaux virtuels (VNet) avec une sortie étroitement contrôlée et des contrôles de sécurité réseau.

Pour plus d'informations, consultez Stratégies réseau basées sur le contexte.

Isoler le stockage des données

• Utilisez un seul métastore Unity Catalog et créez des catalogues distincts pour le développement, la pré-production (le cas échéant) et la production, reflétant l'agencement de votre Workspace Layout.
• Utilisez des schémas personnels pour les développeurs individuels pour les catalogues de développement et de préproduction (hors production).
• Liez le catalogue de production en mode ISOLATED uniquement au workspace de production. La définition du mode d'isolation d'un catalogue sur ISOLATED garantit que les données de production sont inaccessibles depuis les environnements de développement ou de préproduction, même si une identité est mal configurée.
• Réservez des métastores, des comptes ou des régions distincts uniquement pour les organisations ayant des exigences réglementaires, de souveraineté des données ou multi-régionales que l'isolation au niveau du catalogue ne peut pas satisfaire.

Traiter les métadonnées de table et de colonne comme du code

Considérez les commentaires de table et de colonne comme faisant partie de votre code. Conservez-les dans .sql fichiers parallèlement à vos définitions de Declarative Automation Bundles, et déployez-les via un Job de métadonnées afin que des définitions précises et orientées métier soient toujours disponibles. Rédigez des commentaires décrivant ce qu'une ligne représente, les unités et les valeurs valides en langage simple plutôt que de répéter le nom de la colonne.

Configurez les schémas personnels

Pendant le développement, configurez les bundles pour utiliser un schéma personnel par utilisateur, par exemple dev_${user_name}. Cela empêche les développeurs d'écraser les tables des autres dans un Workspace partagé.

Utiliser le compute serverless

Utilisez le compute Serverless pour simplifier la gestion des clusters et optimiser les coûts. Voir Se connecter au compute Serverless.

Recommandations CI/CD

Declarative Automation Bundles pour CI/CD

Les Declarative Automation Bundles (anciennement appelés Databricks Asset Bundles) offrent une approche puissante et unifiée pour gérer le code, les workflows et l'infrastructure au sein de l'écosystème Databricks et sont recommandés pour vos pipelines CI/CD.

Pour plus de détails sur l'utilisation de bundles pour les workflows CI/CD, consultez workflows CI/CD sur Databricks.

Pour plus d'informations sur les Declarative Automation Bundles, consultez Que sont les Declarative Automation Bundles ?.

Utiliser Terraform uniquement pour les Ressources externes

Utilisez Terraform pour définir les ressources suivantes :

• Ressources au niveau du cloud et externes
• Actions d'administrateur que les utilisateurs non privilégiés ne devraient pas effectuer, telles que le provisionnement du Workspace ou la configuration du réseau cloud

Utilisez les Declarative Automation Bundles pour toutes les autres ressources Databricks.

Gestion du bundle

Créer de petits bundles

Databricks recommande de développer des ensembles petits et ciblés plutôt qu’un seul grand ensemble.

• Mettez tout ce qu'une seule équipe possède dans un seul paquet.
• Testez et déployez via le même pipeline CI/CD qui partage le même cycle de vie et la même cadence de publication.
• Chaque bundle doit couvrir tous les environnements pour un projet donné (développement, préproduction, production) plutôt que d'utiliser des bundles séparés par environnement.

Créer des bundles séparés pour :

• Différents produits ou domaines, par exemple : « analytique de facturation » et « détection des fraudes »
• Limites de propriété ou d’autorisation différentes
• Charges de travail avec des cycles de vie clairement différents
• Cas où vous avez besoin d'une promotion ou d'une restauration indépendante

Utilisez sync.paths pour synchroniser les dossiers partagés

Lors de la gestion de plusieurs bundles dans un seul repository, utilisez sync.paths pour synchroniser les dossiers partagés depuis l'extérieur de la racine du bundle. Cela permet à différents projets de partager un dossier de bibliothèque commun, tel que ../common, tout en conservant des identités de déploiement distinctes.

Modéliser les dépendances inter-bundles dans CI/CD

Lorsque le bundle B dépend d'actifs publiés par le bundle A, modélisez cette dépendance dans votre couche CI/CD ou d'orchestration plutôt que de fusionner les deux en un seul bundle.

• Faites du flux de travail de déploiement et de publication du Bundle A un prérequis explicite pour le Bundle B. Connectez votre pipeline de sorte que le Bundle B ne start qu'après la réussite du déploiement du Bundle A et que toutes les vérifications de validation requises sont réussies.
• Transmettez les identificateurs ou les emplacements des ressources publiées en tant qu'entrées de pipeline, et échouez rapidement si les ressources en amont sont manquantes. Cela garantit que le Bundle B ne se déploie jamais contre un état partiellement publié.

Pour plus d’informations sur le partage de bundles, consultez Partage de bundles et de fichiers de bundles.

Bundles de Template personnalisés

Utilisez des templates de Declarative Automation Bundles personnalisés comme point de départ par default pour les nouveaux projets afin que chaque projet hérite des mêmes garde-fous — autorisations, tagging, politiques de cluster, câblage CI/CD et bases de référence d'instance — sans que chaque équipe ait à résoudre le problème à partir de zéro.

Les Templates devraient encoder des conventions partagées et durables telles que la gouvernance, les defaults de performance, le Layout d’environnement et les limites de quota. Évitez la logique métier spécifique à l’application, les secrets ou la configuration ponctuelle dans les Template.

Paramétrez uniquement les entrées qui sont censées varier par équipe, projet ou environnement :

• Nom du projet ou de l'application
• Paramètres du Workspace cible
• Noms de catalogue ou de schéma
• Identifiants de Service Principal
• Paramètres des calendriers et des notifications

Maintenez les garde-fous de la plateforme et les shared defaults fixes dans le Template plutôt que de les paramétrer.

Pour plus d'information sur les templates de bundles personnalisés et sur la façon de les créer, consultez les templates de projet Declarative Automation Bundles.

Planifier les rollbacks et les correctifs

Gardez les bundles suffisamment petits pour que vous puissiez effectuer un rollback ciblé sur un seul bundle plutôt que de coordonner un rollback sur de nombreuses charges de travail sans rapport.

Pendant un incident :

1. Rétablissez ou annulez le bundle affecté à la dernière bonne version connue.
2. Utilisez un correctif d'urgence uniquement pour les correctifs urgents et étroitement ciblés qui ne peuvent pas attendre le flux de promotion normal.
3. Merge tout correctif urgent dans la Branch principale immédiatement après la validation afin que la Branch principale reste la source unique de vérité.

Développement général

Utiliser les Service Principals ou OIDC

Utilisez les Service Principals pour toute automatisation hors développement afin de dissocier les flux de travail automatisés des comptes d'utilisateurs individuels et de garantir que les Jobs continuent de s'exécuter lorsque les utilisateurs internes partent. See Service Principal.

• Utilisez des Service Principal distincts pour le déploiement et l'exécution. Un Service Principal de déploiement dédié pour les déploiements de bundles devrait avoir un accès minimal aux données. Chaque Job de production ou pipeline devrait avoir son propre Service Principal d'exécution, dont la portée est limitée aux données et Ressources requises par la charge de travail. Cette séparation garantit que les déploiements restent sécurisés lorsque vous modifiez ou renforcez les autorisations d'accès aux données, et évite de lier les changements d'infrastructure à l'accès aux données de production.
• **Secteurs d'activité réglementés** : utilisez la fédération d'identité Workload (OIDC) pour CI/CD. Ceci élimine les secrets à long terme dans GitHub Actions ou Azure DevOps. Consultez Activer la fédération d'identité de charge de travail en CI/CD.

Utilisez les outils de développement Databricks

Développez dans l'interface utilisateur (IU) du workspace Databricks à l'aide de dossiers Git, ou dans un IDE local. Si vous utilisez Visual Studio Code ou un fork compatible, installez l’extension Databricks officielle pour :

• Compétences d'agent spécifiques à Databricks
• Unity Catalog et accès au système de fichiers
• Fonctionnalités de développement à distance pour exécuter des charges de travail sur le compute Databricks

Pour plus d'informations, consultez l'extension Databricks pour Visual Studio Code.

Minimiser la logique métier dans les Notebooks

Ne traitez pas les notebooks comme le conteneur principal de la logique métier. Utilisez-les uniquement à des fins d'exploration et de visualisation.

• Python : Intégrez la logique principale dans des modules .py importables dans src/ ou src/py/, et appelez ces fonctions à partir de notebooks.
• SQL : conservez les requêtes dans les fichiers .sql dans src/ ou src/sql/, et référencez ces fichiers à partir des jobs et pipelines plutôt que d'intégrer le SQL directement dans les notebooks.

Utilisez les Notebooks uniquement comme de minces couches d'orchestration et de visualisation qui appellent le code sous-jacent. Cette approche facilite les tests et la réutilisation.

Lorsque vous migrez un projet fortement axé sur les Notebooks, faites-le de manière incrémentielle. Extrayez un module réutilisable ou un fichier SQL à la fois, et utilisez les Declarative Automation Bundles pour intégrer les assets migrés dans le même workflow de déploiement et de test que le reste du projet.

Transmettre le contexte dynamiquement

Évitez les variables statiques pour les dépendances de tâche. Utilisez des références de valeur dynamique comme {{tasks.<task_key>.values.<value_key>}} pour transmettre le contexte d'exécution entre les tâches d'un job multi-étapes.

Tests et observabilité

Mettre en œuvre des couches de test

Utilisez trois niveaux de test qui correspondent à la manière dont vos bundles évoluent vers la production :

1. Tests unitaires : Conservez la logique métier dans des modules src/ importables et couvrez-la avec pytest ou un framework équivalent. Exécutez-les sur chaque pull request afin que les échecs bloquent les Merge.
2. Validation de bundle : Exécutez bundle validate localement. En CI, préférez bundle deploy à un workspace hors production pour détecter les problèmes de YAML et de mappage des ressources avant les déploiements en production.
3. Tests d'intégration en préproduction : Après le déploiement en préproduction, exécutez des jobs de bout en bout avec des vérifications d'achèvement et des assertions critiques de qualité des données, telles que le nombre de lignes ou les attentes de schéma.

Considérez « tous les tests passent sur la Branch principale et en préproduction » comme la condition de promotion des artefacts en production.

Pour les LakeFlow Pipelines, utilisez les fonctionnalités de développement et de validation intégrées plutôt que des exécutions de Notebook ad hoc. Testez la logique du pipeline avec des datasets petits et représentatifs qui incluent des enregistrements avec des erreurs, et utilisez le mode développement pour valider les changements avant de mettre à jour les tables de production.

Traitez la journalisation comme faisant partie du déploiement

Pour les charges de travail déployées via des Declarative Automation Bundles, considérez les métriques et la journalisation comme faisant partie du contrat de déploiement plutôt que comme quelque chose que chaque projet définit indépendamment.

• Émettez des logs structurés de manière cohérente entre les jobs, les pipelines et les tâches. Incluez le nom du bundle, l'environnement cible, le nom de la charge de travail, l'identifiant d'exécution et tout identifiant commercial nécessaire pour tracer les échecs.
• Suivez un ensemble standard de métriques opérationnelles pour chaque charge de travail de production : état d'exécution, durée, nombre de tentatives, et indicateurs de throughput ou de fraîcheur, le cas échéant.
• Encodez ces conventions dans des bibliothèques partagées, des définitions de charges de travail réutilisables ou des Template de bundles afin que les équipes n'aient pas à recréer des modèles d'observabilité pour chaque projet.