Créer une application Python

Les buildpacks sont compatibles avec la configuration idiomatique du langage via des variables d'environnement.

Spécifier la version de Python

Par défaut, le buildpack d'exécution Python utilise la dernière version stable de l'interpréteur Python. Si votre application nécessite une version spécifique, vous pouvez en spécifier une en incluant un fichier .python-version dans le répertoire racine de l'application.

3.13

Utiliser GOOGLE_PYTHON_VERSION

Il est également possible de spécifier la version de Python via la variable d'environnement GOOGLE_PYTHON_VERSION. Si les deux options sont spécifiées, la valeur de GOOGLE_PYTHON_VERSION est prioritaire sur le fichier .python-version. Par défaut, si aucune des options n'est spécifiée (ni le fichier .python-version, ni la variable d'environnement GOOGLE_PYTHON_VERSION), la dernière version LTS de Python est utilisée.

Pour configurer le buildpack afin d'utiliser Python 3.13 lors du déploiement de votre application, procédez comme suit :

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.13.x"

Vous pouvez également utiliser un descripteur de projet project.toml pour encoder la variable d'environnement avec vos fichiers de projet. Consultez les instructions décrivant la compilation de l'application avec des variables d'environnement.

Spécifier des dépendances avec pip

Le buildpack Python est compatible avec la gestion des dépendances d'application à l'aide de pip. Les dépendances de votre application doivent être déclarées dans un fichier requirements.txt placé dans le répertoire racine.

Le fichier requirements.txt contient une ligne par package. Chaque ligne contient le nom du package et, éventuellement, la version demandée. Pour en savoir plus, consultez la documentation de référence sur requirements.txt.

Voici un exemple de fichier requirements.txt :

requests==2.20.0
numpy

Configurer pip

Il est possible de configurer le comportement de pip à l'aide de variables d'environnement :

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Dépendances privées d'Artifact Registry

Un dépôt Python Artifact Registry peut héberger des dépendances privées pour votre fonction Python. Lors de la compilation d'une application sur Cloud Build, le buildpack Python génère automatiquement des identifiants Artifact Registry pour le compte de service Cloud Build. Il vous suffit d'inclure l'URL Artifact Registry dans votre fichier requirements.txt sans générer d'identifiants supplémentaires. Par exemple :

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Point d'entrée de l'application

La section suivante décrit le point d'entrée par défaut pour le buildpack Python.

Point d'entrée pour les déploiements de sources Cloud Run

Cette fonctionnalité n'est disponible que si vous déployez votre code source sur Cloud Run avec le runtime Python. Cette fonctionnalité ne s'applique pas si vous créez votre image de conteneur directement à l'aide de pack build en dehors du processus de déploiement de la source Cloud Run.

Le buildpack Python est compatible avec les frameworks Web modernes tels que FastAPI, Gradio et Streamlit.

Python 3.12 et versions antérieures

Si vous utilisez Python 3.12 ou une version antérieure, le buildpack Python utilise par défaut Gunicorn comme serveur HTTP WSGI pour votre charge de travail. Le buildpack Python définit le point d'entrée par défaut sur gunicorn -b :8080 main:app.

Python 3.13 et versions ultérieures

Pour Python 3.13 et les versions ultérieures, le buildpack Python définit le point d'entrée par défaut pour les déploiements de sources Cloud Run en fonction de la configuration du serveur Web ou du framework dans votre fichier requirements.txt. Ce paramètre par défaut ne s'applique qu'aux déploiements de sources de services Cloud Run, et non aux fonctions Cloud Run.

Lorsque vous déployez un service Cloud Run à partir de la source à l'aide de l'environnement d'exécution Python, le buildpack détermine la version Python et le point d'entrée par défaut de la manière suivante :

• Si vous ne spécifiez pas de version de Python dans vos fichiers sources, le buildpack Python définit la version par défaut sur la dernière version de Python compatible. Le buildpack détermine le point d'entrée par défaut en fonction du serveur Web ou du framework que vous avez configuré dans votre fichier requirements.txt.

• Si vous ne spécifiez pas de serveur Web ni de framework dans votre fichier requirements.txt, le buildpack Python utilise par défaut Gunicorn comme serveur HTTP WSGI pour votre charge de travail. Le buildpack Python définit le point d'entrée par défaut sur gunicorn -b :8080 main:app.

• Le buildpack Python définit le point d'entrée par défaut en fonction de l'ordre de priorité suivant, tel que défini dans le fichier requirements.txt :

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit

Configurer le serveur Web ou le framework

Pour chaque configuration Python courante du fichier requirements.txt, le tableau suivant indique les points d'entrée par défaut lors du déploiement sur Cloud Run à partir de la source :

Configuration principale	Point d'entrée par défaut	Variables d'environnement
gunicorn	gunicorn -b :8080 main:app
numpy	gunicorn -b :8080 main:app
fastapi uvicorn	uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard]	uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn gunicorn	gunicorn -b :8080 main:app
gradio	python main.py	GRADIO_SERVER_NAME=0.0.0.0 GRADIO_SERVER_PORT=8080
streamlit	streamlit run main.py --server.address 0.0.0.0 --server.port 8080

Pour éviter les échecs de déploiement, utilisez une version Python compatible dans vos fichiers sources et spécifiez un serveur Web dans votre fichier requirements.txt.

Vous pouvez également spécifier le point d'entrée en exécutant la commande de déploiement de la source suivante :

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

Remplacez les éléments suivants :

• SERVICE : nom du service sur lequel vous souhaitez déployer.
• ENTRYPOINT : point d'entrée par défaut que vous souhaitez utiliser pour votre code source.

Si vous ne parvenez pas à déployer votre code source sur Cloud Run ou si vous trouvez des erreurs dans les journaux, consultez le guide de dépannage Cloud Run.

Point d'entrée pour tous les autres déploiements

Le buildpack Python utilise Gunicorn comme serveur HTTP WSGI par défaut pour votre charge de travail. Les applications créées avec le buildpack Python lancent le processus gunicorn avec des paramètres par défaut, semblables à ceux de l'exécution :

gunicorn --bind :8080 main:app

Personnaliser le point d'entrée de l'application

Vous pouvez personnaliser la commande de démarrage des applications à l'aide d'un Procfile ou d'une variable d'environnement. Vous devrez peut-être le faire pour personnaliser les configurations du point d'entrée par défaut.

Vous pouvez créer un fichier Procfile avec vos paramètres personnalisés dans le répertoire racine. Exemple :

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Important : Lorsque vous remplacez les valeurs par défaut de Gunicorn, vous devez inclure gunicorn en tant que dépendance du package dans le fichier requirements.txt de votre projet.

Vous pouvez également utiliser la variable d'environnement GOOGLE_ENTRYPOINT avec la commande pack. Exemple :

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

Variables d'environnement

Le buildpack Python est compatible avec les variables d'environnement suivantes, afin de personnaliser votre conteneur :

PIP_<key>

Consultez la documentation sur pip.

Exemple : PIP_DEFAULT_TIMEOUT=60 permet de définir le paramètre --default-timeout=60 pour les commandes pip.