CI/CD för Databricks-appar med GitHub Actions

Den här sidan förklarar hur du automatiserar distributionen av en Databricks-app från GitHub med hjälp av GitHub Actions och Declarative Automation Bundles. Den omfattar federering av arbetsbelastningsidentiteter, YAML-arbetsflödet och en hälsokontroll som bekräftar att appen kör den senaste koden efter varje driftsättning.

För allmän vägledning om GitHub Actions för Azure Databricks-jobb och -pipelines, se GitHub Actions. Information om konfigurationen av arbetsbelastningsidentitetsfederation finns i Enable workload identity federation for GitHub Actions.

Requirements

• Ett tjänsthuvudnamn i ditt Azure Databricks-konto som äger den distribuerade appen. Se Lägg till tjänsteprincipaler i ditt konto.
• En databricks.yml paketkonfiguration i roten på din GitHub lagringsplats som deklarerar appen som en resurs. Se appen.
• Databricks CLI installeras lokalt för engångsinstallationsuppgifter. Se Installera eller uppdatera Databricks CLI.

Steg 1. Konfigurera identitetsfederation för arbetsbelastning

Federering av arbetsbelastningsidentiteter gör att GitHub Actions-runnern kan autentisera sig mot Azure Databricks med hjälp av en kortlivat OIDC-token i stället för att lagra autentiseringsuppgifter i ditt kodförråd.

1. Följ stegen i Enable workload identity federation for GitHub Actions för att skapa en GitHub Actions federationsprincip för tjänstens huvudnamn. Anteckna tjänsthuvudnamnets applikations-ID (UUID) och URL:en för arbetsytan. Du behöver båda som variabler i arbetsflödet.
2. Ge tjänstens huvudnamn CAN MANAGE behörighet för appen eller arbetsytan för att skapa appar om appen inte finns ännu. Se Konfigurera behörigheter för en Databricks-app.

Steg 2. Konfigurera GitHub-lagringsplatsen

I din GitHub lagringsplats skapar du en distributionsmiljö för att lagra variablerna för arbetsytans anslutning. Att använda en miljö gör det också möjligt att kräva ett manuellt godkännande innan distributioner kan köras.

1. I Inställningar>Miljöer skapar du en miljö med namnet prod (eller valfritt namn på dina arbetsflödesreferenser).
2. För miljövariabler lägger du till följande:

Inget av värdena är en autentiseringsuppgift. Federationsprincipen för tjänstens huvudnamn styr vem som kan autentiseras som den, så enbart klient-ID:t beviljar inte åtkomst. Du behöver ingen klienthemlighet.

Steg 3. Konfigurera ditt paket för produktionsdistributioner

I databricks.ymldeklarerar du en explicit arbetsyta host och root_path på målet prod . Detta säkerställer att paketet distribueras till samma plats vid varje körning. Validering i produktionsläge kräver båda fälten om inte run_as har angetts till tjänstens huvudnamn. Se Distributionslägen för deklarativa Automation-paket.

Git-källa

Använd git_source så att distributioner hämtar kod direkt från din Git-lagringsplats i stället för att ladda upp filer till arbetsytan. Detta undviker det extra sync steget och håller den distribuerade koden synkroniserad med din lagringsplats.

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

Ersätt <service-principal-or-owner> med den arbetsyteanvändare som äger paketartefakterna, vanligtvis program-ID:t för tjänstens huvudnamn. git_repository Ersätt URL:en med url:en för din GitHub lagringsplats. Om din appkod finns på lagringsplatsens rot utelämnar du source_code_path. Se appen.

För privata lagringsplatser konfigurerar du en Git-autentiseringsuppgift på appens tjänsthuvudnamn innan du distribuerar. Se CLI-instruktionerna i Distribuera från en Git-lagringsplats.

Källa för arbetsyta

Använd source_code_path för att ladda upp appfiler från din lokala lagringsplats till arbetsytan under distributionen.

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

Ersätt <service-principal-or-owner> med den arbetsyteanvändare som äger paketartefakterna, vanligtvis program-ID:t för tjänstens huvudnamn. Ersätt ./app med sökvägen till appens källkod i förhållande till databricks.yml. Se appen.

Steg 4. Lägg till arbetsflödet för distribution

Lägg till .github/workflows/deploy.yml i ditt repository:

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

Ersätt my_app i det sista steget med resursnyckeln som du databricks.yml använder under resources.apps.

Runnern behöver behörigheten id-token: write för att begära en OIDC-token. Åtgärden databricks/setup-cli läser DATABRICKS_AUTH_TYPE=github-oidc och hanterar autentisering automatiskt.

Steg 5. Vänta tills appen är felfri

Databricks rekommenderar att du lägger till ett statussökningssteg efter distributionen. databricks bundle run avslutas så snart den signalerar att appen ska starta, men appen kanske inte körs ännu. Det kan fortfarande misslyckas vid start på grund av problem som saknade beroenden, en saknad miljövariabel eller en portkonflikt. Genom att lägga till ett pollningssteg säkerställer du att ett misslyckat uppstartsförsök också gör att arbetsflödet misslyckas:

- 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

Ange APP_NAME till det värde som din databricks.yml deklarerar under resources.apps.<key>.name, inte resursnyckeln för paketet.

Hantera en befintlig app

Appnamn är unika i hela arbetsytan. Steget bundle deploy misslyckas med An app with the same name already exists när ett annat paket (eller en manuellt skapad app) redan äger en app med det namnet. Binda ditt paket till den befintliga appen i stället för att återskapa det.

Kör detta en gång lokalt för att koppla paketet till den befintliga appen:

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

Kör sedan arbetsflödet igen. Efterföljande distributioner återanvänder bindningen.

Om den befintliga appen har konfiguration på serversidan (till exempel budget_policy_id) som inte finns i din databricks.ymlkopierar du den till paketfilen innan du distribuerar om den. Felmatchningar visas som ett Terraform-fel med "inkonsekvent resultat" under distributionssteget för paketet.

Välja en utlösare

Börja med workflow_dispatch så att den första distributionen är manuell. När ett par körningar har lyckats lägger du till push: branches: [main] för att distribuera vid varje merge.

För ytterligare en säkerhetsgrind konfigurerar du prod miljön med nödvändiga granskare i Inställningar>Miljöer>prod>Distributionsskyddsregler. Varje arbetsflödeskörning väntar på en godkännare innan driftsättningsjobbet startar.

Ytterligare resurser

• Konfigurera workload identity federation för att konfigurera GitHub Actions-federeringsprincipen för ditt tjänsthuvudnamn.
• Deklarera en app som en paketresurs för att lägga till din app i databricks.yml.
• Konfigurera appbehörigheter för att styra vem som kan hantera eller använda den distribuerade appen.
• Läs mer om deklarativa Automation-paket för mer information om paketets livscykel och distributionslägen.
• Använd GitHub Actions med Azure Databricks för vägledning om jobb och pipelines utöver appar.