Gestisci le dipendenze della pipeline in Dataflow

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

Il seguente elenco fornisce alcuni motivi per cui potresti dover gestire le dipendenze della pipeline:

Le dipendenze fornite dall'ambiente di runtime predefinito non sono sufficienti per il tuo caso d'uso.
Le dipendenze predefinite presentano conflitti di versione o hanno classi e librerie incompatibili con il codice della pipeline.
Devi bloccare 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 pipeline contiene impostazioni e codice specifici per l'utente, il codice non può contenere versioni miste delle librerie.

Problemi di dipendenza Java

Quando la tua 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 in classpath utilizza una versione che non contiene il metodo corretto o quando la firma del metodo è stata modificata.
NoSuchFieldError: questo errore si verifica quando la classe in classpath utilizza una versione che non ha un campo obbligatorio durante il runtime.
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, come Conscrypt.

Gestione delle dipendenze

Per semplificare la gestione delle dipendenze per le pipeline Java, Apache Beam utilizza gli artefatti Bill of Materials (BOM). che consente agli strumenti di gestione delle dipendenze di selezionare combinazioni di dipendenze compatibili. Per ulteriori informazioni, consulta SDK Apache Beam per le dipendenze Java nella documentazione di Apache Beam.

Per utilizzare una distinta base con la pipeline e aggiungere esplicitamente altre dipendenze all'elenco delle dipendenze, aggiungi le seguenti informazioni al file pom.xml per l'artefatto SDK. Per importare il BOM delle librerie corretto, 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'artefatto beam-sdks-java-core contiene solo l'SDK principale. Devi aggiungere esplicitamente altre dipendenze, come I/O e runner, all'elenco delle dipendenze.

Python

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

La tua pipeline utilizza pacchetti pubblici dell'indice dei pacchetti Python (PiPy) e vuoi renderli disponibili in remoto.
Vuoi creare un ambiente riproducibile.
Per ridurre i tempi di avvio, vuoi evitare l'installazione delle dipendenze sui worker in fase di runtime.

Definisci le dipendenze della pipeline Python

Anche se puoi utilizzare un singolo blocco note o script Python per scrivere una pipeline Apache Beam, nell'ecosistema Python il software viene spesso distribuito sotto forma di pacchetti. Per semplificare la gestione della pipeline, quando il codice della pipeline comprende più file, raggruppa i file della pipeline come pacchetto Python.

Definisci le dipendenze della pipeline nel file setup.py del pacchetto.
Invia temporaneamente il pacchetto ai worker utilizzando l'opzione della pipeline --setup_file.

All'avvio dei lavoratori da remoto, installano il pacchetto. Per un esempio, consulta juliaset nel GitHub di Apache Beam.

Per strutturare la pipeline come pacchetto Python, segui questi passaggi:

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(),
)
```
Aggiungi il file setup.py, il file del flusso di lavoro principale e una directory con il resto dei file alla directory radice del progetto. Questo raggruppamento di file è il pacchetto Python per la tua 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
```
Per eseguire la pipeline, installa il pacchetto nell'ambiente di invio. Utilizza l'opzione della pipeline --setup_file per posizionare temporaneamente il pacchetto nei 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 Python Apache Beam, i lavoratori Dataflow devono avere 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 queste immagini includono le dipendenze dell'SDK Apache Beam. Per maggiori informazioni, consulta SDK Apache Beam per le dipendenze Python nella documentazione di Apache Beam.

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

Il tempo di avvio dei worker aumenta a causa della risoluzione, del download e dell'installazione delle dipendenze.
Per l'esecuzione della pipeline è necessaria una connessione a internet.
Il non determinismo si verifica a causa di release del software nelle dipendenze.

Per evitare questi problemi, fornisci l'ambiente di runtime in un'immagine container Docker personalizzata. L'utilizzo di un'immagine di container Docker personalizzata in cui le dipendenze della pipeline sono 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 di Dataflow.
Ti consente di controllare l'ambiente di runtime della tua pipeline.
Evita una risoluzione delle dipendenze dispendiosa in termini di tempo all'avvio.

Quando utilizzi immagini container personalizzate, prendi in considerazione le seguenti indicazioni:

Evita di utilizzare il tag :latest con le immagini personalizzate. Applica il tagging alle build con una data, una versione o un identificatore univoco. Questo passaggio consente di tornare a una configurazione di lavoro nota, se necessario.
Utilizza un ambiente di avvio compatibile con l'immagine container. Per ulteriori indicazioni sull'uso di container personalizzati, consulta Creare un'immagine container.

Per maggiori dettagli sulla preinstallazione delle dipendenze Python, consulta Preinstallare le dipendenze Python.

Controlla l'ambiente di lancio con i modelli Dataflow

Se la tua pipeline richiede ulteriori dipendenze, potrebbe essere necessario installarle sia nell'ambiente di runtime che 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 containerizzato e riproducibile, utilizza i modelli flessibili di Dataflow. Per maggiori informazioni, consulta Creare ed eseguire un modello flessibile. Quando utilizzi i modelli flessibili, prendi in considerazione i seguenti fattori:

Se configuri la pipeline come pacchetto, installa il pacchetto nel Dockerfile del modello. Per configurare il modello flessibile, specifica FLEX_TEMPLATE_PYTHON_SETUP_FILE. Per maggiori informazioni, consulta Impostare le variabili di ambiente Dockerfile richieste.
Se utilizzi un'immagine container personalizzata con la tua pipeline, forniscila quando avvii il modello. Per maggiori informazioni, consulta Utilizzare un container personalizzato per le dipendenze.
Per creare l'immagine Docker del modello flessibile per Dataflow, utilizza la stessa immagine container personalizzata dell'immagine di base. Per maggiori informazioni, consulta Utilizzare immagini container personalizzate.

Questa struttura rende l'ambiente di lancio riproducibile e compatibile con il tuo ambiente di runtime.

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

Per maggiori 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.

Go

Quando esegui job Dataflow utilizzando l'SDK Apache Beam Go, i moduli Go vengono utilizzati per gestire le dipendenze. Il seguente file contiene le dipendenze di compilazione e 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 Gestione delle dipendenze nella documentazione di Go.