Konvertera en pipeline till ett paketprojekt

Du kan omvandla en befintlig pipeline till ett Declarative Automation Bundles-projekt. Med paket kan du definiera och hantera databearbetningskonfigurationen för Azure Databricks i en enda, källkontrollerad YAML-fil som ger enklare underhåll och möjliggör automatisk distribution till målmiljöer.

En handledning som använder databricks pipelines kommandon för att skapa ett pipelineprojekt och sedan distribuerar och kör en pipeline finns i Utveckla pipelines med deklarativa automatiseringspaket.

Översikt över konverteringsprocessen

De steg du utför för att konvertera en befintlig pipeline till ett paket är:

1. Kontrollera att du har åtkomst till en tidigare konfigurerad pipeline som du vill konvertera till ett paket.
2. Skapa eller förbereda en mapp (helst i en källkontrollerad hierarki) för att lagra paketet.
3. Generera en konfiguration för paketet från den befintliga pipelinen med hjälp av Databricks CLI.
4. Granska den genererade paketkonfigurationen för att se till att den är klar.
5. Länka bunten till den ursprungliga pipelinen.
6. Distribuera pipelinen till en målarbetsyta med hjälp av paketkonfigurationen.

Kravspecifikation

Innan du börjar måste du ha:

• Databricks CLI installerat på din lokala utvecklingsdator. Databricks CLI version 0.218.0 eller senare krävs för att använda deklarativa Automation-paket.
• ID:t för en befintlig deklarativ pipeline som du hanterar med ett paket. Information om hur du hämtar det här ID:t finns i Hämta en befintlig pipelinedefinition med hjälp av användargränssnittet.
• Auktorisering för Azure Databricks-arbetsytan där den befintliga pipelinen körs. Information om hur du konfigurerar autentisering och auktorisering för dina Databricks CLI-anrop finns i Auktorisera åtkomst till Azure Databricks-resurser.
• Fullständig uppsättning behörigheter som krävs för att skapa, köra, uppdatera och visa pipelines och deras utdata finns i Hantera identiteter, behörigheter och behörigheter för pipelines.

Steg 1: Konfigurera en mapp för ditt paketprojekt

Du måste ha åtkomst till en Git-lagringsplats som är konfigurerad i Azure Databricks som en Git-mapp. Du skapar ditt paketprojekt på den här lagringsplatsen, som använder källkontroll och gör det tillgängligt för andra medarbetare via en Git-mapp på motsvarande Azure Databricks-arbetsyta. (Mer information om Git-mappar finns i Azure Databricks Git-mappar.)

1. Gå till roten för den klonade Git-lagringsplatsen på den lokala datorn.

2. På en lämplig plats i mapphierarkin skapar du en mapp specifikt för ditt paketprojekt. Till exempel:

   mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle
   

3. Ändra den aktuella arbetskatalogen till den nya mappen. Till exempel:

   cd ~/source/my-pipelines/ingestion/events/my-bundle
   

4. Initiera ett nytt paket genom att köra:

   databricks bundle init
   

   Svara på anvisningarna. När den är klar har du en projektkonfigurationsfil med namnet databricks.yml i den nya startmappen för projektet. Den här filen krävs för att distribuera din pipeline från kommandoraden. Mer information om den här konfigurationsfilen finns i Konfiguration av deklarativa Automation-paket.

Steg 2: Skapa pipelinekonfigurationen

Från den här nya katalogen i den klonade Git-lagringsplatsens mappträd kör du genereringskommandot för Databricks CLI-paketet och anger ID:t för din pipeline som <pipeline-id>:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

När du kör generate kommandot skapas en paketkonfigurationsfil för din pipeline i paketets resources mapp och alla refererade artefakter hämtas till src mappen. ( --profile eller -p flaggan) är valfri, men om du har en specifik Databricks-konfigurationsprofil (definierad i .databrickscfg filen som skapades när du installerade Databricks CLI) som du hellre använder i stället för standardprofilen anger du den i det här kommandot. Information om Databricks-konfigurationsprofiler finns i Konfigurationsprofiler för Azure Databricks.

Steg 3: Granska paketprojektfilerna

När bundle generate-kommandot har slutförts har det skapat två nya mappar:

• resources är projektunderkatalogen som innehåller projektkonfigurationsfiler.
• src är projektmappen där källfiler, till exempel frågor och notebook-filer, lagras.

Kommandot skapar även några ytterligare filer:

• *.pipeline.yml i underkatalogen resources. Den här filen innehåller den specifika konfigurationen och inställningarna för din pipeline.
• Källfiler, till exempel SQL-frågor under underkatalogen src , kopierade från din befintliga pipeline.

├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Steg 4: Koppla paketpipelinen till din befintliga pipeline

Du måste länka, eller binda, pipelinedefinitionen i paketet till din befintliga pipeline för att hålla den uppdaterad när du gör ändringar. Det gör du genom att köra distributionsbindningskommandot för Databricks CLI-paket:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> är namnet på pipelinen. Det här namnet ska vara samma som det prefixerade strängvärdet för filnamnet för pipelinekonfigurationen i den nya resources-katalogen. Om du till exempel har en pipelinekonfigurationsfil med namnet ingestion_data_pipeline.pipeline.yml i mappen resources måste du ange ingestion_data_pipeline som pipelinenamn.

<pipeline-ID> är ID:t för din pipeline. Det är samma som det som du kopierade som en del av kraven för dessa instruktioner.

Steg 5: Distribuera din pipeline med ditt nya paket

Distribuera nu ditt pipelinepaket till den avsedda arbetsytan med hjälp av kommandot bundle deploy i Databricks CLI:

databricks bundle deploy --target <target-name> --profile <profile-name>

Flaggan --target krävs och måste anges till en sträng som matchar ett konfigurerat målarbetsytenamn, till exempel development eller production.

Om det här kommandot lyckas har du nu din pipelinekonfiguration i ett externt projekt som kan läsas in på andra arbetsytor och köras och enkelt delas med andra Azure Databricks-användare i ditt konto.

Flytta fram mellan miljöer med mål

Ett paket definierar namngivna distributionsmiljöer kallade mål i databricks.yml, som var och en pekar på sina egna arbetsyta, katalog- och variabelvärden. Mål är hur du främjar samma pipeline genom utveckling, staging och produktion, och distribuerar identisk källkod till varje efterföljande miljö utan att redigera den:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Det mode du sätter på varje mål ändrar dess distributionsbeteende:

• mode: development markerar ett mål som en personlig, obetydlig utplacering. Resurser får ett [dev username] prefix och scheman pausas som standard, så ditt arbete påverkar ingen annan.
• mode: production Inaktiverar dessa säkerhetsinställningar. Tillsammans med run_as kan du köra pipelinen med ett tjänsthuvudnamn i stället för med en enskild persons konto, så att körningar inte avbryts när någon lämnar teamet eller byter roll. Azure Databricks rekommenderar en tjänsteprincip för staging och produktion. service_principal_name tar tjänstehuvudpersonens applikations-ID, inte dess visningsnamn. Du kan hämta applikations-ID:t från tjänstehuvudets sida i dina admininställningar för arbetsområdet.

För en fullständig beskrivning av lägenas beteenden, se distributionslägen för Declarative Automation Bundles och Ange en körningsidentitet för ett arbetsflöde i Declarative Automation Bundles.

För att promovera, distribuera samma paket till varje målsystem i tur och ordning och verifiera vid varje steg:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Istället för att hårdkoda katalognamn eller källvägar per miljö i din transformationskod, skicka in värdena från målet så att samma källkod körs oförändrad överallt. Hur du ställer in dem beror på ditt källspråk. Pipeline-parametrar gäller endast för SQL-källkod. För Python-källkod, använd pipelinefältet configuration och läs värdena med spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Mer information om att parameterisera pipelinekod finns i Använd parametrar med pipelines.

Konfigurera CI/CD

Eftersom en konverterad pipeline definieras helt som ett paket (YAML plus källfiler i Git), innebär det att sätta upp kontinuerlig integration och kontinuerlig leverans (CI/CD) för den att paketkommandon körs från ett CI-system som GitHub Actions eller Azure DevOps. För varje pullbegäran körs en bra baslinje:

1. pytest mot dina enhetstestningsbara transformeringsfunktioner. Se Enhetstestning för pipelines.
2. databricks bundle validate --target <env> för att upptäcka konfigurationsfel.
3. Valfritt: ett databricks bundle run i ett utkastsmål för att testa förväntningar mot exempeldata.

Följande GitHub Actions-arbetsflöde driftsätter i stagingmiljön vid sammanslagning till main med OpenID Connect-federering (OIDC) i stället för en lagrad token:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

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

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

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

Lägg produktionsdriftsättningen bakom ett manuellt godkännande (till exempel ett andra jobb som kräver ett godkännande i en GitHub-miljö, eller ett separat steg i Azure DevOps) så att en person uttryckligen godkänner varje promovering. Produktionsjobbet körs databricks bundle deploy --target prod med en tjänsteprincip som är begränsad till produktionsarbetsytan. För mer, se CI/CD på Azure Databricks.

Felsökning

Tips för framgång

• Använd alltid versionskontroll. Om du inte använder Databricks Git-mappar lagrar du dina projektunderkataloger och filer på en Git eller annan versionskontrollerad lagringsplats eller filsystem.
• Testa din pipeline i en icke-produktionsmiljö (till exempel en "utvecklings- eller testmiljö" innan du distribuerar den till en produktionsmiljö. Det är lätt att introducera en felkonfiguration av misstag.

Ytterligare resurser

Mer information om hur du använder paket för att definiera och hantera databearbetning finns i:

• Vad är deklarativa automationbundlar?
• Utveckla pipelines med deklarativa Automationspaket. Det här avsnittet beskriver hur du skapar ett paket för en ny pipeline i stället för en befintlig, med versionskontrollerade källfiler för bearbetning som du anger.