Techniques CI/CD avec Git et les dossiers Git Databricks (référentiels)

Découvrez les techniques d’utilisation des dossiers Git Databricks dans des workflows CI/CD. En configurant des dossiers Git Databricks dans l’espace de travail, vous pouvez utiliser le contrôle de code source pour les fichiers projet dans les référentiels Git et les intégrer à vos pipelines d’engineering données.

La figure suivante montre une vue d’ensemble des techniques et du workflow.

Pour obtenir une vue d’ensemble de CI/CD avec Azure Databricks, consultez Qu’est-ce que le CI/CD sur Azure Databricks ?.

Flux de développement

Les dossiers Git Databricks ont des dossiers au niveau de l’utilisateur. Les dossiers de niveau utilisateur sont créés automatiquement quand les utilisateurs clonent un dépôt distant pour la première fois. Vous pouvez considérer les dossiers Git Databricks dans les dossiers utilisateur comme des « validations locales » propres à chaque utilisateur, où les utilisateurs apportent des modifications à leur code.

Dans votre dossier utilisateur dans les dossiers Git Databricks, clonez votre référentiel distant. Une meilleure pratique consiste à créer une branche de fonctionnalité ou à sélectionner une branche créée précédemment pour votre travail, au lieu de valider et d’envoyer directement les modifications à la branche principale. Vous pouvez apporter des modifications, les valider et les transmettre dans cette branche. Lorsque vous êtes prêt à fusionner votre code, vous pouvez le faire dans l’interface utilisateur Dossiers Git.

Spécifications

Ce workflow nécessite que vous ayez déjà configuré votre intégration Git.

Collaborer dans des dossiers Git

Le flux de travail suivant utilise une branche appelée feature-b basée sur la branche primaire.

1. Clonez votre dépôt Git existant dans votre espace de travail Databricks.
2. Utilisez l’interface utilisateur Dossiers Git pour créer une branche de fonctionnalité à partir de la branche primaire. Par souci de simplicité, cet exemple utilise une branche de fonctionnalité unique, feature-b. Vous pouvez créer et utiliser plusieurs branches de fonctionnalité pour accomplir votre travail.
3. Apportez vos changements aux notebooks Azure Databricks et autres fichiers dans le référentiel.
4. Validez et envoyez (push) vos modifications à votre fournisseur Git.
5. Des contributeurs peuvent désormais cloner le dépôt Git dans leur propre dossier utilisateur.
   1. Alors qu’il travaille sur une nouvelle branche, un collègue apporte des changements aux notebooks et à d’autres fichiers dans le dossier Git.
   2. Le contributeur valide et envoie ses modifications au fournisseur Git.
6. Pour fusionner les modifications d’autres branches ou rebaser la branche feature-b dans Databricks, dans l’interface utilisateur Dossiers Git, utilisez l’un des flux de travail suivants :
   • Fusionnez des branches. En l’absence de conflit, la fusion est envoyée au dépôt Git distant avec git push.
   • Rebasez sur une autre branche.
7. Quand vous êtes prêt à fusionner votre travail avec le référentiel Git distant et la branche main, utilisez l’interface utilisateur Dossiers Git pour fusionner les modifications de feature-b. Si vous préférez, vous pouvez fusionner à la place les modifications directement avec le référentiel Git appuyant votre dossier Git.

Flux de travail de production

Dossiers Git Databricks fournit deux options pour l’exécution de vos travaux de production :

• Option 1 : fournissez une référence Git au dépôt distant dans la définition du travail. Par exemple, exécutez un notebook spécifique dans la branche main d’un dépôt Git.
• Option 2 : configurer un référentiel Git de production et appeler les API Repos pour le mettre à jour par programmation. Exécutez les travaux sur le dossier Git Databricks qui clone ce référentiel distant. L’appel d’API Repos doit être la première tâche du travail.

Option 1 : exécuter des travaux à l’aide de notebooks dans un dépôt distant

Simplifiez le processus de définition de travail et conservez une source unique de vérité en exécutant un travail Azure Databricks à l’aide de notebooks situés dans un référentiel Git distant. Cette référence Git peut être un commit, une balise ou une branche Git, et vous la fournissez vous-même dans la définition du travail.

Cela permet d’éviter les modifications involontaires apportées à votre travail de production, par exemple quand un utilisateur apporte des modifications locales dans un dépôt de production ou change de branche. Cela automatise également l’étape de déploiement continu (CD), car vous n’avez pas besoin de créer un dossier Git de production distinct dans Databricks, de gérer les autorisations le concernant et de le tenir à jour.

Consultez Utiliser Git avec des travaux.

Option 2 : configurer un dossier Git de production et l’automatisation Git

Dans cette option, vous configurez un dossier Git de production et l’automatisation pour mettre à jour le dossier Git lors d’une fusion.

Étape 1 : Configurer des dossiers de premier niveau

L’administrateur crée des dossiers de premier niveau non utilisateur. Le cas d’usage le plus courant de ces dossiers de premier niveau consiste à créer des dossiers de développement, de préproduction et de production contenant des dossiers Git Databricks pour les versions ou branches appropriées pour le développement, la préproduction et la production. Par exemple, si votre entreprise utilise la branche main pour la production, le dossier Git « production » doit contenir la branche main extraite.

En général, les autorisations sur ces dossiers de niveau supérieur sont en lecture seule pour tous les utilisateurs non administrateurs au sein de l’espace de travail. Pour ces dossiers de premier niveau, nous vous recommandons de ne donner au(x) principal(aux) de service que les autorisations PEUT MODIFIER et PEUT GÉRER afin d’éviter que les utilisateurs de l’espace de travail ne modifient accidentellement votre code de production.

Étape 2 : Configurer les mises à jour automatisées des dossiers Git Databricks avec l’API Dossiers Git

Pour conserver un dossier Git dans Databricks à la dernière version, vous pouvez configurer l’automatisation Git pour appeler l’API Repos. Dans votre fournisseur Git, configurez une automatisation qui, après chaque fusion réussie d’une demande de tirage dans la branche primaire, appelle le point de terminaison de l’API Repos sur le dossier Git approprié pour le mettre à jour avec la version la plus récente.

Par exemple, sur GitHub, cela peut être accompli avec GitHub Actions. Pour plus d’informations, consultez API Repos.

Pour appeler n’importe quelle API REST Databricks à partir d’une cellule de notebook Databricks, installez d’abord le Kit de développement logiciel (SDK) Databricks avec %pip install databricks-sdk --upgrade (pour les dernières API REST Databricks), puis importez ApiClient à partir de databricks.sdk.core.

Vous pouvez également exécuter des API du Kit de développement logiciel (SDK) Databricks à partir d’un notebook pour récupérer les principaux de service de votre espace de travail. Voici un exemple utilisant Python et le Kit de développement logiciel (SDK) Databricks pour Python.

Vous pouvez également utiliser des outils tels que curl ou Terraform. Vous ne pouvez pas utiliser l’interface utilisateur Azure Databricks.

Pour en savoir plus sur les principaux de service sur Azure Databricks, consultez Gérer les principaux de service. Pour plus d’informations sur les principaux de service et CI/CD, consultez Principaux de service pour CI/CD. Pour plus d’informations sur l’utilisation du Kit de développement logiciel (SDK) Databricks à partir d’un notebook, consultez Utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Databricks.

Utiliser un principal de service avec les dossiers Git Databricks

Pour exécuter les workflows mentionnés ci-dessus avec les principaux de service :

1. Créez un principal de service avec Azure Databricks.
2. Ajoutez les informations d’identification Git : utilisez le jeton d’accès personnel (PAT, Personal Access Token) de votre fournisseur Git pour le principal de service.

Pour configurer des principaux de service, puis ajouter les informations d’identification du fournisseur Git :

1. Créer un principal de service. Consultez Exécuter des travaux avec des principaux de service.
2. Créez un jeton Microsoft Entra ID pour un principal de service.
3. Après avoir créé un principal de service, vous l’ajoutez à votre espace de travail Azure Databricks avec l’API Principaux de service.
4. Ajoutez vos informations d'identification de fournisseur Git à votre espace de travail avec votre jeton d'ID Microsoft Entra et l'API Git Credentials.

Intégration de Terraform

Vous pouvez également gérer les dossiers Git Databricks dans une configuration entièrement automatisée à l’aide de Terraform et de databricks_repo :

resource "databricks_repo" "this" {
  url = "https://github.com/user/demo.git"
}

Pour utiliser Terraform afin d’ajouter des informations d’identification Git à un principal de service, ajoutez la configuration suivante :

  provider "databricks" {
    # Configuration options
  }

  provider "databricks" {
    alias = "sp"
    host = "https://....cloud.databricks.com"
    token = databricks_obo_token.this.token_value
  }

  resource "databricks_service_principal" "sp" {
    display_name = "service_principal_name_here"
  }

  resource "databricks_obo_token" "this" {
    application_id   = databricks_service_principal.sp.application_id
    comment          = "PAT on behalf of ${databricks_service_principal.sp.display_name}"
    lifetime_seconds = 3600
  }

  resource "databricks_git_credential" "sp" {
    provider = databricks.sp
    depends_on = [databricks_obo_token.this]
    git_username          = "myuser"
    git_provider          = "azureDevOpsServices"
    personal_access_token = "sometoken"
  }

Configurer un pipeline CI/CD automatisé avec les dossiers Git Databricks

Voici une automatisation simple que vous pouvez exécuter en tant qu’action GitHub.

Spécifications

• Vous avez créé un dossier Git dans un espace de travail Databricks qui fait le suivi de la branche de base dans laquelle la fusion est effectuée.
• Vous disposez d’un package Python qui crée les artefacts à placer dans un emplacement DBFS. Votre code doit :
  • Mettre à jour le dépôt associé à votre branche préférée (par exemple, development) pour contenir les dernières versions de vos notebooks.
  • Générer tous les artefacts et les copier dans le chemin d’accès de la bibliothèque.
  • Remplacer les dernières versions des artefacts de build pour éviter d’avoir à mettre à jour manuellement les versions d’artefact dans votre travail.

Créer un flux de travail CI/CD automatisé

1. Configurez des secrets pour que votre code puisse accéder à l’espace de travail Databricks. Ajoutez les secrets suivants au dépôt GitHub :

   • DEPLOYMENT_TARGET_URL : définissez cette valeur sur l’URL de votre espace de travail. N’incluez pas la /?o sous-chaîne.
   • DEPLOYMENT_TARGET_TOKEN : définissez-le sur un jeton d’accès personnel Databricks (PAT). Vous pouvez générer un PAT Databricks en suivant les instructions de l’authentification par jeton d’accès personnel Azure Databricks.

2. Accédez à l’onglet Actions de votre dépôt Git, puis cliquez sur le bouton Nouveau workflow. En haut de la page, sélectionnez Configurer un workflow vous-même et collez ce script :

   

   # This is a basic automation workflow to help you get started with GitHub Actions.
   
   name: CI
   
   # Controls when the workflow will run
   on:
     # Triggers the workflow on push for main and dev branch
     push:
       paths-ignore:
         - .github
       branches:
         # Set your base branch name here
         - your-base-branch-name
   
   # A workflow run is made up of one or more jobs that can run sequentially or in parallel
   jobs:
     # This workflow contains a single job called "deploy"
     deploy:
       # The type of runner that the job will run on
       runs-on: ubuntu-latest
       environment: development
       env:
         DATABRICKS_HOST: ${{ secrets.DEPLOYMENT_TARGET_URL }}
         DATABRICKS_TOKEN:  ${{ secrets.DEPLOYMENT_TARGET_TOKEN }}
         REPO_PATH: /Workspace/Users/someone@example.com/workspace-builder
         DBFS_LIB_PATH: dbfs:/path/to/libraries/
         LATEST_WHEEL_NAME: latest_wheel_name.whl
   
       # Steps represent a sequence of tasks that will be executed as part of the job
       steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v3
   
       - name: Setup Python
         uses: actions/setup-python@v3
         with:
         # Version range or exact version of a Python version to use, using SemVer's version range syntax.
           python-version: 3.8
   
       # Download the Databricks CLI. See https://github.com/databricks/setup-cli
       - uses: databricks/setup-cli@main
   
       - name: Install mods
         run: |
           pip install pytest setuptools wheel
   
       - name: Extract branch name
         shell: bash
         run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
         id: extract_branch
   
       - name: Update Databricks Git folder
         run: |
           databricks repos update ${{env.REPO_PATH}} --branch "${{ steps.extract_branch.outputs.branch }}"
   
       - name: Build Wheel and send to Databricks DBFS workspace location
         run: |
           cd $GITHUB_WORKSPACE
           python setup.py bdist_wheel
           dbfs cp --overwrite ./dist/* ${{env.DBFS_LIB_PATH}}
           # there is only one wheel file; this line copies it with the original version number in file name and overwrites if that version of wheel exists; it does not affect the other files in the path
           dbfs cp --overwrite ./dist/* ${{env.DBFS_LIB_PATH}}${{env.LATEST_WHEEL_NAME}} # this line copies the wheel file and overwrites the latest version with it
   

3. Mettez à jour les valeurs de variable d’environnement suivantes avec vos propres valeurs :

   • DBFS_LIB_PATH : chemin d’accès dans DBFS aux bibliothèques (wheels) que vous utiliserez dans cette automatisation. Commence par dbfs:. Par exemple : dbfs:/mnt/myproject/libraries.
   • REPO_PATH : chemin d’accès dans votre espace de travail Databricks au dossier Git où les notebooks seront mis à jour.
   • LATEST_WHEEL_NAME : nom du dernier fichier de roue Python compilé (.whl). Cela permet d’éviter de mettre à jour manuellement les versions de wheel dans vos travaux Databricks. Par exemple : your_wheel-latest-py3-none-any.whl.

4. Sélectionnez Commiter les modifications... pour commiter le script en tant que workflow GitHub Actions. Une fois que la demande de tirage (pull request) pour ce workflow est fusionnée, accédez à l’onglet Actions du dépôt Git et vérifiez que les actions ont réussi.