Gérer les dépendances de pipeline dans Dataflow

De nombreux pipelines Apache Beam peuvent s'exécuter à l'aide des environnements d'exécution Dataflow par défaut. Toutefois, certains cas d'utilisation du traitement des données exploitent l'utilisation de bibliothèques ou de classes supplémentaires. Dans ces cas, vous devrez peut-être gérer les dépendances de votre pipeline.

La liste suivante fournit certaines raisons pour lesquelles vous devrez peut-être gérer vos dépendances de pipeline :

Les dépendances fournies par l'environnement d'exécution par défaut sont insuffisantes pour votre cas d'utilisation.
Les dépendances par défaut présentent des conflits de version ou comportent des classes et des bibliothèques incompatibles avec le code de votre pipeline.
Vous devez épingler des versions de bibliothèque spécifiques de votre pipeline.
Vous disposez d'un pipeline Python qui doit s'exécuter avec un ensemble cohérent de dépendances.

La manière dont vous gérez les dépendances varie selon que votre pipeline utilise Java, Python ou Go.

Java

Les classes et les bibliothèques incompatibles peuvent entraîner des problèmes de dépendance Java. Si votre pipeline contient du code et des paramètres spécifiques à l'utilisateur, le code ne peut pas contenir de versions mixtes des bibliothèques.

Problèmes de dépendance Java

Lorsque votre pipeline rencontre des problèmes de dépendance Java, l'une des erreurs suivantes peut se produire :

NoClassDefFoundError : cette erreur se produit lorsqu'une classe entière n'est pas disponible pendant l'exécution.
NoSuchMethodError : cette erreur se produit lorsque la classe dans le chemin de classe utilise une version qui ne contient pas la bonne méthode ou lorsque la signature de la méthode a été modifiée.
NoSuchFieldError : cette erreur se produit lorsque la classe dans le chemin de classe utilise une version qui ne comporte pas un champ requis pendant l'exécution.
FATAL ERROR : cette erreur se produit lorsqu'une dépendance intégrée ne peut pas être chargée correctement. Lorsque vous utilisez un fichier Uber JAR (ombré), n'incluez pas de bibliothèques utilisant des signatures dans le même fichier JAR, comme Conscrypt.

Gestion des dépendances

Pour simplifier la gestion des dépendances pour les pipelines Java, Apache Beam utilise des artefacts de nomenclature (BOM). La BOM aide les outils de gestion des dépendances à sélectionner des combinaisons de dépendances compatibles. Pour en savoir plus, consultez la page sur le SDK Apache Beam pour les dépendances Java dans la documentation Apache Beam.

Pour utiliser une BOM avec votre pipeline et ajouter explicitement d'autres dépendances à la liste des dépendances, ajoutez les informations suivantes au fichier pom.xml de l'artefact SDK. Pour importer la BOM des bibliothèques appropriées, utilisez 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'artefact beam-sdks-java-core ne contient que le SDK principal. Vous devez ajouter explicitement d'autres dépendances, telles que des E/S et des exécuteurs, à la liste des dépendances.

Python

Lorsque vous exécutez des jobs Dataflow à l'aide du SDK Apache Beam pour Python, la gestion des dépendances est utile dans les scénarios suivants :

Votre pipeline utilise des packages publics issus de l'index de packages Python (PiPy) et vous souhaitez les rendre disponibles à distance.
Vous souhaitez créer un environnement reproductible.
Pour réduire le temps de démarrage, vous souhaitez éviter l'installation de dépendances sur les nœuds de calcul au moment de l'exécution.

Définir les dépendances de pipeline Python

Bien que vous puissiez utiliser un seul script ou un seul notebook Python pour écrire un pipeline Apache Beam, dans l'écosystème Python, les logiciels sont souvent distribués sous forme de packages. Pour faciliter la gestion de votre pipeline, lorsque son code s'étend sur plusieurs fichiers, regroupez les fichiers de pipeline en tant que package Python.

Définissez les dépendances du pipeline dans le fichier setup.py de votre package.
Préproduisez le package sur les nœuds de calcul à l'aide de l'option de pipeline --setup_file.

Lorsque les nœuds de calcul distants démarrent, ils installent votre package. Pour obtenir un exemple, consultez la page juliaset sur le GitHub d'Apache Beam.

Pour structurer votre pipeline en tant que package Python, procédez comme suit :

Créez un fichier setup.py pour votre projet. Dans le fichier setup.py, incluez l'argument install_requires pour spécifier l'ensemble minimal de dépendances pour votre pipeline. L'exemple suivant présente un fichier setup.py de base.
```
import setuptools

setuptools.setup(
  name='PACKAGE_NAME',
  version='PACKAGE_VERSION',
  install_requires=[],
  packages=setuptools.find_packages(),
)
```
Ajoutez le fichier setup.py, le fichier de workflow principal et un répertoire contenant le reste des fichiers dans le répertoire racine de votre projet. Ce regroupement de fichiers correspond au package Python de votre pipeline. La structure du fichier ressemble à l'exemple suivant :
```
root_dir/
  package_name/
    my_pipeline_launcher.py
    my_custom_transforms.py
    ...other files...
  setup.py
  main.py
```
Pour exécuter votre pipeline, installez le package dans l'environnement de soumission. Utilisez l'option de pipeline --setup_file pour préparer le package aux nœuds de calcul. Exemple :
```
python -m pip install -e .
python main.py --runner DataflowRunner --setup_file ./setup.py  <...other options...>
```

Ces étapes simplifient la maintenance du code du pipeline, en particulier lorsque sa taille et sa complexité augmentent. Pour découvrir d'autres moyens de spécifier des dépendances, consultez la page Gérer les dépendances de pipeline Python dans la documentation Apache Beam.

Utiliser des conteneurs personnalisés pour contrôler l'environnement d'exécution

Pour exécuter un pipeline avec le SDK Apache Beam pour Python, les nœuds de calcul Dataflow ont besoin d'un environnement Python contenant un interpréteur, le SDK Apache Beam et les dépendances de pipeline. Les images de conteneurs Docker fournissent l'environnement approprié pour exécuter le code de votre pipeline.

Les images de conteneurs stockées dans la banque d'images sont publiées avec chaque version du SDK Apache Beam. Ces images incluent les dépendances du SDK Apache Beam. Pour en savoir plus, consultez la page sur le SDK Apache Beam pour les dépendances Python dans la documentation Apache Beam.

Lorsque votre pipeline nécessite une dépendance qui n'est pas comprise dans l'image de conteneur par défaut, celle-ci doit être installée au moment de l'exécution. L'installation des packages lors de l'exécution peut avoir les conséquences suivantes :

Le temps de démarrage du nœud de calcul augmente en raison de la résolution, du téléchargement et de l'installation des dépendances.
Le pipeline nécessite une connexion Internet pour s'exécuter.
Le non-déterminisme se produit en raison des versions logicielles dans les dépendances.

Pour éviter ces problèmes, fournissez l'environnement d'exécution dans une image de conteneur Docker personnalisée. L'utilisation d'une image de conteneur Docker personnalisée sur laquelle les dépendances de pipeline sont préinstallées présente les avantages suivants :

Elle s'assure que l'environnement d'exécution du pipeline possède le même ensemble de dépendances chaque fois que vous lancez votre job Dataflow.
Permet de contrôler l'environnement d'exécution de votre pipeline.
Évite la résolution des dépendances potentiellement chronophage au démarrage.

Lorsque vous utilisez des images de conteneurs personnalisées, tenez compte des conseils suivants :

Évitez d'utiliser le tag :latest avec vos images personnalisées. Ajoutez à vos compilations un tag avec une date, une version ou un identifiant unique. Cette étape vous permet de revenir à une configuration opérationnelle connue si nécessaire.
Utilisez un environnement de lancement compatible avec votre image de conteneur. Pour plus de conseils sur l'utilisation des conteneurs personnalisés, consultez la section Créer une image de conteneur.

Pour en savoir plus sur la préinstallation des dépendances Python, consultez la section Préinstaller des dépendances Python.

Contrôler l'environnement de lancement avec des modèles Dataflow

Si votre pipeline nécessite des dépendances supplémentaires, vous devrez peut-être les installer à la fois dans l'environnement d'exécution et dans l'environnement de lancement. L'environnement de lancement exécute la version de production du pipeline. L'environnement de lancement doit être compatible avec l'environnement d'exécution. Vous devez donc utiliser les mêmes versions de dépendances dans les deux environnements.

Pour disposer d'un environnement de lancement conteneurisé et reproductible, utilisez des modèles Flex Dataflow. Pour en savoir plus, consultez la page Créer et exécuter un modèle Flex. Lorsque vous utilisez des modèles Flex, tenez compte des facteurs suivants :

Si vous configurez le pipeline en tant que package, installez-le dans le fichier Dockerfile de votre modèle. Pour configurer le modèle Flex, spécifiez FLEX_TEMPLATE_PYTHON_SETUP_FILE. Pour en savoir plus, consultez la section Définir les variables d'environnement requises dans le fichier Dockerfile.
Si vous utilisez une image de conteneur personnalisée avec votre pipeline, fournissez-la lorsque vous lancez votre modèle. Pour en savoir plus, consultez la page Utiliser un conteneur personnalisé pour les dépendances.
Pour créer votre image Docker de modèle Flex Dataflow, utilisez la même image de conteneur personnalisée que l'image de base. Pour en savoir plus, consultez la section Utiliser des images de conteneurs personnalisées.

Cette construction rend votre environnement de lancement à la fois reproductible et compatible avec votre environnement d'exécution.

Pour obtenir un exemple illustrant cette approche, consultez le tutoriel Modèle Flex pour un pipeline avec des dépendances et un conteneur personnalisé dans GitHub.

Pour en savoir plus, consultez les sections Rendre l'environnement de lancement compatible avec l'environnement d'exécution et Contrôler les dépendances utilisées par le pipeline dans la documentation Apache Beam.

Go

Lorsque vous exécutez des jobs Dataflow à l'aide du SDK Apache Beam pour Go, les modules Go permettent de gérer les dépendances. Le fichier suivant contient les dépendances de compilation et d'exécution par défaut utilisées par votre pipeline :

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

Remplacez VERSION_NUMBER par la version de SDK que vous utilisez.

Pour plus d'informations sur la gestion des dépendances de votre pipeline Go, consultez la page Gérer les dépendances dans la documentation Go.