Gestire le dipendenze della pipeline in Dataflow

Molte pipeline Apache Beam possono essere eseguite utilizzando gli ambienti di runtime Dataflow predefiniti. Tuttavia, alcuni casi d'uso di elaborazione dei dati traggono vantaggio dall'utilizzo di librerie o classi aggiuntive. In questi casi, potrebbe essere necessario gestire le dipendenze della pipeline.

Di seguito sono riportati alcuni motivi per cui potresti dover gestire le dipendenze della pipeline:

  • Le dipendenze fornite dall'ambiente di runtime predefinito sono insufficienti per il tuo caso d'uso.
  • Le dipendenze predefinite presentano collisioni di versioni o contengono classi e librerie incompatibili con il codice della pipeline.
  • Devi bloccare versioni specifiche della libreria per la pipeline.
  • Hai una pipeline Python che deve essere eseguita con un insieme coerente di dipendenze.

Il modo in cui gestisci le dipendenze dipende dal fatto che la pipeline utilizzi Java, Python o Go.

Java

Classi e librerie incompatibili possono causare problemi di dipendenza da Java. Se la pipeline contiene codice e impostazioni specifici per l'utente, il codice non può contenere versioni miste delle librerie.

Problemi di dipendenza Java

Quando la pipeline presenta problemi di dipendenza da Java, potrebbe verificarsi uno dei seguenti errori:

  • NoClassDefFoundError: questo errore si verifica quando un intero corso non è disponibile durante il runtime.
  • NoSuchMethodError: questo errore si verifica quando la classe nel percorso di classe utilizza una versione che non contiene il metodo corretto o quando la firma del metodo è cambiata.
  • NoSuchFieldError: questo errore si verifica quando la classe nel percorso di classe utilizza una versione che non ha un campo obbligatorio durante l'esecuzione.
  • FATAL ERROR: questo errore si verifica quando non è possibile caricare correttamente una dipendenza integrata. Quando utilizzi un file JAR uber (ombreggiato), non includere le librerie che utilizzano le firme nello stesso file JAR, ad esempio Conscrypt.

Gestione delle dipendenze

Per semplificare la gestione delle dipendenze per le pipeline Java, Apache Beam utilizza gli elementi Bill of Materials (BOM). La BOM aiuta gli strumenti di gestione delle dipendenze a selezionare combinazioni di dipendenze compatibili. Per saperne di più, consulta la sezione Dipendenze dell'SDK Apache Beam per Java nella documentazione di Apache Beam.

Per utilizzare un BOM con la pipeline e aggiungere esplicitamente altre dipendenze all'elenco delle dipendenze, aggiungi le seguenti informazioni al file pom.xml per l'elemento SDK. Per importare la distinta base delle librerie corretta, utilizza beam-sdks-java-io-google-cloud-platform-bom.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.beam</groupId>
      <artifactId>beam-sdks-java-google-cloud-platform-bom</artifactId>
      <version>LATEST</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-core</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-runners-google-cloud-dataflow-java</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-io-google-cloud-platform</artifactId>
  </dependency>
</dependencies>

L'elemento beam-sdks-java-core contiene solo l'SDK di base. Devi aggiungere esplicitamente altre dipendenze, come I/O e runner, all'elenco delle dipendenze.

Python

Quando esegui job Dataflow utilizzando l'SDK Apache Beam per Python, la gestione delle dipendenze è utile nei seguenti scenari:

  • La tua pipeline utilizza i pacchetti pubblici del Python Package Index (PiPy) e vuoi metterli a disposizione da remoto.
  • Vuoi creare un ambiente riproducibile.
  • Per ridurre il tempo di avvio, devi evitare di installare le dipendenze sui worker al runtime.

Definire le dipendenze della pipeline Python

Sebbene sia possibile utilizzare un singolo script o notebook Python per scrivere una pipeline Apache Beam, nell'ecosistema Python il software viene spesso distribuito come pacchetti. Per semplificare la gestione della pipeline, quando il codice della pipeline si estende su più file, raggruppa i file della pipeline come pacchetto Python.

  • Definisci le dipendenze della pipeline nel file setup.py del pacchetto.
  • Esegui la gestione delle fasi del pacchetto per i worker utilizzando l'opzione della pipeline --setup_file.

Quando i lavoratori remoti iniziano, installano il tuo pacchetto. Per un esempio, consulta juliaset nel repository GitHub di Apache Beam.

Per strutturare la pipeline come pacchetto Python:

  1. Crea un file setup.py per il tuo progetto. Nel file setup.py, includi l'argomento install_requires per specificare l'insieme minimo di dipendenze per la pipeline. L'esempio seguente mostra un file setup.py di base.

    import setuptools

setuptools.setup(
  name='PACKAGE_NAME',
  version='PACKAGE_VERSION',
  install_requires=[],
  packages=setuptools.find_packages(),
)

  2. Aggiungi il file setup.py, il file del flusso di lavoro principale e una directory con il resto dei file alla directory principale del progetto. Questo raggruppamento di file è il pacchetto Python per la pipeline. La struttura del file è simile all'esempio seguente:

    root_dir/
  package_name/
    my_pipeline_launcher.py
    my_custom_transforms.py
    ...other files...
  setup.py
  main.py

  3. Per eseguire la pipeline, installa il pacchetto nell'ambiente di invio. Utilizza l'opzione della pipeline --setup_file per eseguire lo staging del pacchetto sui worker. Ad esempio:

    python -m pip install -e .
python main.py --runner DataflowRunner --setup_file ./setup.py  <...other options...>

Questi passaggi semplificano la manutenzione del codice della pipeline, in particolare quando il codice aumenta di dimensioni e complessità. Per altri modi per specificare le dipendenze, consulta Gestire le dipendenze della pipeline Python nella documentazione di Apache Beam.

Utilizzare container personalizzati per controllare l'ambiente di runtime

Per eseguire una pipeline con l'SDK Apache Beam per Python, i worker Dataflow devono avere un ambiente Python contenente un interprete, l'SDK Apache Beam e le dipendenze della pipeline. Le immagini dei container Docker forniscono l'ambiente appropriato per l'esecuzione del codice della pipeline.

Le immagini dei contenitori di serie vengono rilasciate con ogni versione dell'SDK Apache Beam e includono le dipendenze dell'SDK Apache Beam. Per saperne di più, consulta Dipendenze dell'SDK Apache Beam per Python nella documentazione di Apache Beam.

Quando la pipeline richiede una dipendenza non inclusa nell'immagine del container predefinita, la dipendenza deve essere installata in fase di runtime. L'installazione dei pacchetti in fase di esecuzione può avere le seguenti conseguenze:

  • Il tempo di avvio del worker aumenta a causa della risoluzione delle dipendenze, del download e dell'installazione.
  • Per funzionare, la pipeline richiede una connessione a internet.
  • Il non determinismo si verifica a causa delle release software nelle dipendenze.

Per evitare questi problemi, fornisci l'ambiente di runtime in un'immagine di container Docker personalizzata. L'utilizzo di un'immagine container Docker personalizzata con le dipendenze della pipeline preinstallate offre i seguenti vantaggi:

  • Garantisce che l'ambiente di runtime della pipeline abbia lo stesso insieme di dipendenze ogni volta che avvii il job Dataflow.
  • Ti consente di controllare l'ambiente di runtime della pipeline.
  • Evita la risoluzione delle dipendenze potenzialmente dispendiosa in termini di tempo all'avvio.

Quando utilizzi immagini container personalizzate, tieni presente le seguenti indicazioni:

  • Evita di utilizzare il tag :latest con le immagini personalizzate. Tagga le tue compilazioni con una data, una versione o un identificatore univoco. Questo passaggio ti consente di ripristinare una configurazione funzionante nota, se necessario.
  • Utilizza un ambiente di lancio compatibile con l'immagine del container. Per ulteriori indicazioni sull'utilizzo dei container personalizzati, consulta Creare un'immagine del contenitore.

Per informazioni dettagliate sulla preinstallazione delle dipendenze Python, consulta Preinstallare le dipendenze Python.

Controllare l'ambiente di lancio con i modelli Dataflow

Se la pipeline richiede dipendenze aggiuntive, potresti doverle installare sia nell'ambiente di runtime sia nell'ambiente di lancio. L'ambiente di lancio esegue la versione di produzione della pipeline. Poiché l'ambiente di lancio deve essere compatibile con l'ambiente di runtime, utilizza le stesse versioni delle dipendenze in entrambi gli ambienti.

Per avere un ambiente di lancio riproducibile e in container, utilizza i modelli flessibili di Dataflow. Per saperne di più, consulta Creare ed eseguire un modello flessibile. Quando utilizzi i modelli flessibili, prendi in considerazione i seguenti fattori:

Questa costruzione rende l'ambiente di lancio riproducibile e compatibile con l'ambiente di runtime.

Per un esempio che segue questo approccio, consulta il tutorial su GitHub Modello flessibile per una pipeline con dipendenze e un contenitore personalizzato.

Per ulteriori informazioni, consulta Rendere l'ambiente di lancio compatibile con l'ambiente di runtime e Controllare le dipendenze utilizzate dalla pipeline nella documentazione di Apache Beam.

Vai

Quando esegui i job Dataflow utilizzando l'SDK Apache Beam Go, vengono utilizzati i moduli Go per gestire le dipendenze. Il seguente file contiene le dipendenze di compilazione e di runtime predefinite utilizzate dalla pipeline:

https://raw.githubusercontent.com/apache/beam/vVERSION_NUMBER/sdks/go.sum

Sostituisci VERSION_NUMBER con la versione dell'SDK in uso.

Per informazioni sulla gestione delle dipendenze per la pipeline Go, consulta Gestire le dipendenze nella documentazione di Go.