Guide de déploiement dans le cloud

La commande supervaizer deploy construit votre agent Supervaizer sous forme d'image Docker. Elle pousse l'image vers le registre de la plateforme et démarre le service.

Vue d'ensemble

info

La CLI de déploiement prend en charge trois plateformes cloud :

• GCP Cloud Run - Plateforme de conteneurs serverless
• AWS App Runner - Service de conteneurs entièrement managé
• DigitalOcean App Platform - Hébergement d'applications à base de conteneurs

Le parcours comporte cinq étapes :

Tester en local - Exécutez votre agent avec Docker avant de déployer

Planifier - Prévisualisez les changements

Déployer - Construisez, poussez et déployez le service

Surveiller - Vérifiez le statut et l'état de santé

Nettoyer - Supprimez le déploiement

Prérequis

Installer l'extra deploy

Les commandes de déploiement ont besoin de l'extra deploy du paquet.

pip install "supervaizer[deploy]"

Exécutez les commandes dans un répertoire qui contient un fichier pyproject.toml. Un répertoire parent, jusqu'à trois niveaux au-dessus, fonctionne aussi. Déclarez les dépendances Python de votre agent dans ce fichier.

Configuration du fournisseur cloud

Avant d'utiliser la CLI de déploiement, effectuez la configuration propre à votre plateforme.

GCP Cloud Run

Installer et s'authentifier

# Installer la CLI Google Cloud
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# S'authentifier
gcloud auth login
gcloud auth application-default login

# Définir le projet
gcloud config set project YOUR_PROJECT_ID

# Activer les API requises
gcloud services enable run.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com

Autorisations requises

Votre compte a besoin de ces rôles IAM :

• Cloud Run Admin
• Secret Manager Admin
• Artifact Registry Writer
• Service Account User

AWS App Runner

Installer et s'authentifier

# Installer la CLI AWS
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Configurer les identifiants
aws configure
# Saisir : Access Key ID, Secret Access Key, Region, Output format

Autorisations requises

Votre compte a besoin de ces autorisations IAM :

• apprunner:*
• ecr:*
• secretsmanager:*
• iam:PassRole

DigitalOcean App Platform

Installer et s'authentifier

# Installer doctl
snap install doctl

# S'authentifier
doctl auth init
# Saisir votre jeton d'API DigitalOcean

Créer un registre de conteneurs

DigitalOcean autorise un seul registre de conteneurs par compte. La CLI utilise ce registre. Créez-le une seule fois.

doctl registry create <registry-name>

Autorisations requises

Votre jeton d'API a besoin de ces portées :

• read - Accès en lecture aux ressources

• write - Accès en écriture aux ressources

Prérequis locaux

# Docker doit être installé et en cours d'exécution
docker --version
docker ps

# Dépôt Git (pour le tag de l'image)
git status

Commandes

Planifier le déploiement

Prévisualisez ce que la CLI va déployer :

# Planifier un déploiement vers GCP Cloud Run
supervaizer deploy plan --platform cloud-run --name my-agent --env prod

# Planifier avec plus d'options
supervaizer deploy plan \
  --platform aws-app-runner \
  --name email-agent \
  --env staging \
  --region us-east-1 \
  --project-id my-aws-account

La commande affiche la plateforme, la région et l'image cible. Elle affiche aussi un tableau d'actions avec le type, la ressource, l'action et la description.

Déployer l'application

Déployez votre agent Supervaizer :

# Déployer vers GCP Cloud Run
supervaizer deploy up --platform cloud-run --name my-agent

# Déployer avec plus d'options
supervaizer deploy up \
  --platform do-app-platform \
  --name email-agent \
  --env prod \
  --region nyc3 \
  --port 8000 \
  --generate-api-key \
  --generate-rsa

Processus de déploiement :

1. Build - Construire l'image Docker à partir de votre code.
2. Push - Pousser l'image vers le registre de la plateforme.
3. Secrets - Stocker les clés d'API en tant que secrets de la plateforme.
4. Deploy - Créer ou mettre à jour le service.
5. Configure - Définir SUPERVAIZER_PUBLIC_URL sur l'URL du service.
6. Verify - Vérifier l'état de santé du service.

La commande affiche l'URL du service, les URL de la documentation, la révision, le statut et l'état de santé.

Nom de l'image

L'option --image accepte name[:tag]. La CLI ajoute le registre de la plateforme. Une valeur contenant / n'est pas valide.

L'image par défaut est {name}-{env}:{git-sha}.

Plateforme	Registre
cloud-run	Artifact Registry de votre projet
aws-app-runner	Amazon ECR de votre compte
do-app-platform	Registre de conteneurs de votre compte

Les identifiants restent hors de l'image

La CLI ne place pas d'identifiants dans l'image. Elle les fournit au service à l'exécution.

Vérifier le statut

Vérifiez le statut et l'état de santé de votre déploiement :

supervaizer deploy status --platform cloud-run --name my-agent --env prod

La commande affiche l'état local issu de .deployment/state.json. Elle affiche ensuite le statut réel fourni par la plateforme.

Supprimer le déploiement

Supprimez le service et ses ressources :

# Demander une confirmation
supervaizer deploy down --platform cloud-run --name my-agent --env prod

# Passer la confirmation
supervaizer deploy down --platform aws-app-runner --name email-agent --yes

Processus de nettoyage :

1. Confirmation - La CLI demande une confirmation. L'option --yes la passe.
2. Suppression - La CLI supprime le service.
3. Secrets - Sur Cloud Run et AWS, la CLI supprime les secrets du service.
4. État - La CLI supprime l'état de déploiement local.

Registres

Sur AWS, la commande supprime aussi le dépôt ECR du service. Sur Cloud Run et DigitalOcean, les images restent dans le registre. DigitalOcean conserve le registre parce que tout le compte le partage.

Tester en local

Testez votre agent avec Docker avant de déployer :

# Tester en local avec les réglages par défaut
supervaizer deploy local --name my-agent

# Tester avec plus d'options
supervaizer deploy local \
  --name email-agent \
  --env dev \
  --port 8000 \
  --generate-api-key \
  --generate-rsa \
  --timeout 60 \
  --verbose

Processus de test local :

1. Vérification de Docker - Vérifier que Docker s'exécute.
2. Secrets - Définir la clé d'API de test et la clé RSA facultative.
3. Génération des fichiers - Créer le Dockerfile, docker-compose.yml et .dockerignore.
4. Construction de l'image - Construire l'image avec le tag local-test.
5. Démarrage - Démarrer le service avec Docker Compose.
6. Attente - Attendre que le service réponde.
7. Contrôle de santé - Appeler /.well-known/health et /docs.
8. Affichage des informations - Afficher l'URL du service et les informations d'accès.

La commande affiche l'URL du service, l'URL /docs et l'URL /redoc.

Options du test local :

Option	Description	Valeur par défaut
--name	Nom de base du service (requis, la CLI le demande)	aucune
--env	Environnement (dev, staging, prod)	dev
--port	Port de l'application	8000
--generate-api-key	Créer une clé d'API aléatoire pour le test	false
--generate-rsa	Générer une clé privée RSA pour le test	false
--timeout	Nombre de secondes d'attente du service	300
--verbose	Afficher la sortie de Docker Compose	false
--docker-files-only	Générer les fichiers Docker sans les exécuter	false
--controller-file	Nom du fichier du contrôleur	supervaizer_control.py

Sans --generate-api-key, la clé d'API de test est test-api-key-local.

Mode fichiers Docker uniquement :

Utilisez --docker-files-only pour générer les fichiers Docker sans démarrer les services :

supervaizer deploy local --docker-files-only --name my-agent

Ce mode est utile pour :

• Les pipelines CI/CD - Générer les fichiers pour une étape Docker externe
• Les configurations Docker personnalisées - Utiliser les fichiers dans votre propre workflow
• L'inspection des fichiers - Lire le Dockerfile avant de l'exécuter

Fichiers générés :

• .deployment/Dockerfile - Définition de l'image du conteneur
• .deployment/docker-compose.yml - Orchestration du service
• .deployment/.dockerignore - Exclusions du build Docker

Le fichier docker-compose.yml contient des valeurs secrètes. La CLI règle son mode sur 600.

Fichier de contrôleur personnalisé :

Utilisez --controller-file quand votre contrôleur porte un autre nom :

supervaizer deploy local --controller-file my_controller.py

Nettoyage :

# Arrêter les services locaux
docker compose -f .deployment/docker-compose.yml down

# Supprimer les fichiers générés
supervaizer deploy clean

Testez d'abord

Le test local est rapide. Il ne nécessite pas d'authentification auprès du cloud.

Nettoyer les fichiers générés

Supprimez les fichiers de .deployment/ :

# Tout supprimer, après confirmation
supervaizer deploy clean

# Passer la confirmation
supervaizer deploy clean --force

# Supprimer uniquement les fichiers Docker
supervaizer deploy clean --docker-only

# Supprimer uniquement l'état de déploiement
supervaizer deploy clean --state-only

Vous ne pouvez pas utiliser --docker-only et --state-only ensemble. L'option --verbose affiche plus de détails.

Options de configuration

Options communes

Option	Description	Valeur par défaut
--platform	Plateforme cloud (cloud-run, aws-app-runner, do-app-platform)	requis
--name	Nom de base du service (requis, la CLI le demande)	aucune
--env	Environnement (dev, staging, prod)	dev
--region	Région du fournisseur	us-central1, us-east-1 ou nyc3
--project-id	Projet GCP / compte AWS / projet DO	aucune
--port	Port de l'application (up et local)	8000
--image	Image name[:tag] (up)	{name}-{env}:{git-sha}
--generate-api-key	Créer une clé d'API sécurisée (up et local)	false
--generate-rsa	Générer une clé privée RSA (up et local)	false
--timeout	Délai d'expiration en secondes (up et local)	300
--yes	Passer la demande de confirmation (down)	false

La région par défaut dépend de la plateforme : us-central1 pour cloud-run, us-east-1 pour aws-app-runner et nyc3 pour do-app-platform.

Variables d'environnement

La CLI définit ces variables dans le service.

Variables standard

Variable	Valeur	Description
SUPERVAIZER_ENVIRONMENT	Valeur de --env	Nom de l'environnement
SUPERVAIZER_HOST	0.0.0.0	Écoute sur toutes les interfaces
SUPERVAIZER_PORT	Valeur de --port	Port de l'application
SUPERVAIZER_LOG_LEVEL	La valeur de votre shell, ou INFO	Niveau de journalisation
SUPERVAIZER_PUBLIC_URL	URL du service	La CLI la définit après le déploiement

Variables issues de votre shell

La CLI copie ces variables dans le service quand elles sont définies dans votre shell :

• SUPERVAIZE_API_KEY
• SUPERVAIZE_WORKSPACE_ID
• SUPERVAIZE_API_URL
• SUPERVAIZER_SERVER_ID
• SUPERVAIZER_WORKSPACE_AUTH_REQUIRED
• SUPERVAIZER_WORKSPACE_AUTH_ISSUER
• SUPERVAIZER_WORKSPACE_AUTH_AUDIENCE
• SUPERVAIZER_WORKSPACE_AUTH_PUBLIC_KEY
• SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL
• SUPERVAIZER_WORKSPACE_AUTH_LEEWAY_SECONDS

La commande supervaizer login écrit les variables SUPERVAIZE_* et SUPERVAIZER_WORKSPACE_AUTH_* dans un fichier. Voir le démarrage rapide. Chargez ce fichier dans votre shell avant d'exécuter deploy up.

Variables secrètes

Variable	Source	Description
SUPERVAIZER_API_KEY	--generate-api-key	Clé d'API pour les routes /api
SUPERVAIZER_PRIVATE_KEY	--generate-rsa	Clé RSA pour le chiffrement
SUPERVAIZE_API_KEY	Votre shell	Clé d'API Studio

La CLI stocke ces valeurs dans le gestionnaire de secrets de la plateforme.

Fichiers générés

La CLI écrit ses fichiers dans le répertoire .deployment/ :

.deployment/
├── Dockerfile              # Image Docker générée
├── .dockerignore           # Règles d'exclusion Docker
├── docker-compose.yml      # Test local
├── do-app-spec.yaml        # Spécification d'application DigitalOcean
├── state.json              # État du déploiement
└── logs/                   # Journaux de déploiement

info

La CLI ajoute .deployment/ à .gitignore. Les fichiers docker-compose.yml et do-app-spec.yaml contiennent des valeurs secrètes et ont le mode 600.

Interface d'administration

L'interface d'administration se trouve à l'adresse /manage. Vous ne pouvez l'ouvrir que depuis un réseau Tailscale. En mode local, l'interface de bouclage (loopback) fonctionne aussi. Une URL de service publique n'y donne pas accès.

Voir la documentation d'administration.

Vérification de l'état de santé

La CLI vérifie le service au chemin /.well-known/health :

curl https://your-service-url/.well-known/health

Cette route fait partie des routes A2A du serveur. Activez les points de terminaison A2A dans votre Server.

La CLI répète la vérification avec des délais croissants jusqu'à ce que le service réponde ou que le délai d'expiration soit atteint.

Dépannage

Problèmes courants

Erreurs d'authentification

# GCP : s'authentifier de nouveau
gcloud auth login
gcloud auth application-default login

# AWS : vérifier les identifiants
aws sts get-caller-identity

# DigitalOcean : s'authentifier de nouveau
doctl auth init

Erreurs d'autorisation

Vérifiez que votre compte dispose des autorisations requises pour votre plateforme. Voir Prérequis.

Échecs du build Docker

# Vérifier que Docker s'exécute
docker ps

# Lire le Dockerfile généré
cat .deployment/Dockerfile

Délais dépassés du contrôle de santé

# Vérifier le statut
supervaizer deploy status --platform cloud-run --name my-agent

# Tester le point de terminaison de santé
curl https://your-service-url/.well-known/health

# Augmenter le délai d'expiration
supervaizer deploy up --platform cloud-run --name my-agent --timeout 600

DigitalOcean : aucun registre de conteneurs

Créez le registre avec doctl registry create <registry-name>. Relancez ensuite la commande.

Débogage

Lisez l'état du déploiement :

cat .deployment/state.json

Bonnes pratiques

Sécurité

1. Clés d'API - Utilisez --generate-api-key en production.
2. Secrets - Ne commitez jamais de secrets dans le contrôle de version.
3. Autorisations - Utilisez des rôles IAM au moindre privilège.
4. Réseau - Configurez le VPC et les règles de pare-feu selon vos besoins.

Performance

1. Taille de l'image - Gardez une image Docker petite.
2. Dépendances - Ne déclarez dans pyproject.toml que les dépendances dont vous avez besoin.

Et ensuite ?

• Surveillez votre déploiement avec l'interface d'administration à l'adresse /manage.
• Intégrez les commandes à votre pipeline CI/CD.

Besoin d'aide ?

• Consultez le guide de dépannage pour les problèmes courants
• Consultez la documentation de la CLI pour les options de ligne de commande
• Consultez la référence de l'API REST pour des informations détaillées sur les points de terminaison
• Rendez-vous sur le dépôt GitHub pour obtenir de l'aide