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 del trattamento dei dati traggono vantaggio dall'utilizzo di librerie o classi aggiuntive. In questi casi, potrebbe essere necessario gestire le dipendenze della pipeline.

L'elenco seguente fornisce 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 conflitti di versione o classi e librerie incompatibili con il codice della pipeline.
  • Devi bloccare le versioni specifiche delle librerie per la tua pipeline.
  • Hai una pipeline Python che deve essere eseguita con un insieme coerente di dipendenze.

La modalità di gestione delle dipendenze varia a seconda che la pipeline utilizzi Java, Python o Go.

Java

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

Problemi di dipendenza Java

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

  • NoClassDefFoundError: questo errore si verifica quando un'intera classe non è disponibile durante il runtime.
  • NoSuchMethodError: questo errore si verifica quando la classe nel classpath 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 classpath utilizza una versione che non ha un campo richiesto durante l'esecuzione.
  • FATAL ERROR: questo errore si verifica quando una dipendenza integrata non può essere caricata correttamente. Quando utilizzi un file JAR uber (ombreggiato), non includere librerie che utilizzano 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 artefatti Bill of Materials (BOM). La distinta materiali aiuta gli strumenti di gestione delle dipendenze a selezionare combinazioni di dipendenze compatibili. Per maggiori informazioni, consulta la sezione Dipendenze dell'Apache Beam SDK per Java nella documentazione di Apache Beam.

Per utilizzare una distinta base con la tua pipeline e aggiungere esplicitamente altre dipendenze all'elenco delle dipendenze, aggiungi le seguenti informazioni al file pom.xml per l'artefatto SDK. Per importare la distinta materiali delle librerie corrette, utilizza beam-sdks-java-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'artefatto 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 Python, la gestione delle dipendenze è utile nei seguenti scenari:

  • La pipeline utilizza pacchetti pubblici di Python Package Index (PiPy) e vuoi rendere disponibili questi pacchetti da remoto.
  • Vuoi creare un ambiente riproducibile.
  • Per ridurre il tempo di avvio, devi evitare l'installazione delle dipendenze sui worker al runtime.

Definisci 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 manutenzione della pipeline, se 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.
  • Prepara il pacchetto per i lavoratori utilizzando l'opzione della pipeline --setup_file.

Quando i lavoratori remoti iniziano, installano il tuo pacchetto. Per un esempio, vedi juliaset su 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 il set 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 tua pipeline. La struttura del file è simile al seguente esempio:

    root_dir/
  package_name/
    __init__.py
    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 preparare il pacchetto per i 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 in dimensioni e complessità. Per altri modi per specificare le dipendenze, consulta Gestione delle 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 Python, i worker Dataflow hanno bisogno di un ambiente Python che contenga un interprete, l'SDK Apache Beam e le dipendenze della pipeline. Le immagini container Docker forniscono l'ambiente appropriato per l'esecuzione del codice della pipeline.

Le immagini container stock vengono rilasciate con ogni versione dell'SDK Apache Beam e includono le dipendenze dell'SDK Apache Beam. Per maggiori informazioni, consulta la sezione Dipendenze dell'SDK Apache Beam per Python nella documentazione di Apache Beam.

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

  • Il tempo di avvio del worker aumenta a causa della risoluzione, del download e dell'installazione delle dipendenze.
  • La pipeline richiede una connessione a internet per essere eseguita.
  • 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.
  • 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. Assegna un tag alle tue build 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 container. Per ulteriori indicazioni sull'utilizzo dei container personalizzati, consulta Crea un'immagine container.

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

Controllare l'ambiente di lancio con i modelli Dataflow

Se la pipeline richiede dipendenze aggiuntive, potrebbe essere necessario installarle sia nell'ambiente di runtime sia nell'ambiente di avvio. 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 disporre di un ambiente di avvio containerizzato e riproducibile, utilizza i modelli flessibili Dataflow. Per saperne di più, vedi Creare ed eseguire un modello flessibile. Quando utilizzi i modelli flessibili, tieni presente 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 l'esercitazione Modello flessibile per una pipeline con dipendenze e un container personalizzato su GitHub.

Per ulteriori informazioni, consulta le sezioni 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 che stai utilizzando.

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