Techniques CI/CD avec Git et Databricks Repos

Article
03/20/2024

Découvrez les techniques d’utilisation de Databricks Repos dans des workflows CI/CD. L’intégration de dépôts Git à Databricks Repos fournit un contrôle de code source pour les fichiers projet.

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

Vue d’ensemble des techniques CI/CD pour Repos.

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

Databricks Repos comprend des dossiers de niveau utilisateur et des dossiers de niveau supérieur non-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 Databricks Repos dans les dossiers utilisateur comme des « validations locales » propres à chaque utilisateur, où les utilisateurs apportent des modifications à leur code.

Dans votre dossier utilisateur dans Databricks Repos, clonez votre dépôt 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 Repos.

Spécifications

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

Remarque

Databricks recommande que chaque développeur travaille sur sa propre branche de fonctionnalité. Pour plus d’informations sur la résolution des conflits de fusion, consultez Résoudre les conflits de fusion.

Collaborer dans Repos

Dans ce qui suit, le workflow utilise une branche appelée feature-b basée sur la branche primaire.

Clonez votre dépôt Git existant dans votre espace de travail Databricks.
Utilisez l’interface utilisateur Repos pour créer une branche de fonctionnalité à partir de la branche principale. 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.
Apportez vos changements aux notebooks Azure Databricks et autres fichiers dans le référentiel.
Validez et envoyez (push) vos modifications à votre fournisseur Git.
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 dépôt.
2. Le contributeur valide et envoie ses modifications au fournisseur Git.
Pour fusionner les modifications d’autres branches ou rebaser la branche feature-b dans Databricks, dans l’interface utilisateur Repos, utilisez l’un des workflows 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.
Quand vous êtes prêt à fusionner votre travail avec le dépôt Git distant et la branche main, utilisez l’interface utilisateur Repos pour fusionner les modifications de feature-b. Si vous préférez, vous pouvez à la place fusionner les modifications dans votre fournisseur Git.

Flux de travail de production

Databricks Repos 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 : configurez un dépôt Git de production et appelez les API Repos pour le mettre à jour par programmation. Exécutez les travaux sur le dépôt Databricks qui clone ce dépôt 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 dépôt de production distinct dans Databricks, de gérer les autorisations le concernant et de le tenir à jour.

Consultez Utiliser du code source contrôlé par version dans une tâche Azure Databricks.

Option 2 : configurer un dépôt de production et l’automatisation Git

Dans cette option, vous configurez un dépôt de production et l’automatisation Git pour mettre à jour Databricks Repos 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 Databricks Repos 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 dépôt « 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.

Dossiers de dépôt de premier niveau.

Étape 2 : Configurer des mises à jour automatisées de Databricks Repos via l’API Repos

Dans cette étape, utilisez l’API Repos pour configurer l’automatisation afin de mettre à jour Databricks Repos lors d’un événement de fusion.

Pour conserver un dépôt 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 dépôt approprié dans le dossier Production pour mettre à jour ce dépôt 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.

Remarque

Si %pip install databricks-sdk --upgrade retourne une erreur indiquant « Impossible de trouver le package », cela signifie que le package databricks-sdk n’a pas été installé au préalable. Réexécutez la commande sans l’indicateur --upgrade : %pip install databricks-sdk.

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, Postman 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 Databricks Repos

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

Créez un principal de service avec Azure Databricks.
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 :

Créer un principal de service. Consultez Exécuter des travaux avec des principaux de service.
Créez un jeton Microsoft Entra ID pour un principal de service.
Après avoir créé un principal de service, vous l’ajoutez à votre espace de travail Azure Databricks avec l’API Principaux de service.
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 Databricks Repos 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 Databricks Repos

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

Spécifications

Vous avez créé un dépôt 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.

Étapes

Remarque

L’étape 1 doit être effectuée par un administrateur du dépôt Git.

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 ce secret sur l’URL de l’espace de travail, mais n’incluez pas la sous-chaîne /?o.
- DEPLOYMENT_TARGET_TOKEN : fournissez une valeur de jeton d’accès personnel (PAT) Databricks. Vous pouvez générer un PAT Databricks en suivant les instructions contenues dans Configurer les informations d’identification Git et connecter un dépôt distant à Azure Databricks.

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 :

Lien « Set up a workflow yourself » (Configurer vous-même un workflow) dans l’interface utilisateur de GitHub Actions

# 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:
      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
      env:
        DBFS_LIB_PATH: dbfs:/path/to/libraries/
        REPO_PATH: /Repos/path/here
        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@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
        # Version range or exact version of a Python version to use, using SemVer's version range syntax.
          python-version: 3.8

      - name: Install mods
        run: |
          pip install databricks-cli
          pip install pytest setuptools wheel

      - name: Configure CLI
        run: |
          echo "${{ secrets.DEPLOYMENT_TARGET_URL }} ${{ secrets.DEPLOYMENT_TARGET_TOKEN }}" | databricks configure --token

      - name: Extract branch name
        shell: bash
        run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
        id: extract_branch

      - name: Update Databricks Repo
        run: |
          databricks repos update --path ${{env.REPO_PATH}} --branch "${{ steps.extract_branch.outputs.branch }}"

      - name: Build Wheel and send to Databricks workspace DBFS 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

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 dépôt où les notebooks seront mis à jour. Par exemple : /Repos/Develop.
- LATEST_WHEEL_NAME : nom du dernier wheel 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.
Sélectionnez Commiter les modifications... pour commiter le script en tant que workflow GitHub Actions. Une fois la demande de tirage (pull request) pour ce workflow fusionnée, accédez à l’onglet Actions du dépôt Git et vérifiez que les actions ont réussi.

Techniques CI/CD avec Git et Databricks Repos

Flux de développement

Spécifications

Collaborer dans Repos

Flux de travail de production

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

Option 2 : configurer un dépôt de production et l’automatisation Git

Étape 1 : Configurer des dossiers de premier niveau

Étape 2 : Configurer des mises à jour automatisées de Databricks Repos via l’API Repos

Utiliser un principal de service avec Databricks Repos

Intégration de Terraform

Configurer un pipeline CI/CD automatisé avec Databricks Repos

Spécifications

Étapes

Ressources supplémentaires