EvolutionAPI sur GKE Autopilot

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 GKE Autopilot au-dessus du socle App_GKE, qui provisionne et gère l'infrastructure Google Cloud et Kubernetes 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 GKE — Workload Identity, entrée, autoscaling, 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_GKE plutôt que de les répéter ici.

1. Vue d'ensemble

Evolution API s'exécute comme une charge de travail web Node.js sur GKE Autopilot. Le déploiement assemble un ensemble ciblé de services Google Cloud :

Fonctionnalité	Service Google Cloud	Remarques
Calcul	GKE Autopilot	Pod Node.js, 2 vCPU / 4 GiB par défaut ; épinglé à un seul réplica
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	Cloud Load Balancing	LoadBalancer externe avec affinité de session `ClientIP` ; domaine personnalisé et certificat géré 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.
La charge de travail est épinglée à un seul réplica (min_instance_count = 1, max_instance_count = 1). Evolution API conserve en mémoire, par pod, 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. 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'affinité de session est ClientIP et le type de Service est LoadBalancer par défaut, ce qui expose une IP externe pour les rappels de webhook WhatsApp et l'interface de gestion.
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 reçoit une valeur par défaut à l'exécution de la part du point d'entrée du conteneur, à partir de l'URL de service injectée, de sorte que les URL de QR code et de rappel de webhook reflètent l'adresse réelle.

2. Services Google Cloud et comment les explorer

Toutes les commandes supposent que vous avez exécuté gcloud container clusters get-credentials <cluster> --region <region> --project <project> et que PROJECT, REGION et NAMESPACE sont définis. L'espace de noms et les autres identifiants figurent dans les sorties du déploiement.

A. GKE Autopilot — la charge de travail Evolution API

Les pods Evolution API sont planifiés sur Autopilot, qui facture le CPU et la mémoire effectivement demandés par les pods. La charge de travail s'exécute en un seul réplica par conception.

Console : Kubernetes Engine → Workloads → sélectionnez la charge de travail Evolution API pour voir les pods, les révisions et les événements. Kubernetes Engine → Services & Ingress affiche l'IP externe.

CLI :

kubectl get pods,svc -n "$NAMESPACE"
kubectl logs -n "$NAMESPACE" deploy/<service-name> --tail=100
kubectl describe pod -n "$NAMESPACE" -l app=<service-name>

Consultez App_GKE pour la gestion d'Autopilot, de la mise à l'échelle et du type de charge de travail (Deployment ou StatefulSet).

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. Les pods s'y connectent de manière privée via le sidecar Cloud SQL Auth Proxy sur une boucle locale TCP (127.0.0.1) ; 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"
# Open an interactive shell to inspect schema/data:
gcloud sql connect <instance-name> --user=evolution --database=evolution --project "$PROJECT"

Le nom de l'instance, la base de données (evolution), l'utilisateur (evolution) et le secret Secret Manager contenant le mot de passe figurent tous dans les sorties. Pour le modèle de connexion, les sauvegardes automatisées et la rotation du mot de passe, consultez App_GKE.

C. Cloud Storage

Un bucket de données Cloud Storage dédié est provisionné automatiquement pour le stockage de fichiers d'Evolution API. Le compte de service de la charge de travail reçoit l'accès. 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_GKE pour les options CMEK et les montages GCS Fuse.

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 injected into the running pod:
kubectl exec -n "$NAMESPACE" deploy/<service-name> -- env | grep CACHE_REDIS

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, montée via le pilote Secret Store CSI. 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"

Le nom du secret du mot de passe de la base de données figure dans les sorties. Consultez App_GKE pour l'intégration Secret Store CSI et la rotation.

F. Réseau et entrée

Par défaut, la charge de travail est exposée via une IP Cloud Load Balancing externe avec une affinité de session ClientIP — nécessaire pour que les requêtes d'un client WhatsApp restent attachées à l'unique pod qui détient son socket. Un domaine personnalisé avec un certificat géré par Google peut être activé, et une IP statique peut être réservée afin que l'adresse survive aux redéploiements.

Console : Network services → Load balancing ; VPC network → IP addresses.

CLI :

kubectl get ingress,svc -n "$NAMESPACE"
gcloud compute addresses list --project "$PROJECT"

Consultez App_GKE pour les domaines personnalisés, Cloud CDN et les détails sur l'IP statique.

G. Cloud Logging et Monitoring

Les sorties stdout/stderr des pods sont envoyées à Cloud Logging ; les métriques GKE et Cloud SQL sont envoyées à Cloud Monitoring. 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. Des tests de disponibilité et des règles d'alerte facultatifs sont disponibles.

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

CLI :

gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="'"$NAMESPACE"'"' \
  --project "$PROJECT" --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, puis signale au sidecar du proxy de s'arrêter afin que le pod du Job se termine. 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. Sur GKE, le sidecar cloud-sql-proxy est une boucle locale TCP ; le point d'entrée se connecte donc avec sslmode=disable.
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.
Réplica unique par conception. Les sessions de socket WhatsApp (Baileys) résident dans la mémoire du pod et ne sont pas partagées entre réplicas. min_instance_count = 1 en garde un en cours d'exécution ; max_instance_count = 1 évite de fragmenter les connexions actives. Ne procédez pas à une mise à l'échelle horizontale. L'affinité de session ClientIP maintient chaque client attaché au pod.
URL de rappel webhook / QR. Le point d'entrée attribue par défaut à SERVER_URL l'URL de service injectée. Une fois l'IP externe du LoadBalancer attribuée, définissez SERVER_URL (via environment_variables) sur l'URL externe afin que les rappels de QR code et de webhook utilisent une adresse joignable :
```
kubectl get svc <service-name> -n "$NAMESPACE" \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
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 plusieurs minutes au premier démarrage, le temps que les migrations Prisma s'exécutent.

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_GKE avec leur comportement et leurs valeurs par défaut standard.