Een pijplijn converteren naar een bundelproject

U kunt een bestaande pipeline omzetten in een Declarative Automation Bundles-project. Met bundels kunt u uw configuratie voor gegevensverwerking van Azure Databricks definiëren en beheren in één, door bron beheerd YAML-bestand dat eenvoudiger onderhoud biedt en geautomatiseerde implementatie naar doelomgevingen mogelijk maakt.

Zie databricks pipelines voor een zelfstudie die gebruikmaakt van opdrachten voor het maken van een pijplijnproject en vervolgens een pijplijn implementeert en uitvoert.

Overzicht van conversieproces

diagram met de specifieke stappen voor het converteren van een bestaande pijplijn naar een bundel

De stappen die u uitvoert om een bestaande pijplijn te converteren naar een bundel zijn:

  1. Zorg ervoor dat u toegang hebt tot een eerder geconfigureerde pijplijn die u wilt converteren naar een bundel.
  2. Maak of bereid een map (bij voorkeur in een bronbeheerde hiërarchie) voor om de bundel op te slaan.
  3. Genereer een configuratie voor de bundel vanuit de bestaande pijplijn met behulp van de Databricks CLI.
  4. Controleer de gegenereerde bundelconfiguratie om te controleren of deze is voltooid.
  5. Koppel de bundel aan de oorspronkelijke pijplijn.
  6. Implementeer de pijplijn in een doelwerkruimte met behulp van de bundelconfiguratie.

Requirements

Voordat u begint, moet u het volgende hebben:

Stap 1: Een map instellen voor uw bundelproject

U moet toegang hebben tot een Git-opslagplaats die is geconfigureerd in Azure Databricks als een Git-map. U maakt uw bundelproject in deze opslagplaats, dat broncodebeheer toepast en beschikbaar maakt voor andere medewerkers via een Git-map in de bijbehorende Azure Databricks-werkruimte. (Zie Azure Databricks Git-mappen voor meer informatie over Git-mappen.)

  1. Ga naar de hoofdmap van de gekloonde Git-opslagplaats op uw lokale computer.

  2. Maak op een geschikte plaats in de mappenhiërarchie een map die specifiek is voor uw projectbundel. Voorbeeld:

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

  3. Wijzig de huidige werkmap in deze nieuwe map. Voorbeeld:

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

  4. Initialiseer een nieuwe bundel door het volgende uit te voeren:

    databricks bundle init

    Beantwoord de aanwijzingen. Zodra dit is voltooid, hebt u een projectconfiguratiebestand met de naam databricks.yml in de nieuwe basismap voor uw project. Dit bestand is vereist voor het implementeren van uw pijplijn via de opdrachtregel. Voor meer informatie over dit configuratiebestand, zie Declarative Automation Bundles configuration.

Stap 2: De pijplijnconfiguratie genereren

Voer vanuit deze nieuwe map in de mapstructuur van uw gekloonde Git-opslagplaats de opdracht voor het genereren van de Databricks CLI-bundel uit, waarbij u de id van uw pijplijn opslaat als <pipeline-id>:

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

Wanneer u de generate opdracht uitvoert, wordt er een bundelconfiguratiebestand voor uw pijplijn gemaakt in de map van resources de bundel en worden eventuele artefacten waarnaar wordt verwezen naar de src map gedownload. De --profile (of -p vlag) is optioneel, maar als u een specifiek Databricks-configuratieprofiel hebt (gedefinieerd in uw .databrickscfg bestand dat is gemaakt toen u de Databricks CLI hebt geïnstalleerd) die u liever gebruikt in plaats van het standaardprofiel, geeft u dit op in deze opdracht. Zie Azure Databricks-configuratieprofielenvoor meer informatie over Databricks-configuratieprofielen.

Aanbeveling

Als u een bestaand SDP-project (Spark Declarative Pipelines) hebt (het heeft een spark-pipeline.yml bestand), kunt u dat pijplijnproject naar de src map van de bundel kopiëren en vervolgens de databricks pipelines generate opdracht gebruiken om de bundelconfiguratie voor het project te genereren. Zie databricks-pijplijnen genereren.

Stap 3: De bundelprojectbestanden controleren

Wanneer de opdracht bundle generate is voltooid, zijn er twee nieuwe mappen gemaakt:

  • resources is de submap van het project die projectconfiguratiebestanden bevat.
  • src is de projectmap waarin bronbestanden, zoals query's en notebooks, worden opgeslagen.

Met de opdracht worden ook enkele extra bestanden gemaakt:

  • *.pipeline.yml onder de submap resources. Dit bestand bevat de specifieke configuratie en instellingen voor uw pijplijn.
  • Bronbestanden, zoals SQL-query's in de src submap, gekopieerd vanuit uw bestaande pijplijn.
├── 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

Stap 4: Koppel de bundelpijplijn aan uw bestaande pijplijn

U moet de definitie van de pijplijn in de bundel koppelen of bindenaan uw bestaande pijplijn om deze actueel te houden terwijl u wijzigingen aanbrengt. Voer hiervoor het bind-commando van de Databricks CLI-bundel uit:

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

<pipeline-name> is de naam van de pijplijn. Deze naam moet hetzelfde zijn als de voorvoegseltekenreekswaarde van de bestandsnaam voor de pijplijnconfiguratie in uw nieuwe resources map. Als u bijvoorbeeld een pijplijnconfiguratiebestand met de naam ingestion_data_pipeline.pipeline.yml in de map resources hebt, moet u ingestion_data_pipeline opgeven als de naam van uw pijplijn.

<pipeline-ID> is de id voor uw pijplijn. Het is hetzelfde als degene die u hebt gekopieerd als onderdeel van de vereisten voor deze instructies.

Stap 5: Uw pijplijn implementeren met behulp van uw nieuwe bundel

Implementeer nu uw pijplijnbundel in uw doelwerkruimte met behulp van de opdracht Databricks CLI-bundel implementeren:

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

De vlag --target is vereist en moet worden ingesteld op een tekenreeks die overeenkomt met een geconfigureerde naam van de doelwerkruimte, zoals development of production.

Als deze opdracht is geslaagd, hebt u nu uw pijplijnconfiguratie in een extern project dat kan worden geladen in andere werkruimten en kan worden uitgevoerd en eenvoudig kan worden gedeeld met andere Azure Databricks-gebruikers in uw account.

Doorzetten tussen omgevingen met doelen

Een bundel definieert benoemde deploymentomgevingen genaamd targets in databricks.yml, elk wijzend naar zijn eigen werkruimte-, catalogus- en variabelewaarden. Targets zijn hoe je dezelfde pipeline promoot via dev, staging en productie, waarbij identieke broncode wordt uitgezet naar elke opeenvolgende omgeving zonder deze te bewerken:

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'

De mode die u voor elk doel instelt, verandert het implementatiegedrag:

  • mode: development markeert een doel als een persoonlijke, ad-hocimplementatie. Resources krijgen een [dev username] prefix en schema's worden standaard gepauzeerd, dus je werk heeft geen invloed op anderen.
  • mode: production schakelt die standaardveiligheidsinstellingen uit. In combinatie met run_as, kun je de pipeline runnen als service principal in plaats van als individueel account, zodat runs niet kapot gaan als iemand het team verlaat of van rol verandert. Azure Databricks raadt een serviceprincipal aan voor staging en productie. service_principal_name gebruikt de toepassings-ID van de service principal, niet de weergavenaam. Je kunt de toepassings-ID vinden op de pagina van de service principal in de beheerdersinstellingen van je workspace.

Voor de volledige set modegedragingen, zie Declarative Automation Bundles deployment modes en Specificeer een run identity voor een Declarative Automation Bundles-workflow.

Om te promoveren, zet je dezelfde bundel op elk doelwit achtereenvolgens in, waarbij je bij elke fase verifieert:

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

In plaats van catalogusnamen of bronpaden per omgeving binnen je transformatiecode hardcodisch te coderen, geef je de waarden door van het doel zodat dezelfde bron overal ongewijzigd draait. Hoe je ze instelt hangt af van je brontaal. Pipeline-parameters gelden alleen voor SQL-broncode. Voor Python-broncode gebruik je het pipeline-veld configuration en lees je de waarden met 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

Voor meer informatie over het parametriseren van pijplijncode, zie Gebruik parameters met pijplijnen.

CI/CD instellen

Omdat een geconverteerde pijplijn volledig wordt gedefinieerd als een bundel (YAML plus bronbestanden in Git), betekent het opzetten van continue integratie en continue levering (CI/CD) ervoor dat de bundelcommando's vanaf een CI-systeem zoals GitHub Actions of Azure DevOps worden uitgevoerd. Bij elke pull request volgt een goede baseline:

  1. pytest op je met unit-tests testbare transformatiefuncties. Zie Eenheidstests voor pijplijnen.
  2. databricks bundle validate --target <env> om configuratiefouten op te sporen.
  3. Optioneel: gebruik een databricks bundle run in een testdoel om verwachtingen te toetsen aan de hand van voorbeeldgegevens.

De volgende GitHub Actions-workflow rolt uit naar staging na het mergen naar main, waarbij OpenID Connect (OIDC)-federatie wordt gebruikt in plaats van een opgeslagen 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

Zet de productie-implementatie achter een handmatige goedkeuring (bijvoorbeeld een tweede baan die een goedkeuring van de GitHub-omgeving vereist, of een aparte fase in Azure DevOps) zodat iemand elke promotie expliciet goedkeurt. De productietaak draait databricks bundle deploy --target prod met een serviceprincipe die is afgestemd op de productiewerkruimte. Voor meer, zie CI/CD op Azure Databricks.

Probleemoplossingsproces

Probleem Solution
Fout 'databricks.yml niet gevonden' bij het uitvoeren van bundle generate Op dit moment maakt de bundle generate opdracht het bundelconfiguratiebestand (databricks.yml) niet automatisch. U moet het bestand maken met behulp van databricks bundle init of handmatig.
Bestaande pijplijninstellingen komen niet overeen met de waarden in de gegenereerde YAML-configuratie van de pijplijn De pijplijn-id wordt niet weergegeven in het YML-bestand van de bundelconfiguratie. Als u andere ontbrekende instellingen ziet, kunt u deze handmatig toepassen.

Tips voor succes

  • Gebruik altijd versiebeheer. Als u geen Databricks Git-mappen gebruikt, slaat u de submappen en bestanden van uw project op in een Git- of andere door versie beheerde opslagplaats of bestandssysteem.
  • Test uw pijplijn in een niet-productieomgeving (zoals een ontwikkel- of testomgeving) voordat u deze implementeert in een productieomgeving. Het is eenvoudig om per ongeluk een onjuiste configuratie te introduceren.

Aanvullende bronnen

Zie voor meer informatie over het gebruik van bundels voor het definiëren en beheren van gegevensverwerking:

  • Last updated on