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 ce 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 ne sont pas suffisantes 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 associer des versions de bibliothèque spécifiques à votre pipeline.
Vous disposez d'un pipeline Python qui doit s'exécuter avec un ensemble cohérent de dépendances.

La façon dont vous gérez les dépendances dépend de l'utilisation de Java, Python ou Go par votre pipeline.

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 qui utilisent 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. La nomenclature aide les outils de gestion des dépendances à sélectionner des combinaisons de dépendances compatibles. Pour en savoir plus, consultez la section SDK Apache Beam pour les dépendances Java dans la documentation Apache Beam.

Pour utiliser une nomenclature avec votre pipeline et ajouter explicitement d'autres dépendances à la liste des dépendances, ajoutez les informations suivantes au fichier pom.xml pour l'artefact SDK. Pour importer la nomenclature 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 de l'index de packages Python (PyPI) et vous souhaitez les rendre disponibles à distance.
Vous souhaitez créer un environnement reproductible.
Pour réduire le temps de démarrage, vous devez é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 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 le code de votre pipeline s'étend sur plusieurs fichiers, regroupez les fichiers du pipeline en tant que package Python.

Définissez les dépendances du pipeline dans le fichier setup.py de votre package.
Entreposez 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 juliaset sur le dépôt GitHub 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 de votre pipeline. L'exemple suivant montre 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 au répertoire racine de votre projet. Ce regroupement de fichiers est le 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 d'envoi. Utilisez l'option de pipeline --setup_file pour entreposer le package sur les 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 le code augmente en taille et en complexité. Pour découvrir d'autres méthodes permettant 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 du pipeline. Les images de conteneurs Docker fournissent l'environnement approprié pour exécuter le code de votre pipeline.

Les images de conteneurs de stockage sont publiées avec chaque version du SDK Apache Beam. Elles incluent les dépendances du SDK Apache Beam. Pour en savoir plus, consultez la section 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 est dû aux 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.
Vous permet de contrôler l'environnement d'exécution de votre pipeline.
Évite la résolution des dépendances, qui peut être 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 fonctionnelle connue si nécessaire.
Utilisez un environnement de lancement compatible avec votre image de conteneur. Pour obtenir des conseils sur l'utilisation de conteneurs personnalisés, consultez Créer une image de conteneur.

Pour en savoir plus sur l'installation préalable 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. Étant donné que l'environnement de lancement doit être compatible avec l'environnement d'exécution, utilisez les mêmes versions de dépendances dans les deux environnements.

Pour disposer d'un environnement de lancement reproductible et conteneurisé, utilisez les modèles Flex Dataflow. Pour en savoir plus, consultez 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 votre fichier Dockerfile de 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 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 Utiliser des images de conteneurs personnalisées.

Cette construction rend votre environnement de lancement 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 en savoir plus sur la gestion des dépendances de votre pipeline Go, consultez la section Gérer les dépendances de la documentation Go.