Cal.com sur GKE Autopilot

Cal.com est une plateforme de planification open source sous licence AGPL — l'alternative auto-hébergée à Calendly — construite avec Next.js et Prisma sur PostgreSQL. Ce module déploie Cal.com sur GKE Autopilot en s'appuyant sur le socle App_GKE, qui provisionne et gère l'infrastructure Google Cloud et Kubernetes partagée.

Ce guide se concentre sur les services cloud utilisés par Cal.com 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 à toutes les applications 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

Cal.com s'exécute sous la forme d'une charge de travail web Next.js. Le déploiement assemble un ensemble ciblé de services Google Cloud :

Fonctionnalité	Service Google Cloud	Remarques
Calcul	GKE Autopilot	Pods Next.js, 2 vCPU / 2 GiB par défaut, autoscaling horizontal
Base de données	Cloud SQL for PostgreSQL 15	Obligatoire — Cal.com (Prisma/`pg`) cible uniquement PostgreSQL
Stockage d'objets	Cloud Storage (aucun par défaut)	Cal.com stocke tout son état dans PostgreSQL ; aucun bucket de téléversement n'est créé
Cache	Redis (facultatif)	Désactivé par défaut ; utilisé pour la mise en cache / la limitation de débit
Secrets	Secret Manager	`NEXTAUTH_SECRET` et `CALENDSO_ENCRYPTION_KEY` générés automatiquement ; mot de passe de la base de données
Entrée	Cloud Load Balancing	Service LoadBalancer externe, domaine personnalisé + certificat géré en option

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 ; le schéma Prisma de Cal.com cible uniquement PostgreSQL.
NEXTAUTH_SECRET et CALENDSO_ENCRYPTION_KEY sont générés automatiquement et stockés dans Secret Manager. N'effectuez jamais leur rotation après le premier démarrage sans fenêtre de maintenance — la rotation de CALENDSO_ENCRYPTION_KEY rend indéchiffrables tous les identifiants de calendrier/OAuth stockés, et celle de NEXTAUTH_SECRET invalide toutes les sessions.
L'URL publique est validée au démarrage. NEXT_PUBLIC_WEBAPP_URL / NEXTAUTH_URL prennent par défaut l'URL du service du cluster (définie à partir de GKE_SERVICE_URL à l'exécution) ; définissez webapp_url sur l'adresse du LoadBalancer externe ou sur le domaine personnalisé dès qu'elle est connue, faute de quoi les liens de réservation/OAuth seront erronés.
Le schéma est créé au démarrage, pas par un job de migration. Le job db-init se contente de provisionner la base de données et le rôle vides ; Cal.com exécute prisma migrate deploy à chaque démarrage. Prévoyez plusieurs minutes pour le premier démarrage.
Le plancher de mémoire est de 2 GiB. Cal.com (Next.js 16) plante en OOM au démarrage en dessous de 2 GiB.
L'affinité de session est ClientIP par défaut, ce qui maintient les requêtes d'un client sur le même pod pour un comportement cohérent de l'interface et des sessions.
Le sidecar Cloud SQL Auth Proxy est utilisé par défaut (enable_cloudsql_volume = true), ce qui fournit à Cal.com un point de terminaison PostgreSQL en loopback 127.0.0.1 en clair (le proxy termine le mTLS).
Redis est désactivé par défaut. Ne l'activez que pour servir de cache / de support à la limitation de débit.

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 sont indiqués dans les sorties du déploiement.

A. GKE Autopilot — la charge de travail Cal.com

Les pods Cal.com sont planifiés sur Autopilot, qui facture le CPU et la mémoire réellement demandés par les pods. L'Horizontal Pod Autoscaling dimensionne le déploiement entre le nombre minimal et le nombre maximal de réplicas.

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

CLI :

kubectl get pods,svc,hpa -n "$NAMESPACE"
kubectl logs -n "$NAMESPACE" deploy/<service-name> --tail=100
kubectl describe hpa -n "$NAMESPACE"          # current vs target utilisation

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

Cal.com stocke toutes les données applicatives (utilisateurs, types d'événements, réservations, identifiants des calendriers connectés) dans une instance gérée Cloud SQL for PostgreSQL 15. Les pods y accèdent de façon privée via le sidecar Cloud SQL Auth Proxy sur 127.0.0.1 ; aucune IP publique n'est exposée. Lors du premier déploiement, un Job d'initialisation crée la base de données et le rôle de l'application, et Cal.com applique son schéma via Prisma au démarrage.

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=<db-user> --database=<db-name> --project "$PROJECT"

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

C. Cloud Storage

Cal.com conserve tout son état dans PostgreSQL ; aucun bucket de données n'est donc créé par défaut (storage_buckets est vide). Des buckets supplémentaires peuvent toujours être déclarés via storage_buckets si des intégrations personnalisées le nécessitent.

Console : Cloud Storage → Buckets.

CLI :

gcloud storage buckets list --project "$PROJECT"

Consultez App_GKE pour les options CMEK et les montages GCS Fuse.

D. Redis (cache facultatif)

Redis est désactivé par défaut (enable_redis = false). Lorsqu'il est activé, Cal.com l'utilise comme backend de cache / de limitation de débit. Lorsque redis_host est laissé vide et que enable_nfs vaut true, l'IP de la VM du serveur NFS est utilisée comme point de terminaison Redis.

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

E. Secret Manager

Deux secrets cryptographiques sont générés automatiquement et stockés dans Secret Manager : NEXTAUTH_SECRET (signe les jetons de session NextAuth.js) et CALENDSO_ENCRYPTION_KEY (chiffre les identifiants de calendrier/OAuth stockés). 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"
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 (service_type = LoadBalancer). Un domaine personnalisé avec un certificat géré par Google peut être activé (enable_custom_domain = true par défaut), et une IP statique est réservée afin que l'adresse survive aux redéploiements. Définissez webapp_url sur l'URL externe obtenue afin que les liens de réservation/OAuth générés par Cal.com soient corrects.

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 vers Cloud Logging ; les métriques GKE et Cloud SQL vers Cloud Monitoring. Des tests de disponibilité et des règles d'alerte sont disponibles en option.

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 Cal.com

Configuration de la base de données au premier déploiement. Un Job d'initialisation exécute db-init.sh à l'aide de postgres:15-alpine. Il se connecte via le Cloud SQL Auth Proxy et crée de manière idempotente le rôle et la base de données de l'application, puis accorde les privilèges sur le schéma public. Il ne crée pas le schéma applicatif — c'est le rôle de Cal.com.
Migrations de schéma au démarrage. Le script de démarrage de l'image exécute prisma migrate deploy à chaque démarrage, créant le schéma au premier démarrage et appliquant les nouvelles migrations lors des mises à niveau de version — aucune étape de migration distincte. Prévoyez plusieurs minutes pour le premier démarrage avant que le pod ne passe à l'état Ready.
NEXTAUTH_SECRET et CALENDSO_ENCRYPTION_KEY sont immuables après le premier démarrage. Modifier CALENDSO_ENCRYPTION_KEY rend indéchiffrables tous les identifiants de calendrier/OAuth stockés (chaque intégration doit être réautorisée) ; modifier NEXTAUTH_SECRET déconnecte tous les utilisateurs. N'effectuez de rotation que lors d'une fenêtre de maintenance planifiée.
L'URL publique nécessite l'IP externe. NEXT_PUBLIC_WEBAPP_URL / NEXTAUTH_URL sont définies à partir de GKE_SERVICE_URL à l'exécution. Une fois l'IP du LoadBalancer (ou le domaine personnalisé) attribuée, définissez webapp_url sur cette adresse :
```
kubectl get svc <service-name> -n "$NAMESPACE" -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
Vous pouvez aussi définir environment_variables/webapp_url dans la configuration du module avant le déploiement.
Configuration au premier lancement. Ouvrez l'URL externe et terminez l'intégration Cal.com pour créer le compte administrateur/propriétaire initial, puis configurez au moins un calendrier connecté. Cal.com auto-hébergé autorise par défaut l'inscription en libre-service — restreignez-la (ou placez IAP devant le service) si l'instance ne doit pas être publique.
Chemin de santé. Les sondes de démarrage et de vivacité ciblent /. La fenêtre de démarrage généreuse (délai initial de 0 seconde, jusqu'à une fenêtre de 30×30s tentatives ≈ 15 minutes) absorbe les migrations Prisma du premier démarrage.

4. Variables de configuration

Les variables sont regroupées exactement comme sur la plateforme de déploiement. Seuls les paramètres propres à Cal.com ou notables pour lui sont listés ; toutes les autres entrées sont héritées d'App_GKE avec leur comportement et leurs valeurs par défaut standard.