Hello Cloud Run avec Python (FastAPI)

1. Introduction

Cloud Run est une plate-forme de calcul gérée qui permet d'exécuter des conteneurs sans état pouvant être appelés à l'aide de requêtes HTTP. Il est basé sur le projet Open Source Knative, ce qui permet la portabilité de vos charges de travail entre de nombreuses plates-formes. Cloud Run fonctionne sans serveur. Il élimine toute gestion de l'infrastructure pour vous permettre de vous concentrer sur ce qui compte le plus : créer des applications de qualité.

L'objectif de ce tutoriel est de créer une application Web FastAPI simple et de la déployer sur Cloud Run.

Points abordés

• Créer une application "Hello World" FastAPI
• Tester l'application en exécutant le serveur FastAPI en mode dev.
• Buildpacks Cloud et comment la présence de fastapi et uvicorn dans un requirements.txt permet de se passer de Dockerfile.
• Déployer l'application FastAPI sur Cloud Run

2. Préparation

Configuration de l'environnement au rythme de chacun

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.

• Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
• Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention : Un ID de projet est unique. Une fois que vous l'avez choisi, personne d'autre ne peut l'employer. Vous en êtes le seul utilisateur. Même si un projet est supprimé, son ID ne peut pas être réutilisé.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300$.

Démarrer Cloud Shell

Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Cloud Shell pour ce tutoriel, un environnement de ligne de commande exécuté dans le cloud.

Activer Cloud Shell

1. Dans la console Cloud, cliquez sur Activer Cloud Shell.

Si vous démarrez Cloud Shell pour la première fois, un écran intermédiaire s'affiche pour vous le présenter. Si tel est le cas, cliquez sur Continuer.

Le provisionnement et la connexion à Cloud Shell ne devraient pas prendre plus de quelques minutes.

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez réaliser une grande partie, voire la totalité, des activités de cet atelier de programmation dans un navigateur.

Une fois connecté à Cloud Shell, vous êtes en principe authentifié, et le projet est défini avec votre ID de projet.

2. Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :

gcloud auth list

Résultat de la commande

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Remarque : gcloud est l'outil de ligne de commande performant et unifié de Google Cloud. Il est préinstallé dans Cloud Shell. Il est également compatible avec la saisie semi-automatique via la touche de tabulation. Vous serez peut-être invité à vous authentifier la première fois que vous exécuterez une commande. Pour en savoir plus, consultez la présentation de l'outil de ligne de commande gcloud.

3. Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet :

gcloud config list project

Résultat de la commande

[core]
project = <PROJECT_ID>

Si vous obtenez un résultat différent, exécutez cette commande :

gcloud config set project <PROJECT_ID>

Résultat de la commande

Updated property [core/project].

Remarque : Si vous suivez ce tutoriel en dehors de Cloud Shell, suivez la section Configurer les identifiants par défaut de l'application.

3. Activer les API

Dans Cloud Shell, activez les API Artifact Registry, Cloud Build et Cloud Run :

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com

Un message de confirmation semblable à celui-ci s'affiche :

Operation "operations/..." finished successfully.

En arrière-plan, pour déployer votre application, Cloud Run s'associe à l'écosystème de conteneurs :

• Cloud Build crée automatiquement une image de conteneur à partir de votre code source et la transfère vers Artifact Registry.
• Artifact Registry gère votre image de conteneur.

Vous êtes maintenant prêt à commencer à travailler et à écrire votre application…

4. Écrire l'application

Dans cette étape, vous allez créer une application Python FastAPI "Hello World" qui répond aux requêtes HTTP.

Répertoire de travail

Utilisez Cloud Shell pour créer un répertoire de travail nommé helloworld-fastapi et accédez-y :

mkdir ~/helloworld-fastapi && cd ~/helloworld-fastapi

main.py

Créez un fichier nommé main.py :

touch main.py

Modifiez le fichier avec l'éditeur de ligne de commande de votre choix (nano, vim ou emacs) ou en cliquant sur le bouton "Éditeur Cloud Shell" :

Pour modifier directement le fichier avec l'éditeur Cloud Shell, utilisez la commande suivante :

cloudshell edit main.py

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello(name: str = "World"):
    """Return a friendly HTTP greeting."""
    return {
        "message": f"Hello {name}!"
    }

Ce code crée un service Web de base qui répond aux requêtes HTTP GET avec un message convivial.

requirements.txt

Rouvrez le terminal et ajoutez un fichier nommé requirements.txt pour définir les dépendances :

touch requirements.txt

Pour modifier directement le fichier avec l'éditeur Cloud Shell, utilisez la commande suivante :

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/fastapi
fastapi[standard]==0.116.1

# https://pypi.org/project/uvicorn
uvicorn==0.35.0

Vous pouvez utiliser de nombreux autres langages avec Cloud Run. Des instructions pour Go, Node.js, Java, C#, C++, PHP, Ruby, les scripts shell et bien d'autres sont disponibles sur cette page : https://cloud.google.com/run/docs/quickstarts/build-and-deploy

L'application FastAPI est prête à être déployée, mais il est temps de la tester.

5. Tester l'application

Pour tester l'application, utilisez uv (gestionnaire de packages et de projets Python extrêmement rapide), qui est préinstallé dans Cloud Shell.

Pour tester l'application, créez un environnement virtuel :

uv venv

Installez les dépendances :

uv pip install -r requirements.txt

Démarrez l'application en mode dev :

uv run fastapi dev main.py --port=8080

Les journaux indiquent que vous êtes en mode Développement :

FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/user/code/helloworld-fastapi

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with the following code:

          from main import app

     app  Using import string: main:app

  server   Server started at http://127.0.0.1:8080
  server   Documentation at http://127.0.0.1:8080/docs

     tip   Running in development mode, for production use: fastapi run

           Logs:

    INFO   Will watch for changes in these directories: ['/home/user/code/helloworld-fastapi']
    INFO   Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
    INFO   Started reloader process [19627] using WatchFiles
    INFO   Started server process [19629]
    INFO   Waiting for application startup.
    INFO   Application startup complete.

Dans la fenêtre Cloud Shell, cliquez sur l'icône Web Preview, puis sélectionnez Preview on port 8080 :

Une fenêtre de navigateur doit normalement s'ouvrir, avec le message Hello World!.

Vous pouvez également ouvrir une autre session Cloud Shell (un nouvel onglet de terminal) en cliquant sur l'icône + et en envoyant une requête Web à l'application exécutée en local :

curl localhost:8080

Vous devriez obtenir la réponse suivante :

{"message": "Hello World!"}

Lorsque vous avez terminé, revenez à la session Cloud Shell principale et arrêtez le serveur de développement FastAPI avec CTRL+C.

L'application fonctionne comme prévu. Il est temps de la déployer…

6. Déployer dans Cloud Run

Cloud Run est régional, ce qui signifie que l'infrastructure qui exécute vos services Cloud Run est située dans une région spécifique et gérée par Google pour être disponible de manière redondante dans toutes les zones de cette région. Définissez la région que vous utiliserez pour votre déploiement, par exemple :

REGION=europe-west1

Pour obtenir la liste complète des régions compatibles, consultez Emplacements Cloud Run (entièrement géré).

Assurez-vous d'être toujours dans le répertoire de travail :

ls

Les fichiers suivants devraient s'afficher :

main.py  requirements.txt

Avant le déploiement, créez un fichier .gcloudignore contenant .venv/. Cela empêche le déploiement Cloud Run d'inclure l'environnement virtuel créé à partir de uv lors des tests locaux.

Créez le .gcloudignore à l'aide de la commande suivante :

echo ".venv/" > .gcloudignore

Déployez l'application sur Cloud Run :

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated

• L'option --allow-unauthenticated rend le service accessible au public. Pour éviter les requêtes non authentifiées, utilisez plutôt --no-allow-unauthenticated.

Pour vérifier toutes les options, utilisez gcloud run deploy --help.

La première fois, vous serez invité à créer un dépôt Artifact Registry. Appuyez sur Enter pour valider :

Deploying from source requires an Artifact Registry Docker repository to store
built containers. A repository named [cloud-run-source-deploy] in region [REGION]
will be created.

Do you want to continue (Y/n)?

Cela lance l'importation de votre code source dans le dépôt Artifact Registry et la création de votre image de conteneur :

Building using Buildpacks and deploying container ...
* Building and deploying new service... Building Container.           
  OK Creating Container Repository...
  OK Uploading sources...
  * Building Container... Logs are available at ...

Cloud Build utilise des Buildpacks qui détectent automatiquement le langage de votre code source et créent une image de conteneur basée sur la dernière version stable de l'interpréteur Python (Python 3.13 au moment de la rédaction).

Pour utiliser des buildpacks avec un serveur Web ASGI tel que uvicorn, requis par FastAPI, la présence de uvicorn doit être indiquée dans le fichier requirements.txt. Sinon, Buildpacks utilisera par défaut un serveur Web WSGI avec gunicorn, ce qui entraînera des erreurs avec FastAPI.

Pour en savoir plus, consultez Créer une application Python.

Patientez quelques instants jusqu'à la fin du déploiement. En cas de réussite, la ligne de commande affiche l'URL du service :

...
OK Building and deploying new service... Done.
  OK Creating Container Repository...
  OK Uploading sources...
  OK Building Container... Logs are available at ...
  OK Creating Revision... Creating Service.
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [SERVICE]... has been deployed and is serving 100 percent of traffic.
Service URL: https://SERVICE-PROJECTHASH-REGIONID.a.run.app

Vous pouvez obtenir l'URL du service à l'aide de la commande suivante :

SERVICE_URL=$( \
  gcloud run services describe helloworld-fastapi \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Vous devriez obtenir un résultat semblable à celui-ci :

https://helloworld-fastapi-PROJECTHASH-REGIONID.a.run.app

Vous pouvez maintenant utiliser votre application en ouvrant l'URL du service dans un navigateur Web :

Vous pouvez également appeler l'application depuis Cloud Shell :

curl $SERVICE_URL?name=me

Vous devriez obtenir le message d'accueil attendu :

{"message": "Hello me!"}

Bien que ce bref atelier ait été réalisé à l'aide de la ligne de commande gcloud, Cloud Run est également disponible dans la console Cloud ( console.cloud.google.com/run). Vous devriez voir votre service helloworld-fastapi listé :

Vous pouvez également utiliser la console pour déployer des services Cloud Run.

Félicitations ! Vous venez de déployer une application sur Cloud Run. Cloud Run effectue un scaling automatique et horizontal de votre image de conteneur pour traiter les requêtes reçues, puis un scaling à la baisse lorsque la demande diminue. Vous ne payez que pour le processeur, la mémoire et le réseau utilisés lors du traitement des requêtes pour ce service Cloud Run.

7. Effectuer un nettoyage

Bien que Cloud Run ne facture pas lorsque le service n'est pas utilisé, il se peut que des frais vous soient facturés pour le stockage de l'image de conteneur dans Artifact Registry. Vous pouvez supprimer votre dépôt ou votre projet Cloud pour éviter des frais. La suppression de votre projet Cloud arrête la facturation de toutes les ressources utilisées dans ce projet.

Pour supprimer votre dépôt d'images de conteneurs :

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Pour supprimer votre service Cloud Run :

gcloud run services delete helloworld-fastapi \
  --region $REGION

Pour supprimer votre projet Google Cloud,

1. Récupérez l'ID de votre projet actuel :

PROJECT_ID=$(gcloud config get-value core/project)

2. Assurez-vous qu'il s'agit bien du projet que vous souhaitez supprimer :

echo $PROJECT_ID

3. Supprimez le projet :

gcloud projects delete $PROJECT_ID

8. Félicitations !

Vous avez créé une application Web FastAPI "Hello World" et l'avez déployée sur Cloud Run.

Points abordés

• Créer une application "Hello World" FastAPI
• Tester l'application en exécutant le serveur FastAPI en mode dev.
• Buildpacks Cloud et comment la présence de fastapi et uvicorn dans un requirements.txt permet de se passer de Dockerfile.
• Déployer l'application FastAPI sur Cloud Run

En savoir plus

• Consultez la documentation Cloud Run.
• Consultez Passer du développement à la production en trois étapes faciles avec Cloud Run pour découvrir d'autres options.
• Suivez le tutoriel Django sur Cloud Run pour créer une base de données Cloud SQL, gérer les identifiants avec Secret Manager et déployer Django.
• Découvrez d'autres ateliers de programmation Cloud Run.