Installer des dépendances Python

Cloud Composer 1 | Cloud Composer 2

Cette page explique comment installer des packages Python dans votre environnement.

À propos des packages PyPI préinstallés et personnalisés

Les packages PyPI préinstallés sont des packages inclus dans l'image Cloud Composer de votre environnement. Chaque image Cloud Composer contient des packages PyPI spécifiques à votre version de Cloud Composer et Airflow.

Les packages PyPI personnalisés sont des packages que vous pouvez installer dans votre environnement en plus des packages préinstallés.

Options de gestion des packages Python

Option À utiliser si
Installer à partir de PyPI Le package ne comporte pas de dépendances externes et n'entre pas en conflit avec les dépendances Cloud Composer.
Effectuer l'installation à partir d'un dépôt privé Le package est hébergé dans un dépôt de packages privé disponible sur Internet.
Installer une bibliothèque en tant que bibliothèque Python locale Le package ne se trouve pas dans l'index de packages Python, et la bibliothèque ne comporte aucune dépendance externe, telle que dist-packages.
Installer un plug-in Ce package fournit des fonctionnalités spécifiques au plug-in, telles que la modification de l'interface Web Airflow.
PythonVirtualenvOperator Vous ne souhaitez pas que le package soit installé pour tous les nœuds de calcul, ou que la dépendance soit en conflit avec les packages préinstallés. Ce package se trouve dans l'index de packages Python et ne comporte aucune dépendance externe.
KubernetesPodOperator Vous devez disposer de dépendances externes qui ne peuvent pas être installées à partir de pip, telles que dist-packages, ou sur un serveur pip interne. Cette option nécessite davantage de configuration et de maintenance et ne doit généralement être envisagée que si les autres options ne fonctionnent pas.

Avant de commencer

  • Vous devez disposer d'un rôle permettant de déclencher des opérations de mise à jour d'environnement. De plus, le compte de service de l'environnement doit disposer d'un rôle doté d'autorisations suffisantes pour effectuer des opérations de mise à jour. Pour plus d'informations, consultez la section Contrôle des accès.
  • Si votre environnement est protégé par un périmètre VPC Service Controls, vous devez accorder des identités utilisateur supplémentaires aux services que le périmètre protège et activer la compatibilité avec un dépôt PyPI privé avant d'installer des dépendances PyPI.
  • Les exigences doivent respecter le format spécifié dans PEP-508, où chaque exigence est spécifiée en minuscules et consiste en un nom de package avec des options et des spécificateurs de version facultatifs.
  • Les mises à jour des dépendances PyPI génèrent des images Docker dans Artifact Registry. Veuillez ne pas modifier, ni supprimer les images.
  • Si un conflit de dépendance entraîne l'échec de la mise à jour, votre environnement continue de s'exécuter avec ses dépendances existantes. Si l'opération réussit, vous pouvez commencer à utiliser les dépendances Python récemment installées dans vos DAG.

Afficher la liste des packages

Vous pouvez obtenir la liste des packages pour votre environnement dans différents formats.

Packages préinstallés

Pour afficher la liste des packages préinstallés pour votre environnement, consultez la liste des packages pour l'image Cloud Composer de votre environnement.

Tous les packages

Pour afficher tous les packages (préinstallés et personnalisés) dans votre environnement, procédez comme suit:

gcloud

La commande CLI gcloud suivante renvoie le résultat de la commande python -m pip list pour un nœud de calcul Airflow dans votre environnement.

Vous pouvez également utiliser l'argument --tree pour obtenir le résultat de la commande python -m pipdeptree --warn.

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.

Packages PyPI personnalisés

Console

  1. Dans Google Cloud Console, accédez à la page Environnements.

    Accéder à la page Environnements

  2. Dans la liste des environnements, cliquez sur le nom de votre environnement. La page Environment details (Détails sur l'environnement) s'ouvre.

  3. Accédez à l'onglet Packages PYPI.

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.

Installer un package à partir de PyPI

Un package peut être installé à partir de l'index de packages Python s'il n'a pas de dépendances externes ni de conflits avec des packages préinstallés.

Pour ajouter, mettre à jour ou supprimer les dépendances Python sur l'environnement, procédez comme suit :

Console

  1. Dans Google Cloud Console, accédez à la page Environnements.

    Accéder à la page Environnements

  2. Dans la liste des environnements, cliquez sur le nom de votre environnement. La page Environment details (Détails sur l'environnement) s'ouvre.

  3. Accédez à l'onglet Configuration de l'environnement.

  4. Cliquez sur Modifier.

  5. Dans la section Packages PyPI, spécifiez des noms de package, avec des spécificateurs de version facultatifs et des options supplémentaires.

    Exemple :

    • scikit-learn
    • scipy, >=0.13.3
    • nltk, [machine_learning]

gcloud

La CLI gcloud propose plusieurs mécanismes pour utiliser des packages PyPI personnalisés:

  • --update-pypi-packages-from-file remplace tous les packages PyPI personnalisés existants par les packages spécifiés. Les packages que vous ne spécifiez pas sont supprimés.
  • --update-pypi-package installe ou met à jour un package.
  • --remove-pypi-packages supprime les packages spécifiés.
  • --clear-pypi-packages supprime tous les packages.

Installer les conditions requises à partir d'un fichier

Le fichier requirements.txt doit comporter chaque spécificateur d'exigence sur une ligne distincte.

Exemple :

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Mettez à jour votre environnement et spécifiez le fichier requirements.txt dans l'argument --update-pypi-packages-from-file:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.

Installer un package

Mettez à jour votre environnement, puis spécifiez le package, la version et les options supplémentaires dans l'argument --update-pypi-package:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.
  • PACKAGE_NAME par le nom du package.
  • EXTRAS_AND_VERSION avec la version facultative et le spécificateur supplémentaire Pour ignorer les versions et les bonus, spécifiez une valeur vide.

Exemple :

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package scipy>=0.13.3

Supprimer des packages

Mettez à jour votre environnement et spécifiez les packages que vous souhaitez supprimer dans l'argument --remove-pypi-packages:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.
  • PACKAGE_NAMES avec une liste de packages séparés par une virgule.

Exemple :

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

Rédigez une requête API environments.patch.

Dans cette requête :

  1. Dans le paramètre updateMask, spécifiez le masque:

    • Utilisez le masque config.softwareConfig.pypiPackages pour remplacer tous les packages existants par les packages spécifiés. Les packages que vous ne spécifiez pas sont supprimés.
    • Utilisez config.softwareConfig.envVariables.PACKAGE_NAME pour ajouter ou mettre à jour un package spécifique. Pour ajouter ou mettre à jour plusieurs packages, spécifiez plusieurs masques avec des virgules.
  2. Dans le corps de la requête, spécifiez les packages et les valeurs pour les versions et les options supplémentaires:

    {
      "config": {
        "softwareConfig": {
          "pypiPackages": {
            "PACKAGE_NAME": "EXTRAS_AND_VERSION"
          }
        }
      }
    }
    

    Remplacez :

    • PACKAGE_NAME par le nom du package.
    • EXTRAS_AND_VERSION avec la version facultative et le spécificateur supplémentaire Pour ignorer les versions et les bonus, spécifiez une valeur vide.
    • Pour ajouter plusieurs packages, ajoutez des entrées supplémentaires pour les packages dans pypiPackages.

Exemple :

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

Le bloc env_variables du bloc software_config spécifie les variables d'environnement.

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      env_variables = {
        VAR_NAME = "VAR_VALUE"
      }

    }
  }
}

Remplacez :

  • ENVIRONMENT_NAME par le nom de l'environnement.
  • LOCATION par la région où se trouve l'environnement.
  • VAR_NAME par le nom de la variable d'environnement.
  • VAR_VALUE par la valeur de la variable d'environnement ;
  • Pour ajouter plusieurs variables, ajoutez des entrées pour les variables dans env_variables.

Exemple :

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {

      env_variables = {
        EXAMPLE_VARIABLE = "True"
        ANOTHER_VARIABLE = "test"
      }

  }
}

Installer depuis un dépôt privé

Vous pouvez installer des packages hébergés dans des dépôts de packages disponibles sur l'Internet public.

Les packages doivent être correctement configurés pour que l'outil pip par défaut puisse l'installer.

Pour effectuer l'installation à partir d'un dépôt de packages privé disposant d'une adresse publique:

  1. Créez un fichier pip.conf et incluez-y les informations suivantes, le cas échéant:

    • URL du dépôt
    • Identifiants d'accès au dépôt
    • Options d'installation pip non définies par défaut

    Exemple :

    [global]
    extra-index-url=https://example.com/
    
  2. Importez ce fichier pip.conf dans le dossier /config/pip/ de votre bucket d'environnement. Par exemple, gs://us-central1-example-bucket/config/pip/pip.conf.

Installer dans un environnement IP privé

Un environnement d'adresse IP privée restreint l'accès à l'Internet public. Par conséquent, l'installation de dépendances Python peut nécessiter des étapes supplémentaires.

Lors de l'installation des dépendances à partir d'un dépôt PyPI, aucune configuration spéciale n'est requise. Suivez la procédure décrite dans Installer un package à partir de PyPI. Vous pouvez également demander des packages depuis un dépôt privé avec une adresse publique.

Vous pouvez également héberger un dépôt PyPI privé dans le réseau de votre projet. Lors de l'installation des dépendances, Cloud Composer exécute l'opération dans le cluster qui héberge votre environnement, sans accéder à aucune adresse IP publique via Cloud Build.

Pour installer des packages à partir d'un dépôt privé hébergé dans le réseau de votre projet, procédez comme suit:

  1. Le compte de service de votre environnement Cloud Composer doit disposer du rôle iam.serviceAccountUser.

  2. Créez un fichier pip.conf et incluez-y les informations suivantes, le cas échéant:

    • Adresse IP du dépôt dans le réseau de votre projet
    • Identifiants d'accès au dépôt
    • Options d'installation pip non définies par défaut

    Exemple :

    [global]
    extra-index-url=https://192.0.2.10/
    
  3. Importez ce fichier pip.conf dans le dossier /config/pip/ du bucket de votre environnement. Par exemple, gs://us-central1-example-bucket/config/pip/pip.conf.

Installer dans un environnement d'adresse IP privée soumis à des restrictions d'emplacement des ressources

Garder votre projet en conformité avec les exigences de restriction d'emplacement des ressources qui interdisent l'utilisation de certains outils. Cloud Build ne peut pas être utilisé pour l'installation de packages, ce qui empêche l'accès direct aux dépôts sur l'Internet public.

Pour installer des dépendances Python dans un tel environnement, suivez les instructions relatives aux environnements IP privés avec un périmètre VPC Service Controls.

Installer une dépendance Python dans un environnement d'adresse IP privée dans un périmètre VPC Service Controls

La protection de votre projet avec un périmètre VPC Service Controls entraîne d'autres restrictions de sécurité. Cloud Build ne peut pas être utilisé pour l'installation de packages, ce qui empêche l'accès direct aux dépôts sur l'Internet public.

Pour installer des dépendances Python pour un environnement d'adresses IP privées dans un périmètre, vous pouvez:

  • Utilisez un dépôt PyPI privé hébergé dans votre réseau VPC.
  • Utilisez une VM de serveur proxy dans votre réseau VPC pour vous connecter à un dépôt PyPI sur le réseau Internet public. Spécifiez l'adresse du proxy dans le fichier /config/pip/pip.conf du bucket de votre environnement.
  • Si votre stratégie de sécurité autorise l'accès à votre réseau VPC à partir d'adresses IP externes, vous pouvez l'activer en configurant Cloud NAT.
  • Placez les dépendances Python dans le dossier dags du bucket Cloud Storage pour les installer en tant que bibliothèques locales. Cette option ne convient pas s'il est très volumineux.

Installer une bibliothèque Python locale

Pour installer une bibliothèque Python interne ou locale, procédez comme suit :

  1. Placez les dépendances dans un sous-répertoire du dossier dags/ de votre bucket d'environnement. Pour importer un module à partir d'un sous-répertoire, chaque sous-répertoire du chemin d'accès du module doit contenir un fichier de repère de package __init__.py.

    Dans l'exemple suivant, la dépendance est coin_module.py :

    dags/
      use_local_deps.py  # A DAG file.
      dependencies/
        __init__.py
        coin_module.py
    
  2. Importez la dépendance à partir du fichier de définition du DAG.

    Exemple :

from dependencies import coin_module

Utiliser des packages qui dépendent de bibliothèques d'objets partagés

Certains packages PyPI dépendent de bibliothèques système. Bien que Cloud Composer ne soit pas compatible avec les bibliothèques système, vous pouvez utiliser les options suivantes :

  • Utiliser KubernetesPodOperator. Définissez l'image de l'opérateur sur une image de compilation personnalisée. Si vous rencontrez des échecs pendant l'installation des packages en raison d'une dépendance système non satisfaite, utilisez cette option.

  • Importez les bibliothèques d'objets partagées dans le bucket de votre environnement. Si vos packages PyPI sont correctement installés, mais qu'ils échouent lors de l'exécution, utilisez cette option.

    1. Recherchez manuellement les bibliothèques d'objets partagées pour la dépendance PyPI (un fichier .so).
    2. Importez les bibliothèques d'objets partagées dans le dossier /plugins du bucket de votre environnement.
    3. Définissez la variable d'environnement suivante : LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Étapes suivantes