Publier en toute sécurité

Ce que vous saurez faire

Mettez l’API sur Internet, avec une adresse HTTPS que tout programme peut appeler. Sa clé la protège dès la première seconde. Aucun secret ne se trouve dans le code, dans un fichier ou dans l’historique de votre terminal.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 45 minutes

Ce que vous devez savoir

• Le mode production et pyproject.toml, dans Premiers pas avec l’hébergement : mode développement et mode production et Premiers pas avec l’hébergement : exemple détaillé : décrire le projet pour une plateforme.
• Les secrets, dans Configuration et secrets : secrets.
• ClassifierUnavailable et sa réponse 503, dans Tests automatisés des points de terminaison : le cas que seul un test peut atteindre : une dépendance défaillante.

Ce qu’il vous faut sur votre ordinateur

• pyproject.toml et l’API qui fonctionne en mode production, dans Premiers pas avec l’hébergement : exercice guidé : prêt pour l’hébergement.
• .gitignore avec .venv/, __pycache__/, .env et .fastapicloud/, dans Environnement et premier point de terminaison : les fichiers qui restent sur votre ordinateur. Vous l’avez vérifié à l’étape 7 de cet exercice guidé.
• La fixture (préparation de test) make_client dans tests/conftest.py, dans Configuration et journalisation : des tests avec leurs propres paramètres. Le nouveau test l’utilise.
• La collection dans Postman et dans postman, avec la requête Vérifier que le service fonctionne, dans Tests et exécutions reproductibles : enregistrer la collection dans le projet.
• Un compte FastAPI Cloud gratuit. Le forfait Hobby (loisir) ne coûte rien, ne demande aucune carte de paiement et permet 3 applications. FastAPI Cloud est créé par l’équipe derrière FastAPI et est en bêta : ses commandes et ses écrans peuvent changer. Si vous ne voulez pas de compte, utilisez la simulation de déploiement local comme preuve et lisez cette leçon. La simulation se trouve dans Premiers pas avec l’hébergement : exemple détaillé : le mode production sur votre ordinateur.
• Si votre projet manque ou ne fonctionne plus, copiez l’instantané end-of-m06, le projet à la fin du module 6. Suivez Utiliser un instantané. Refaites ensuite Premiers pas avec l’hébergement : exercice guidé : prêt pour l’hébergement. Pour utiliser la collection dans l’application Postman, importez les fichiers de postman/ (Import, importer).

Les étapes suivent la documentation de FastAPI Cloud et l’aide de fastapi-cloud-cli 0.26.

Un service d’exercice jetable

Ce déploiement sert à pratiquer. Considérez-le comme jetable : vous le créez, le vérifiez et le supprimez à la fin de la prochaine leçon. Trois règles en découlent :

1. Il reçoit sa propre clé d’API, créée pour lui, jamais une clé que vous utilisez ailleurs.
2. Il ne contient aucune donnée réelle. Le classificateur est la simulation par mots-clés.
3. Vous savez exactement ce que vous avez créé, pour pouvoir tout supprimer.

Vitalité et disponibilité

Une plateforme doit savoir deux choses différentes sur votre application :

Vérification	Question	Point de terminaison	En cas d’échec
Vitalité	Le processus fonctionne-t-il?	/health	Redémarrer l’application.
Disponibilité	Peut-il faire son travail maintenant?	/ready	Ne pas encore lui envoyer de requêtes, mais ne pas le redémarrer.

La différence compte quand le classificateur est en panne. Le processus fonctionne bien, donc le redémarrer n’aide pas, et une boucle de redémarrage aggrave la situation. Mais un client doit savoir que la classification ne fonctionne pas pour le moment. /health reste à 200, et /ready donne 503.

/ready vérifie le travail réel : il demande une prédiction au classificateur. Ajoutez-le à main.py, à côté de /health :

ticket_api/main.py (in create_app, after /health)

    @app.get(
        "/ready",
        tags=["health"],
        summary="Check that the service can classify tickets",
        responses={503: {"model": ErrorResponse, "description": "Not ready."}},
    )
    def ready() -> Readiness:
        app.state.classifier.predict("readiness check")
        return Readiness(status="ready")

ticket_api/models.py (add)

class Readiness(BaseModel):
    status: Literal["ready"]

Importez ErrorResponse et Readiness dans main.py. Si le classificateur lève ClassifierUnavailable, le gestionnaire du module 6 répond 503, dans le format standard. Ajoutez un test, puis mettez à jour le contrat révisé :

tests/test_classify.py (add)

def test_ready_and_not_ready(make_client):
    assert make_client().get("/ready").status_code == 200
    not_ready = make_client(classifier_mode="unavailable").get("/ready")
    assert not_ready.status_code == 503

Étape 1 : se connecter et créer l’application

1. Assurez-vous que votre environnement virtuel est actif. La commande fastapi qui déploie est incluse dans fastapi[standard].

2. Connectez-vous :

   fastapi login

   Une fenêtre de navigateur s’ouvre. Créez votre compte ou connectez-vous, puis autorisez la ligne de commande à l’utiliser. La commande attend, puis indique que vous êtes connecté.

3. Dans le dossier du projet, créez l’application et liez-y le dossier :

   fastapi cloud apps create --name ticket-api --link

   Si le nom est pris, choisissez-en un autre, par exemple ticket-api-yourname. La commande écrit l’identifiant de l’application dans .fastapicloud/cloud.json, pour que les prochaines commandes sachent quelle application utiliser.

Vous créez volontairement l’application avant le premier déploiement : vous pouvez ainsi lui donner sa clé avant toute exécution du code. Si vous déployez d’abord, l’API est publique quelques minutes sans clé. L’avertissement API_KEY is not set (API_KEY n’est pas définie) dans son journal l’indique à toute personne qui le lit.

Étape 2 : une nouvelle clé, stockée comme secret

Créez une longue clé aléatoire avec le module secrets de Python. Envoyez-la à la plateforme sans la taper, pour qu’elle ne soit pas dans l’historique de votre terminal :

macOS

KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
printf %s "$KEY" | fastapi cloud env set API_KEY --secret --value-stdin --no-redeploy
fastapi cloud env set SHOW_DOCS false --no-redeploy
echo "$KEY"

Windows

$key = python -c "import secrets; print(secrets.token_urlsafe(32))"
$key | fastapi cloud env set API_KEY --secret --value-stdin --no-redeploy
fastapi cloud env set SHOW_DOCS false --no-redeploy
$key

Linux

KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
printf %s "$KEY" | fastapi cloud env set API_KEY --secret --value-stdin --no-redeploy
fastapi cloud env set SHOW_DOCS false --no-redeploy
echo "$KEY"

Partie	Pourquoi
secrets.token_urlsafe(32)	32 octets aléatoires sous forme de texte, soit environ 43 caractères. Personne ne peut la deviner.
KEY=$(...)	Garde la clé dans une variable de ce terminal seulement.
--value-stdin	Lit la valeur depuis le `
--secret	FastAPI Cloud chiffre la valeur. Personne ne peut la relire, même vous, dans le tableau de bord ou l’interface en ligne de commande.
--no-redeploy	Enregistre le paramètre sans déploiement. Il n’y a encore rien à déployer.
SHOW_DOCS false	Le système de soutien est le seul client. Les pages de documentation sont donc désactivées en production, comme décidé au module 4. Ce n’est pas un secret.
La dernière ligne	Affiche la clé une seule fois, pour que vous puissiez la copier dans Postman à la prochaine leçon. Copiez-la maintenant, puis fermez ce terminal.

Comme le secret ne peut pas être relu, si vous perdez la clé, vous en définissez une nouvelle. C’est aussi ainsi que vous remplacez une clé qui a été divulguée.

Étape 3 : déployer

Terminal

fastapi deploy

La commande regroupe le dossier du projet, l’envoie et attend pendant que la plateforme construit et démarre l’application. Elle exclut .venv, les caches, .git, tous les fichiers .env et les fichiers indiqués dans .gitignore. À la fin, elle affiche l’adresse de l’application, qui se termine par .fastapicloud.dev. Notez l’adresse.

Vérifiez-la ensuite, avec HTTPS, depuis votre terminal (remplacez l’adresse par la vôtre) :

Terminal (on Windows: curl.exe)

curl -i https://ticket-api.fastapicloud.dev/health
curl -i https://ticket-api.fastapicloud.dev/ready
curl -i https://ticket-api.fastapicloud.dev/docs

Vous attendez 200, 200 et 404. HTTPS fonctionne sans configuration : la plateforme possède un certificat pour ses adresses. Chaque réponse contient un en-tête X-Request-ID, fourni par votre intergiciel.

Exercice guidé : publier l’API

1. Ajoutez /ready, son modèle et son test. Exécutez les tests, examinez la différence du contrat (un nouveau point de terminaison), puis exportez le contrat.
2. Dans Postman, dupliquez Vérifier que le service fonctionne sous le nom Vérifier que le service peut classer les billets, avec l’URL {{baseUrl}}/ready. Ajoutez ces tests : le code d’état est 200, et status (état) vaut ready (prêt). Exportez de nouveau la collection dans postman/.
3. Vérifiez .gitignore : il contient .venv/, __pycache__/, .env et .fastapicloud/.
4. Connectez-vous avec fastapi login, puis créez l’application liée avec fastapi cloud apps create --name ticket-api --link.
5. Créez la clé, puis définissez API_KEY (secret) et SHOW_DOCS, tous deux avec --no-redeploy. Copiez la clé affichée par la dernière commande et fermez le terminal.
6. Ouvrez un nouveau terminal, activez l’environnement et exécutez fastapi deploy. Notez l’adresse.
7. Appelez /health, /ready et /docs avec curl. Vérifiez les trois codes d’état et l’en-tête X-Request-ID.
8. Envoyez une requête de classification sans clé : 401. La clé protège l’API dès le premier déploiement.

À vous de jouer : le tableau de bord

Ouvrez le tableau de bord de FastAPI Cloud dans votre navigateur et trouvez votre application. Sans rien changer, trouvez :

1. L’adresse de l’application.
2. Les variables d’environnement. Pouvez-vous voir la valeur de API_KEY? De SHOW_DOCS?
3. Le dernier déploiement et son état.

Afficher ce que vous devriez voir

L’adresse est celle que fastapi deploy a affichée. Sous Environment Variables (variables d’environnement), SHOW_DOCS affiche false (faux), et API_KEY indique un secret, sans sa valeur. Les secrets ne peuvent pas être consultés après leur enregistrement. Le déploiement figure dans la liste avec son état. Le tableau de bord peut faire les mêmes choses que les commandes de l’interface en ligne de commande. La prochaine leçon l’utilise pour supprimer l’application.

Erreur courante

L'application est déployée, mais chaque requête de classification reçoit 401, même avec la clé

Symptôme : /health fonctionne, mais les requêtes de classification reçoivent 401 avec la clé que vous avez copiée.

Cause : la clé de l’application n’est pas celle que vous envoyez. Il y a quelques raisons courantes. La clé a été définie après le déploiement avec --no-redeploy, donc l’application en cours d’exécution ne l’a pas encore. Ou un espace ou un saut de ligne a été copié avec elle. Ou un deuxième env set l’a remplacée par une nouvelle clé aléatoire.

Solution :

1. Cherchez le message de démarrage API_KEY is not set dans le journal de l’application (prochaine leçon : fastapi cloud logs). S’il s’y trouve, déployez de nouveau : fastapi deploy.
2. Si vous ne savez pas quelle clé possède l’application, définissez-en une nouvelle et utilisez-la. Suivez l’étape 2, sans --no-redeploy cette fois, pour que l’application redémarre avec elle.
3. Ne définissez pas la clé sans --secret pour la rendre visible. Une clé qu’on peut lire est une clé qu’on peut divulguer.

Vérifiez votre compréhension

Pourquoi créer l'application et son secret avant le premier fastapi deploy, plutôt que déployer d'abord et ajouter la clé ensuite?

Afficher la réponse

L’application lit API_KEY au démarrage. Sans cette clé, /v1/classify accepte les requêtes de n’importe qui, et l’adresse est publique dès la fin du déploiement. Créer l’application et son secret d’abord signifie que la toute première version en cours d’exécution est déjà protégée. Il n’y a jamais de période, même très courte, où l’API est ouverte.

Vérifiez votre compréhension

Le classificateur est en panne. Que retournent /health et /ready, et que doit faire la plateforme?

Afficher la réponse

/health retourne 200 : le processus fonctionne, donc le redémarrer n’aiderait pas. /ready retourne 503 avec classifier_unavailable : le service ne peut pas faire son travail maintenant. La plateforme, ou un outil de surveillance, doit arrêter d’envoyer des requêtes de classification ou avertir quelqu’un. Elle ne doit pas redémarrer l’application en boucle.

De bout en boutServir un modèle de prix des maisonsÉtude de cas

L’étude de cas sur le prix des maisons déploie une API qui inclut un modèle d’apprentissage automatique. Elle consigne ce que l’instance gratuite peut prendre en charge.

Récapitulatif

• Un déploiement d’exercice est jetable : sa propre clé, aucune donnée réelle, et vous le supprimez ensuite.
• /health vérifie la vitalité (redémarrer en cas d’échec). /ready vérifie la disponibilité (le service peut faire son travail maintenant).
• Créez l’application, définissez ses secrets avec --secret --value-stdin, puis déployez. La première version en cours d’exécution est déjà protégée.
• Les secrets sur la plateforme ne peuvent pas être relus. Pour remplacer une clé, définissez-en une nouvelle.
• La plateforme vous fournit HTTPS. Vérifiez /health, /ready et une requête sans clé après chaque déploiement.

Ensuite, vous vérifiez l’API déployée avec la collection Postman, lisez ses journaux et la supprimez.

Leçon suivante : Vérifier et nettoyer