Configurer l'environnement Python

Les jobs PySpark sur Managed Service pour Apache Spark sont exécutés par un interpréteur Python sur le cluster. Le code du job doit être compatible au moment de l'exécution avec la version de l'interpréteur Python et les dépendances.

Vérifier la version et les modules de l'interpréteur

L'exemple de programme check_python_env.py suivant vérifie l'utilisateur Linux qui exécute la tâche, l'interpréteur Python et les modules disponibles.

import getpass
import importlib.util
import sys

print(f'This job is running as "{getpass.getuser()}".')
print(sys.executable, sys.version_info)
for package in sys.argv[1:]:
  print(importlib.util.find_spec(package))

Exécutez le programme :

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    -- pandas scipy

Exemple de résultat : 

This job is running as "root".
/opt/conda/default/bin/python sys.version_info(major=3, minor=11, micro=8, releaselevel='final', serial=0)
ModuleSpec(name='pandas', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3d90>, origin='/opt/conda/default/lib/python3.11/site-packages/pandas/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/pandas'])
ModuleSpec(name='scipy', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3e50>, origin='/opt/conda/default/lib/python3.11/site-packages/scipy/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/scipy'])

Environnements Python des images Managed Service pour Apache Spark

Les sections suivantes décrivent les environnements Python pour les clusters compatibles avec les versions d'image Managed Service pour Apache Spark.

Version 2.x de l'image Managed Service pour Apache Spark

Conda (ou micromamba dans les images 2.3) est installé sur les clusters Managed Service pour Apache Spark 2.x. L'interpréteur Python 3 par défaut se trouve sur l'instance de VM sous /opt/conda/default/bin. Les pages suivantes listent la version de Python incluse dans les versions d'image 2.x Managed Service pour Apache Spark compatibles :

L'interpréteur Python non défini par défaut dans l'OS est disponible sous /usr/bin/.

Vous pouvez installer des packages conda et pip dans l'environnement base ou configurer votre propre environnement conda sur le cluster à l'aide des propriétés de cluster liées à Conda.

Remarque sur le canal Conda : Les versions d'image par défaut de Managed Service pour Apache Spark 2.1, 2.2 et 2.3 n'incluent pas les canaux de packages Conda préconfigurés (tels que defaults ou conda-forge) dans .condarc (voir les notes de version du 4 septembre 2026). La transmission de noms de packages sans préfixe à dataproc:conda.packages ou l'exécution de conda install PACKAGE sans spécifier de canal échoue avec CondaValueError: No channels available to install from ou PackagesNotFoundError.

Pour installer des packages Conda, vous devez spécifier explicitement le canal :

  • Lorsque vous utilisez la propriété dataproc:conda.packages, utilisez le format CHANNEL::PACKAGE==VERSION (par exemple, dataproc:conda.packages=conda-forge::pip==24.0).
  • Lorsque vous exécutez conda install sur la ligne de commande, transmettez l'indicateur -c (ou --channel) (par exemple, conda install PACKAGES -c conda-forge).

Exemple :

REGION=region
gcloud dataproc clusters create my-cluster \
    --image-version=2.3 \
    --region=${REGION} \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1'

Version 3.0 de l'image Managed Service pour Apache Spark

Python 3 est installé sur les clusters Managed Service pour Apache Spark 3.0. Dans les images 3.0, Pixi est installé dans le cadre de l'installation de Python et est utilisé pour installer les packages Python au lieu de Conda.

Éviter les problèmes de téléchargement de packages

Les nœuds de cluster Managed Service pour Apache Spark téléchargent des packages à partir de dépôts Python publics externes lors de l'installation de packages conda et pip personnalisés (voir Propriétés de cluster liées à conda). Pour éviter les échecs de création de clusters dus à l'indisponibilité des dépôts Python publics, envisagez de créer une image personnalisée Managed Service pour Apache Spark ou d'importer les dépendances dans un bucket Cloud Storage (voir Télécharger les dépendances avec des clusters à adresse IP interne uniquement).

Choisir un interpréteur Python pour un job

Si plusieurs interpréteurs Python sont installés sur votre cluster, le système exécute /etc/profile.d/effective-python.sh, qui exporte la variable d'environnement PYSPARK_PYTHON afin de choisir l'interpréteur Python par défaut pour vos tâches PySpark. Si vous avez besoin d'un interpréteur Python autre que celui par défaut pour une tâche PySpark, définissez les propriétés spark.pyspark.python et spark.pyspark.driver.python sur le chemin ou la version Python requis (par exemple, "/usr/bin/python3" ou "python3.11").

Exemple :

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    --properties="spark.pyspark.python=/usr/bin/python3,spark.pyspark.driver.python=/usr/bin/python3"

Python avec sudo

Si vous vous connectez à un nœud de cluster à l'aide de SSH, lorsque vous exécutez sudo python --version, la version Python affichée peut différer de celle affichée par python --version. Cette différence de version peut se produire parce que sudo utilise le système Python par défaut /usr/bin/python, mais n'exécute pas /etc/profile.d/effective-python.sh pour initialiser l'environnement Python. Pour bénéficier d'une expérience cohérente lors de l'utilisation de sudo, recherchez le chemin d'accès Python défini dans /etc/profile.d/effective-python.sh, puis exécutez la commande env pour définir PATH sur ce chemin d'accès Python. Exemple :

sudo env PATH=/opt/conda/default/bin:${PATH} python --version

Utiliser les propriétés de cluster liées à Conda

Vous pouvez personnaliser l'environnement conda lors de la création du cluster à l'aide des propriétés de cluster liées à Conda.

Lorsque vous créez un cluster Managed Service pour Apache Spark, deux méthodes mutuellement exclusives permettent de personnaliser l'environnement conda :

  1. Utilisez la propriété de cluster dataproc:conda.env.config.uri pour créer et activer un nouvel environnement conda sur le cluster. Ou

  2. Utilisez les propriétés de cluster dataproc:conda.packages et dataproc:pip.packages pour ajouter respectivement les packages conda et pip à l'environnement conda base sur le cluster.

Propriétés de cluster liées à Conda

  • dataproc:conda.env.config.uri : chemin absolu vers un fichier de configuration YAML d'environnement conda situé dans Cloud Storage. Ce fichier permet de créer et d'activer un nouvel environnement conda sur le cluster. Étant donné que les images par défaut n'incluent pas de canaux Conda préconfigurés, assurez-vous que votre fichier environment.yaml liste explicitement les canaux de packages requis (tels que conda-forge) sous channels.

    Exemple :

    1. Obtenez ou créez un fichier de configuration conda environment.yaml. Vous pouvez créer manuellement le fichier, utiliser un fichier existant ou exporter un environnement conda existant dans un fichier environment.yaml à l'aide de la commande suivante : 

      conda env export --name=env-name > environment.yaml

    2. Copiez le fichier de configuration dans votre bucket Cloud Storage. 

      gcloud storage cp environment.yaml gs://bucket-name/environment.yaml

    3. Créez le cluster et pointez vers le fichier de configuration de votre environnement dans Cloud Storage. 

      REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='dataproc:conda.env.config.uri=gs://bucket-name/environment.yaml' \
    ... other flags ...

  • dataproc:conda.packages : liste de packages conda avec des canaux et des versions spécifiques à installer dans l'environnement de base, au format CHANNEL::PACKAGE==VERSION (par exemple, conda-forge::pkg1==v1,conda-forge::pkg2==v2...). Si conda ne parvient pas à résoudre les conflits avec les packages existants dans l'environnement de base, les packages en conflit ne sont pas installés.

    Remarques :

    • Étant donné que les versions d'image par défaut 2.1, 2.2 et 2.3 de Managed Service pour Apache Spark n'incluent pas de canaux Conda préconfigurés dans .condarc, vous devez préfixer chaque nom de package avec son canal (par exemple, conda-forge::). Si vous transmettez des noms de package sans préfixe, l'opération échoue avec CondaValueError: No channels available to install from ou PackagesNotFoundError.

    • Les propriétés de cluster dataproc:conda.packages et dataproc:pip.packages ne peuvent pas être utilisées avec la propriété de cluster dataproc:conda.env.config.uri.

    • Lorsque vous spécifiez plusieurs packages (séparés par une virgule), vous devez spécifier un autre caractère de délimitation (voir Mise en forme des propriétés du cluster). L'exemple suivant spécifie "#" comme caractère de délimitation pour transmettre plusieurs noms de packages séparés par une virgule à la propriété dataproc:conda.packages.

    Exemple :

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:conda.packages=conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0' \
    ... other flags ...

  • dataproc:pip.packages : liste de packages pip avec des versions spécifiques à installer dans l'environnement de base, au format pkg1==v1,pkg2==v2.... pip met à niveau les dépendances existantes uniquement si nécessaire. Les conflits peuvent entraîner une incohérence au sein de l'environnement.

    Remarques :

    • Les propriétés de cluster dataproc:pip.packages et dataproc:conda.packages ne peuvent pas être utilisées avec la propriété de cluster dataproc:conda.env.config.uri.

    • Lorsque vous spécifiez plusieurs packages (séparés par une virgule), vous devez spécifier un autre caractère de délimitation (voir Mise en forme des propriétés du cluster). L'exemple suivant spécifie "#" comme caractère de délimitation pour transmettre plusieurs noms de package séparés par une virgule à la propriété dataproc:pip.packages.

    Exemple :

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:pip.packages=tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...

  • Vous pouvez utiliser à la fois dataproc:conda.packages et dataproc:pip.packages lorsque vous créez un cluster.

    Exemple :

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --image-version=2.3 \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...