EvolutionAPI sur Google Cloud Run

Evolution API est une passerelle open source Node.js vers l'API WhatsApp Business (construite sur la bibliothèque Baileys) qui provisionne des instances WhatsApp, envoie et reçoit des messages, et expose une API REST ainsi qu'une interface de gestion (manager) pour intégrer WhatsApp à d'autres systèmes. Ce module déploie Evolution API sur Cloud Run v2 au-dessus du socle App_CloudRun, qui provisionne et gère l'infrastructure Google Cloud partagée.

Ce guide se concentre sur les services cloud qu'utilise Evolution API et sur la manière de les explorer et de les exploiter depuis la console Google Cloud et la ligne de commande. Pour les mécanismes communs à toute application Cloud Run — identité du service, entrée et équilibrage de charge, mise à l'échelle et concurrence, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide du socle App_CloudRun plutôt que de les répéter ici.

1. Vue d'ensemble

Evolution API s'exécute comme un conteneur Node.js sur Cloud Run v2. Le déploiement assemble un ensemble ciblé de services Google Cloud :

Fonctionnalité	Service Google Cloud	Remarques
Calcul	Cloud Run v2	Service Node.js, 2 vCPU / 4 GiB par défaut ; épinglé à une seule instance toujours active
Base de données	Cloud SQL for PostgreSQL 15	Obligatoire — Evolution API utilise Prisma, uniquement avec PostgreSQL
Cache	Redis	Activé par défaut (`CACHE_REDIS_URI`) ; met en cache l'état des instances et des messages
Stockage objet	Cloud Storage	Un bucket de données dédié, provisionné automatiquement
Secrets	Secret Manager	`AUTHENTICATION_API_KEY` généré automatiquement ; mot de passe de la base de données
Entrée	URL Cloud Run / Cloud Load Balancing	URL `run.app` par défaut (publique) ; équilibreur de charge HTTPS externe et domaine personnalisé facultatifs

Valeurs par défaut judicieuses à connaître d'emblée :

PostgreSQL 15 est obligatoire. Le moteur de base de données est fixé par la couche applicative partagée ; Evolution API utilise Prisma et ne prend pas en charge d'autres moteurs.
Le service est épinglé à une seule instance (min_instance_count = 1, max_instance_count = 1). Evolution API conserve en mémoire, par instance, les sessions de socket WhatsApp (Baileys) actives ; ces sessions ne sont pas partagées entre réplicas, si bien que la mise à l'échelle horizontale fragmente les connexions actives et qu'une instance doit rester active. N'augmentez pas max_instance_count.
AUTHENTICATION_API_KEY est généré automatiquement et stocké dans Secret Manager. C'est la clé d'administration globale d'Evolution API, et elle ne doit jamais faire l'objet d'une rotation après le premier démarrage — la renouveler rend injoignables les instances WhatsApp déjà provisionnées et renvoie 401 à tout client qui détient encore l'ancienne clé.
Redis est activé par défaut (enable_redis = true). Laissez redis_host vide pour utiliser l'IP de la VM du serveur NFS comme point de terminaison Redis (nécessite enable_nfs = true), ou pointez-le vers une instance gérée explicite.
L'entrée publique est la valeur par défaut (ingress_settings = "all") afin que les systèmes externes puissent atteindre les points de terminaison de webhook et l'interface de gestion. Activer IAP bloque ces appels externes.
La mémoire est de 4 GiB par défaut — Evolution API a besoin d'au moins 2 GiB pour fonctionner de manière fiable.
SERVER_URL prend par défaut l'URL réelle du service à l'exécution, via le point d'entrée du conteneur, de sorte que les URL de QR code et de rappel de webhook reflètent l'adresse Cloud Run réelle.

2. Services Google Cloud et comment les explorer

Toutes les commandes supposent que PROJECT et REGION sont définis. Les noms des services et des ressources figurent dans les sorties du déploiement.

A. Cloud Run — le service Evolution API

Evolution API s'exécute comme un service Cloud Run v2 épinglé à une seule instance. Chaque déploiement crée une révision immuable ; le trafic peut être réparti entre les révisions pour des déploiements progressifs sûrs.

Console : Cloud Run → sélectionnez le service pour consulter les révisions, le trafic, les journaux et les métriques.

CLI :

gcloud run services list --project "$PROJECT" --region "$REGION" \
  --filter="metadata.name~evolutionapi"
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

Consultez App_CloudRun pour la mise à l'échelle, la concurrence, l'environnement d'exécution et la répartition du trafic.

B. Cloud SQL for PostgreSQL 15

Evolution API stocke toutes les données applicatives (instances WhatsApp, contacts, conversations, historique des messages) dans une instance gérée Cloud SQL for PostgreSQL 15. Le service s'y connecte de manière privée via le Cloud SQL Auth Proxy sur un socket Unix ; aucune IP publique n'est exposée. Au premier déploiement, un Job d'initialisation crée la base de données et l'utilisateur de l'application ; les migrations Prisma créent ensuite le schéma au démarrage du conteneur.

Console : SQL → sélectionnez l'instance pour consulter les connexions, les sauvegardes, les flags et les métriques.

CLI :

gcloud sql instances list --project "$PROJECT"
gcloud sql instances describe <instance-name> --project "$PROJECT"
gcloud sql connect <instance-name> --user=evolution --database=evolution --project "$PROJECT"

Le nom de l'instance, la base de données, l'utilisateur et le secret du mot de passe figurent dans les sorties. Consultez App_CloudRun pour le modèle de connexion, les sauvegardes et la rotation du mot de passe.

C. Cloud Storage

Un bucket de données Cloud Storage dédié est provisionné automatiquement pour le stockage de fichiers d'Evolution API. Des buckets supplémentaires peuvent être déclarés via storage_buckets.

Console : Cloud Storage → Buckets.

CLI :

gcloud storage buckets list --project "$PROJECT"
gcloud storage ls gs://<data-bucket>/        # bucket name is in the Outputs

Consultez App_CloudRun pour les options GCS Fuse et CMEK.

D. Cache Redis

Redis est activé par défaut (enable_redis = true). Evolution API l'utilise pour mettre en cache les instances et les messages (CACHE_REDIS_URI, index de base Redis 6). Lorsque redis_host est laissé vide et que enable_nfs = true, l'IP de la VM du serveur NFS sert de point de terminaison Redis ; le point d'entrée du conteneur assemble l'URI à l'exécution.

Console : Memorystore → Redis (si vous utilisez une instance gérée).

CLI :

redis-cli -h <redis-host> ping
redis-cli -h <redis-host> info keyspace
# Confirm the cache URI is set in the running revision:
gcloud run services describe <service-name> --region "$REGION" \
  --format='value(spec.template.spec.containers[0].env)'

E. Secret Manager

Un secret cryptographique est généré automatiquement et stocké dans Secret Manager : AUTHENTICATION_API_KEY — la clé d'API d'administration globale d'Evolution API, injectée comme variable d'environnement secrète. Le mot de passe de la base de données est géré séparément par le socle.

Console : Security → Secret Manager.

CLI :

gcloud secrets list --project "$PROJECT" --filter="name~api-key"
gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

Consultez App_CloudRun pour les détails d'injection et de rotation.

F. Réseau et entrée

Le service est joignable par défaut à son URL run.app, ce qui permet l'accès public nécessaire aux rappels de webhook WhatsApp et à l'interface de gestion. Un équilibreur de charge HTTPS externe avec domaine personnalisé, Cloud CDN et Cloud Armor peut être ajouté par-dessus ; les paramètres d'entrée et la sortie VPC contrôlent la connectivité.

Console : Cloud Run (URL du service) ; Network services → Load balancing.

CLI :

gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
gcloud compute addresses list --project "$PROJECT"

Consultez App_CloudRun.

G. Cloud Logging et Monitoring

Les journaux des conteneurs sont envoyés à Cloud Logging ; les métriques Cloud Run et Cloud SQL sont envoyées à Cloud Monitoring, avec des tests de disponibilité et des règles d'alerte facultatifs. Le point d'entrée émet des marqueurs [cloud-entrypoint] qui confirment au démarrage la configuration résolue de la base de données, de Redis et de l'URL.

Console : Logging → Logs Explorer ; Monitoring → Dashboards / Alerting.

CLI :

gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Comportement de l'application EvolutionAPI

Configuration de la base de données au premier déploiement. Un Job d'initialisation exécute db-init.sh avec postgres:15-alpine. Il se connecte via le Cloud SQL Auth Proxy et crée de manière idempotente la base de données et le rôle evolution, accorde les privilèges et fait de l'utilisateur de l'application le propriétaire du schéma public. Le job peut être réexécuté sans risque.
Migrations Prisma au démarrage. Evolution API exécute prisma migrate deploy à chaque démarrage du conteneur (via le script encapsulé deploy_database.sh), de sorte que la mise à niveau de la version de l'application applique les modifications de schéma sans étape de migration distincte. Le point d'entrée attend le socket Cloud SQL avant cette exécution et lance le script de migration comme sous-processus, afin qu'un échec transitoire ne puisse pas empêcher le serveur de démarrer.
AUTHENTICATION_API_KEY est immuable après le premier démarrage. La clé d'administration globale est générée une seule fois et écrite dans Secret Manager. La renouveler rend injoignables toutes les instances WhatsApp déjà provisionnées et renvoie 401 à tout client qui détient encore l'ancienne clé. Ne la renouvelez que lors d'une migration planifiée.
Instance unique par conception. Les sessions de socket WhatsApp (Baileys) résident dans la mémoire de l'instance et ne sont pas partagées entre réplicas. min_instance_count = 1 en garde une active ; max_instance_count = 1 évite de fragmenter les connexions actives. Ne procédez pas à une mise à l'échelle horizontale.
URL de rappel webhook / QR. Le point d'entrée attribue par défaut à SERVER_URL la valeur injectée CLOUDRUN_SERVICE_URL, de sorte que les URL de QR code et de rappel de webhook utilisent l'adresse réelle du service. Vérifiez l'URL du service en cours d'exécution :
```
gcloud run services describe <service-name> \
  --region "$REGION" --project "$PROJECT" --format='value(status.url)'
```
Configuration initiale. Après le déploiement, récupérez AUTHENTICATION_API_KEY dans Secret Manager et utilisez-la (comme en-tête apikey) pour accéder à l'interface de gestion sur /manager, créez une instance WhatsApp (POST /instance/create), puis scannez le QR code renvoyé depuis WhatsApp sur votre téléphone pour connecter le numéro.
Chemin de santé. Les sondes de démarrage et de vivacité ciblent la racine / — un point de terminaison d'état non authentifié qui répond dès que le serveur est opérationnel. Prévoyez environ 7 minutes au premier démarrage (la sonde de démarrage accorde un délai initial de 60 secondes plus une fenêtre de 30 tentatives pendant les migrations Prisma).

Inspecter l'exécution des jobs :

gcloud run jobs list --project "$PROJECT" --region "$REGION"
gcloud run jobs executions list --job <job-name> --project "$PROJECT" --region "$REGION"

4. Variables de configuration

Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres propres à Evolution API ou notables pour elle sont listés ; toutes les autres entrées sont héritées de App_CloudRun avec leur comportement standard.