CI/CD pour Databricks Apps avec GitHub Actions

Cette page explique comment automatiser le déploiement d’une application Databricks à partir de GitHub à l’aide de GitHub Actions et de Declarative Automation Bundles. Cela couvre la fédération d’identités de charge de travail, le fichier YAML du workflow et une vérification d’intégrité qui confirme que l’application utilise bien la version la plus récente du code après chaque déploiement.

Pour obtenir des conseils de GitHub Actions génériques pour les travaux et les pipelines Azure Databricks, consultez GitHub Actions. Pour la configuration de la fédération des identités de charge de travail, consultez Activer la fédération des identités de charge de travail pour GitHub Actions.

Requirements

• Un principal de service dans votre compte Azure Databricks qui possède l’application déployée. Voir Ajouter des entités de service à votre compte.
• Configuration de bundle databricks.yml à la racine de votre référentiel de GitHub déclarant l’application en tant que ressource. Voir l’application.
• L’interface de ligne de commande Databricks installée localement pour des tâches de configuration ponctuelles. Consultez Installer ou mettre à jour l’interface CLI Databricks.

Étape 1. Configurer la fédération des identités de charge de travail

La fédération des identités de charge de travail permet à l’exécuteur GitHub Actions de s’authentifier avec Azure Databricks à l’aide d’un jeton OIDC de courte durée au lieu de stocker les informations d’identification dans votre référentiel.

1. Suivez les étapes dans Activer la fédération d’identité de charge de travail pour GitHub Actions pour créer une stratégie de fédération pour GitHub Actions sur votre principal de service. Enregistrez l’ID d’application du principal de service (UUID) et l’URL de votre espace de travail. Vous avez besoin des deux variables dans le flux de travail.
2. Accordez au principal de service CAN MANAGE les autorisations sur l’application, ou les autorisations sur l’espace de travail pour créer des applications si l’application n’existe pas encore. Consultez Configurer des autorisations pour une application Databricks.

Étape 2. Configurer le référentiel GitHub

Dans votre référentiel GitHub, créez un environnement de déploiement pour stocker les variables de connexion de l’espace de travail. L’utilisation d’un environnement vous permet également d’exiger une approbation manuelle avant l’exécution des déploiements.

1. Dansles environnements>, créez un environnement nommé prod (ou n’importe quel nom de vos références de flux de travail).
2. Pour les variables d’environnement, ajoutez les éléments suivants :

Aucune de ces valeurs n’est un identifiant. La stratégie de fédération appliquée au principal de service contrôle qui peut s’authentifier avec cette identité, de sorte que l’ID client à lui seul n’accorde pas l’accès. Vous n’avez pas besoin d’un secret client.

Étape 3. Configurer votre bundle pour les déploiements de production

Dans databricks.yml, déclarez un espace de travail host explicite et root_path sur votre prod cible. Cela garantit que le package est déployé au même emplacement à chaque exécution. La validation en mode production nécessite les deux champs, sauf si run_as est défini comme principal de service. ** Consultez les modes de déploiement des ensembles d'automatisation déclarative.

Source Git

Utilisez git_source cette méthode pour que les déploiements extrayent du code directement à partir de votre dépôt Git au lieu de charger des fichiers dans l’espace de travail. Cela évite l’étape supplémentaire sync et conserve le code déployé synchronisé avec votre référentiel.

targets:
  prod:
    mode: production
    workspace:
      host: https://my-workspace.cloud.databricks.com
      root_path: /Workspace/Users/<service-principal-or-owner>/.bundle/${bundle.name}/${bundle.target}
    resources:
      apps:
        my_app:
          name: my-app
          git_repository:
            url: https://github.com/org/repo
          git_source:
            branch: main
            source_code_path: apps/my-app

Remplacez <service-principal-or-owner> par l’utilisateur de l’espace de travail propriétaire des artefacts groupés, généralement l’ID d’application du principal de service. Remplacez l’URL git_repository par l’URL de votre dépôt GitHub. Si votre code d’application se trouve à la racine du référentiel, omettez source_code_path. Voir l’application.

Pour les référentiels privés, configurez des informations d’identification Git sur le principal de service de l’application avant le déploiement. Consultez les instructions de l’interface CLI dans Déployer à partir d’un référentiel Git.

Source de l’espace de travail

Permet source_code_path de charger des fichiers d’application à partir de votre référentiel local vers l’espace de travail pendant le déploiement.

targets:
  prod:
    mode: production
    workspace:
      host: https://my-workspace.cloud.databricks.com
      root_path: /Workspace/Users/<service-principal-or-owner>/.bundle/${bundle.name}/${bundle.target}
    resources:
      apps:
        my_app:
          name: my-app
          source_code_path: ./app

Remplacez <service-principal-or-owner> par l’utilisateur de l’espace de travail propriétaire des artefacts groupés, généralement l’ID d’application du principal de service. Remplacez ./app par le chemin d’accès au code source de votre application par rapport à databricks.yml. Voir l’application.

Étape 4. Ajouter le workflow de déploiement

Ajoutez .github/workflows/deploy.yml à votre dépôt :

name: Deploy to Databricks Apps

on:
  workflow_dispatch:
  # Uncomment to deploy on every push to main once the workflow is validated.
  # push:
  #   branches: [main]

permissions:
  id-token: write # required for OIDC federation
  contents: read

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: prod
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}
    steps:
      - uses: actions/checkout@v4

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

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

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

      - name: Start or restart app
        run: databricks bundle run my_app --target prod

Remplacez my_app à la dernière étape par la clé de ressource qu’utilise votre databricks.yml sous resources.apps.

Le runner doit disposer de l’autorisation id-token: write pour demander un jeton OIDC. L’action databricks/setup-cli lit DATABRICKS_AUTH_TYPE=github-oidc et gère automatiquement l’authentification.

Étape 5. Attendez que l’application soit saine

Databricks recommande d’ajouter une étape d’interrogation d’état après le déploiement. databricks bundle run se ferme dès qu’elle envoie à l’application le signal de démarrage, mais l’application n’est peut-être pas encore en cours d’exécution. Il peut toujours échouer au démarrage en raison de problèmes tels que les dépendances manquantes, une variable d’environnement manquante ou un conflit de port. L’ajout d’une étape de scrutation garantit que, si le démarrage échoue, le flux de travail échoue lui aussi :

- name: Wait for app to be running
  env:
    APP_NAME: my-app
  run: |
    for i in $(seq 1 20); do
      STATE=$(databricks apps get "$APP_NAME" --output json | jq -r '.app_status.state')
      echo "Attempt $i/20: state=$STATE"
      if [ "$STATE" = "RUNNING" ]; then
        exit 0
      fi
      sleep 15
    done
    echo "App did not reach RUNNING state within 5 minutes" >&2
    exit 1

Définissez APP_NAME sur la valeur que databricks.yml déclare sous resources.apps.<key>.name, et non sur la clé de ressource du bundle.

Gestion d’une application existante

Les noms d’application sont uniques dans l’espace de travail. L’étape bundle deploy échoue avec An app with the same name already exists lorsqu’un autre paquet (ou une application créée manuellement) possède déjà une application portant ce nom. Liez votre offre groupée à l’application existante au lieu de la recréer.

Exécutez cette opération une fois localement pour attacher l’offre groupée à l’application existante :

databricks bundle deployment bind my_app <existing-app-name> --target prod --auto-approve

Réexécutez ensuite le flux de travail. Les déploiements suivants réutilisent la liaison.

Si l’application existante dispose d’une configuration côté serveur (par exemple budget_policy_id) qui n’est pas dans votre databricks.ymlfichier, copiez-la dans le fichier groupé avant de le redéployer. Les incompatibilités apparaissent sous la forme d’une erreur Terraform « résultat incohérent » lors de l’étape de déploiement du bundle.

Choix d’un déclencheur

Commencez par workflow_dispatch afin que le premier déploiement soit manuel. Une fois que quelques exécutions ont réussi, ajoutez push: branches: [main] pour déployer à chaque fusion.

Pour une mesure de sécurité supplémentaire, configurez l’environnement prod avec des réviseurs obligatoires dans Paramètres>Environnements>prod>Règles de protection du déploiement. Chaque exécution du workflow attend une approbation avant que la tâche de déploiement ne démarre.

Ressources supplémentaires

• Configurez la fédération des identités de charge de travail pour configurer la stratégie de fédération GitHub Actions sur votre principal de service.
• Déclarez une application en tant que ressource groupée pour ajouter votre application à databricks.yml.
• Configurez les autorisations d’application pour contrôler qui peut gérer ou utiliser l’application déployée.
• Découvrez les bundles d’automatisation déclarative pour en savoir plus sur le cycle de vie et les modes de déploiement des bundles.
• Utilisez GitHub Actions avec Azure Databricks pour obtenir des conseils sur les travaux et les pipelines au-delà des applications.