Convertire una pipeline in un progetto pacchetto

È possibile convertire una pipeline esistente in un progetto Declarative Automation Bundles. I bundle consentono di definire e gestire la configurazione dell'elaborazione dati di Azure Databricks in un singolo file YAML controllato dal codice sorgente che offre una manutenzione più semplice e consente la distribuzione automatica negli ambienti di destinazione.

Per un'esercitazione che usa i databricks pipelines comandi per creare un progetto di pipeline, quindi distribuisce ed esegue una pipeline, vedere Sviluppare pipeline con bundle di automazione dichiarativa.

Panoramica del processo di conversione

I passaggi da eseguire per convertire una pipeline esistente in un bundle sono:

1. Assicurati di avere accesso a una pipeline configurata in precedenza che vuoi convertire in un bundle.
2. Creare o preparare una cartella (preferibilmente in una gerarchia controllata dall'origine) per archiviare il bundle.
3. Generare una configurazione per il bundle dalla pipeline esistente usando il CLI di Databricks.
4. Esaminare la configurazione del bundle generato per assicurarsi che sia completata.
5. Collegare il bundle alla pipeline originale.
6. Distribuire la pipeline in un'area di lavoro di destinazione usando la configurazione del bundle.

Requisiti

Prima di iniziare, è necessario disporre di:

• CLI di Databricks installata sulla macchina di sviluppo locale. La versione 0.218.0 o superiore del CLI Databricks è necessaria per usare i Bundle di Automazione Dichiarativa.
• ID di una pipeline dichiarativa esistente che verrà gestita con un bundle. Per informazioni su come ottenere questo ID, vedere Ottenere una definizione di pipeline esistente usando l'interfaccia utente.
• Autorizzazione per l'area di lavoro di Azure Databricks in cui viene eseguita la pipeline esistente. Per configurare l'autenticazione e l'autorizzazione per le chiamate dell'interfaccia della riga di comando di Databricks, vedere Autorizzare l'accesso alle risorse di Azure Databricks.
• Per il set completo di privilegi necessari per creare, eseguire, aggiornare e visualizzare le pipeline e il relativo output, vedere Gestire identità, autorizzazioni e privilegi per le pipeline.

Passaggio 1: Configurare una cartella per il progetto bundle

È necessario avere accesso a un repository Git configurato in Azure Databricks come cartella Git. Verrà creato il progetto bundle in questo repository, che applicherà il controllo del codice sorgente e lo renderà disponibile ad altri collaboratori tramite una cartella Git nell'area di lavoro di Azure Databricks corrispondente. Per altre informazioni sulle cartelle Git, vedere Cartelle Git di Azure Databricks.

1. Passare alla radice del repository Git clonato sul tuo computer locale.

2. In una posizione appropriata nella gerarchia di cartelle, creare una cartella specifica per il progetto bundle. Per esempio:

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

3. Cambia la cartella di lavoro corrente in questa nuova cartella. Per esempio:

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

4. Inizializzare un nuovo bundle eseguendo:

   databricks bundle init
   

   Rispondere alle richieste. Al termine, si avrà un file di configurazione del progetto denominato databricks.yml nella nuova cartella home per il progetto. Questo file è necessario per distribuire la pipeline dalla riga di comando. Per altri dettagli su questo file di configurazione, vedere Configurazione dei bundle di automazione dichiarativa.

Passaggio 2: Generare la configurazione della pipeline

Da questa nuova directory nell'albero delle cartelle del repository Git clonato, eseguire il comando bundle generate dell'interfaccia della riga di comando di Databricks, specificando l'ID della pipeline come: <pipeline-id>

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

Quando si esegue il comando generate, crea un file di configurazione del bundle per la pipeline nella cartella del resources bundle e scarica gli artefatti di riferimento nella cartella src. Il --profile flag (o -p ) è facoltativo, ma se si dispone di un profilo di configurazione di Databricks specifico (definito nel .databrickscfg file creato quando è stata installata l'interfaccia della riga di comando di Databricks) che si preferisce usare anziché il profilo predefinito, specificarlo in questo comando. Per informazioni sui profili di configurazione di Databricks, vedere Profili di configurazione di Azure Databricks.

Passaggio 3: Esaminare i file di progetto bundle

Al termine del comando bundle generate, verranno create due nuove cartelle:

• resources è la sottodirectory del progetto che contiene i file di configurazione del progetto.
• src è la cartella del progetto in cui vengono archiviati i file di origine, ad esempio query e notebook.

Il comando crea anche alcuni file aggiuntivi:

• *.pipeline.yml nella sottodirectory resources. Questo file contiene la configurazione e le impostazioni specifiche per la pipeline.
• File di origine, ad esempio query SQL nella src sottodirectory, copiati dalla pipeline esistente.

├── 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

Passaggio 4: Associare la pipeline di bundle alla pipeline esistente

È necessario collegare o associare la definizione della pipeline nel bundle alla pipeline esistente per mantenerla aggiornata man mano che si apportano modifiche. A tale scopo, eseguire il comando bundle deployment bind dell'interfaccia a riga di comando di Databricks:

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

<pipeline-name> è il nome della pipeline. Questo nome deve corrispondere al valore di stringa con prefisso del nome del file per la configurazione della pipeline nella tua nuova directory resources. Ad esempio, se si dispone di un file di configurazione della pipeline denominato ingestion_data_pipeline.pipeline.yml nella cartella resources, è necessario specificare ingestion_data_pipeline come nome della pipeline.

<pipeline-ID> è l'ID della pipeline. È lo stesso di quello che hai copiato come parte dei requisiti per queste istruzioni.

Passaggio 5: Distribuisci la tua pipeline utilizzando il tuo nuovo bundle

Distribuire ora il bundle della pipeline nell'area di lavoro di destinazione usando il comando bundle deploy della CLI di Databricks.

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

Il flag --target è obbligatorio e deve essere impostato su una stringa corrispondente a un nome dell'area di lavoro di destinazione configurato, ad esempio development o production.

Se questo comando ha esito positivo, è ora disponibile la configurazione della pipeline in un progetto esterno che può essere caricato in altre aree di lavoro ed eseguito e condiviso facilmente con altri utenti di Azure Databricks nell'account.

Promuovi tra ambienti con obiettivi

Un bundle definisce ambienti di distribuzione denominati target in databricks.yml, ognuno dei quali fa riferimento al proprio workspace, catalogo e ai propri valori delle variabili. I target sono il modo in cui promuovi la stessa pipeline attraverso sviluppo, staging e produzione, distribuendo codice sorgente identico a ciascun ambiente successivo senza modificarlo:

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'

L'impostazione mode che configuri per ciascun target ne modifica il comportamento di distribuzione:

• mode: development contrassegna una destinazione come una distribuzione personale e temporanea. Le risorse ricevono un [dev username] prefisso e gli orari sono messi in pausa di default, così il tuo lavoro non influenza nessun altro.
• mode: production Disattiva quei valori di sicurezza predefiniti. Combinato con run_as, ti permette di gestire la pipeline come principale di servizio invece che come account individuale, così le run non si interrompono quando qualcuno lascia il team o cambia ruolo. Azure Databricks raccomanda un principio di servizio per staging e produzione. service_principal_name prende l'ID dell'applicazione del principale del servizio, non il suo nome visualizzato. Puoi recuperare l'ID dell'applicazione dalla pagina del principale del servizio nelle impostazioni amministrative dello spazio di lavoro.

Per l'elenco completo dei comportamenti delle modalità, vedi modalità di distribuzione di Declarative Automation Bundles e Specifica un'identità di esecuzione per un flusso di lavoro di Declarative Automation Bundles.

Per la promozione, distribuisci lo stesso pacchetto a ogni destinazione in successione, verificando in ogni fase:

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

Invece di codificare manualmente i nomi dei cataloghi o i percorsi sorgente per ogni ambiente all'interno del tuo codice di trasformazione, passa i valori dal target così la stessa sorgente gira ovunque senza modifica. Come li imposti dipende dalla lingua originaria. I parametri della pipeline si applicano solo al codice sorgente SQL. Per il codice sorgente Python, usa il campo pipeline configuration e leggi i valori con: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

Per saperne di più sulla parametrizzazione del codice delle pipeline, vedi Usa parametri con pipeline.

Configura CI/CD

Poiché una pipeline convertita è definita interamente come bundle (YAML più file sorgente in Git), impostare un'integrazione continua e la consegna continua (CI/CD) significa eseguire i comandi bundle da un sistema CI come GitHub Actions o Azure DevOps. Per ogni pull request, viene eseguita una buona baseline di base:

1. pytest contro le tue funzioni di trasformazione testabili con test unitari. Vedi test unitari delle pipeline.
2. databricks bundle validate --target <env> per rilevare errori di configurazione.
3. Facoltativamente, un databricks bundle run in una destinazione scratch per verificare le aspettative sui dati di esempio.

Il seguente flusso di lavoro GitHub Actions esegue il deployment nell'ambiente di staging in caso di merge su main, utilizzando la federazione OpenID Connect (OIDC) invece di un token archiviato:

# .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

Confina il deployment in produzione dietro un'approvazione manuale (ad esempio, un secondo lavoro che richiede l'approvazione di un ambiente GitHub, o una fase separata in Azure DevOps) così che una persona approvi esplicitamente ogni promozione. Il processo di produzione viene eseguito databricks bundle deploy --target prod utilizzando un'entità servizio con ambito limitato all'area di lavoro di produzione. Per maggiori informazioni, vedi CI/CD su Azure Databricks.

Risoluzione dei problemi

Suggerimenti per il successo

• Usare sempre il controllo della versione. Se non si usano cartelle Git di Databricks, archiviare le sottodirectory e i file del progetto in un repository Git o in un altro sistema a controllo di versione.
• Testare la pipeline in un ambiente non di produzione ( ad esempio un ambiente di "sviluppo" o "test") prima di distribuirlo in un ambiente di produzione. È facile introdurre una configurazione errata per caso.

Risorse aggiuntive

Per altre informazioni sull'uso di bundle per definire e gestire l'elaborazione dei dati, vedere:

• Che cosa sono i bundle di automazione dichiarativa?
• Sviluppare pipeline con pacchetti di automazione dichiarativa. In questo argomento viene illustrata la creazione di un bundle per una nuova pipeline anziché per una esistente, con file di origine controllati dalla versione che fornite voi per l'elaborazione.