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

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.

Följ stegen i Enable workload identity federation for GitHub Actions för att skapa en GitHub Actions federationsprincip för tjänstens huvudnamn. Observera tjänstens huvudnamns program-ID (UUID) och din arbetsyte-URL. Du behöver båda som variabler i arbetsflödet.

Ge sedan 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:
Variabel Value
DATABRICKS_HOST Webbadressen till arbetsytan, till exempel https://my-workspace.cloud.databricks.com
DATABRICKS_CLIENT_ID Program-ID för tjänstens huvudnamn från steg 1

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.

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. Fältet source_code_path krävs när appkoden finns på samma lagringsplats som paketet. Om din appkod finns på en separat lagringsplats använder du git_source i stället. 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.

Varning

databricks bundle deploy laddar upp källkoden och uppdaterar resurser, men den startar inte om appprocessen. Om du hoppar över det sista databricks bundle run steget skickas distributionen i CI medan appen fortsätter att betjäna den tidigare koden. Kör alltid paketresursen efter distributionen.

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 innebär du att en misslyckad start också leder till 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.

Nästa steg

  • Last updated on