Aller au contenu principal

Tolgee sur Google Cloud Run

Tolgee sur Google Cloud Run

Tolgee est une plateforme open source de localisation (i18n) et de gestion des traductions, pensée pour les développeurs et construite sur Spring Boot. Ce module déploie Tolgee 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 Tolgee 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 Cloud Run — identité du service, ingress 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​

Tolgee s'exécute comme un conteneur Java / Spring Boot sur Cloud Run v2. Le déploiement assemble un ensemble ciblé de services Google Cloud :

FonctionnalitéService Google CloudRemarques
CalculCloud Run v2Service Spring Boot, 2 vCPU / 4 GiB par défaut, autoscaling serverless
Base de donnéesCloud SQL for PostgreSQL 15Obligatoire — Tolgee ne prend en charge ni MySQL ni d'autres moteurs
Stockage d'objetsCloud StorageUn bucket pour le stockage de fichiers facultatif (captures d'écran/imports)
SecretsSecret ManagerMot de passe administrateur initial et secret de signature JWT générés automatiquement ; mot de passe de la base de données
IngressURL Cloud Run / Cloud Load BalancingURL run.app par défaut ; é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 ; choisir un autre moteur empêche le démarrage.
  • Tolgee se connecte à Cloud SQL en TCP, et non via un socket Unix. Son pilote JDBC PostgreSQL intégré ne peut pas utiliser de socket ; sur Cloud Run, le point d'entrée se connecte donc via l'IP privée de Cloud SQL avec sslmode=require. C'est pourquoi enable_cloudsql_volume vaut false par défaut ici (pas de sidecar socket Auth Proxy).
  • Le secret JWT est généré automatiquement et stocké dans Secret Manager. Il ne doit jamais faire l'objet d'une rotation après le premier démarrage sans fenêtre de maintenance — sa rotation invalide immédiatement toutes les sessions utilisateur actives.
  • SERVER_PORT, et non PORT. Tolgee lit SERVER_PORT = 8080 ; Cloud Run réserve PORT, c'est pourquoi le module définit explicitement SERVER_PORT.
  • min_instance_count vaut 1 et cpu_always_allocated vaut true par défaut. Tolgee exécute des opérations par lots asynchrones (traduction automatique en masse, imports, suppressions) dans des threads d'arrière-plan internes au processus, après le retour de la requête déclenchante ; une facturation à la requête les limiterait à ~0 CPU. Inversez ces deux valeurs (false + min = 0) uniquement pour un déploiement purement interactif, axé sur le coût, qui n'exécute aucun gros traitement par lots.
  • Pas de Redis. Tolgee stocke tout l'état des traductions dans PostgreSQL ; enable_redis vaut false par défaut.
  • Le schéma est créé par Liquibase au premier démarrage. Il n'y a pas de job de migration distinct — le socle crée le rôle et la base de données, et Tolgee effectue ses migrations automatiquement au démarrage.

2. Services Google Cloud et comment les explorer​

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

A. Cloud Run — le service Tolgee​

Tolgee s'exécute comme un service Cloud Run v2 qui s'adapte automatiquement à la charge de requêtes entre le nombre minimal et maximal d'instances. 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 les révisions, le trafic, les journaux et les métriques.
  • CLI : 
    gcloud run services list --project "$PROJECT" --region "$REGION"
    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​

Tolgee stocke toutes les données applicatives (projets, langues, clés, traductions, utilisateurs) dans une instance gérée Cloud SQL for PostgreSQL 15. Le service se connecte via l'IP privée de Cloud SQL (TCP, sslmode=require) plutôt que via un socket Unix, car le pilote JDBC de Tolgee ne peut pas utiliser de socket. Lors du premier déploiement, l'étape create-db-and-user.sh du socle crée la base de données et le rôle ; Tolgee exécute ensuite ses propres migrations Liquibase au démarrage.

  • Console : SQL → sélectionnez l'instance pour 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=<db-user> --database=<db-name> --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 des mots de passe.

C. Cloud Storage​

Un bucket Cloud Storage (name_suffix = "storage") est provisionné pour le stockage de fichiers facultatif — Tolgee conserve les traductions dans PostgreSQL ; ce bucket ne contient donc que les captures d'écran téléversées ou les artefacts d'import si vous le montez via gcs_volumes ou si vous configurez le stockage de fichiers compatible S3 de Tolgee.

  • Console : Cloud Storage → Buckets.
  • CLI : 
    gcloud storage buckets list --project "$PROJECT"
    gcloud storage ls gs://<bucket>/            # bucket name is in the Outputs

Consultez App_CloudRun pour les options GCS Fuse et CMEK.

D. Secret Manager​

Deux secrets sont générés automatiquement et stockés dans Secret Manager : le mot de passe administrateur initial (TOLGEE_AUTHENTICATION_INITIAL_PASSWORD), utilisé pour la première connexion, et le secret de signature JWT (TOLGEE_AUTHENTICATION_JWT_SECRET), utilisé pour signer tous les jetons de session utilisateur. 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~admin-password OR name~jwt-secret"
    gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

Consultez App_CloudRun pour les détails sur l'injection et la rotation.

E. Réseau et entrée​

Le service est joignable par défaut à son URL run.app (ingress_settings = "all"). Un équilibreur de charge HTTPS externe avec domaine personnalisé, Cloud CDN et Cloud Armor peut être ajouté ; les paramètres d'ingress et la sortie VPC contrôlent la connectivité. Comme Tolgee se connecte à Cloud SQL via l'IP privée, le service nécessite une sortie VPC (fournie par le socle).

  • 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.

F. Cloud Logging et Monitoring​

Les journaux des conteneurs sont envoyés à Cloud Logging ; les métriques Cloud Run et Cloud SQL à Cloud Monitoring, avec des tests de disponibilité et des règles d'alerte facultatifs. Le point de terminaison /actuator/health est utilisé pour le test de disponibilité provisionné lorsque le service est joignable publiquement.

  • 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 Tolgee​

  • Configuration de la base de données au premier déploiement. Aucun job d'initialisation dédié ne s'exécute — l'étape create-db-and-user.sh du socle App_CloudRun crée le rôle et la base de données PostgreSQL et accorde la propriété du schéma. Tolgee crée ensuite et migre automatiquement l'intégralité de son schéma avec Liquibase au premier démarrage.
  • Migrations au démarrage. Tolgee applique ses changesets Liquibase à chaque démarrage ; ainsi, la mise à niveau de application_version applique les changements de schéma sans étape distincte.
  • Le secret JWT est immuable après le premier démarrage. Il est généré une seule fois, écrit dans Secret Manager et maintenu stable entre les redémarrages et les instances. La rotation de TOLGEE_AUTHENTICATION_JWT_SECRET invalide immédiatement toutes les sessions utilisateur actives — n'effectuez cette rotation que pendant une fenêtre de maintenance planifiée.
  • Connexion au premier lancement. Après le déploiement, connectez-vous en tant que propriétaire initial : TOLGEE_AUTHENTICATION_INITIAL_USERNAME (par défaut admin@techequity.cloud) avec le mot de passe généré stocké dans Secret Manager. Modifiez le mot de passe et configurez des fournisseurs d'authentification supplémentaires (Google/OAuth2/SSO) depuis l'interface de Tolgee avant la mise en service.
  • Chemin de santé. Les sondes de disponibilité (readiness), de démarrage et de vivacité ciblent /actuator/health, qui ne renvoie un 200 non authentifié qu'une fois les migrations Liquibase terminées. Prévoyez plusieurs minutes au premier démarrage (délai initial de 60 secondes plus une large fenêtre d'échecs) — Spring Boot et les migrations du premier lancement démarrent plus lentement qu'une application Node typique.
  • Les opérations par lots s'exécutent en arrière-plan. La traduction automatique en masse, les imports et les suppressions s'exécutent de manière asynchrone dans des threads internes au processus après le retour de la requête, ce qui explique pourquoi cpu_always_allocated = true et min_instance_count = 1 sont les valeurs par défaut.
  • Inspectez le câblage de la base de données de la révision en cours : 
    gcloud run services describe <service-name> --region "$REGION" --project "$PROJECT" \
      --format='value(spec.template.spec.containers[0].env)'

4. Variables de configuration​

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

Groupe 3 — Identité de l'application​

VariableValeur par défautDescription
application_nametolgeeNom de base du service Cloud Run et des secrets. Ne le modifiez pas après le premier déploiement.
application_versionlatestTag de l'image Tolgee utilisé comme FROM tolgee/tolgee:<tag> pour le build du wrapper personnalisé léger. Épinglez une version (par ex. v3.130.4) en production.

Groupe 4 — Exécution et mise à l'échelle​

VariableValeur par défautDescription
deploy_applicationtrueDéfinissez false pour ne provisionner que l'infrastructure.
cpu_limit2000mCPU par instance ; 2 vCPU recommandés.
memory_limit4GiMémoire par instance. Tolgee nécessite au moins 2 GiB pour fonctionner de manière fiable.
min_instance_count1Permet aux opérations par lots asynchrones de continuer entre les requêtes. 0 (mise à zéro) est sûr pour un usage purement interactif.
max_instance_count5Plafond de coût. Doit être ≥ min_instance_count.
cpu_always_allocatedtrueMaintient le CPU alloué afin que les traitements par lots internes au processus aboutissent. Passez à false (+ min = 0) pour des déploiements uniquement interactifs, axés sur le coût.
container_port8080SERVER_PORT Spring Boot de Tolgee.
container_image_sourcecustomConstruit le wrapper léger via Cloud Build.
enable_cloudsql_volumefalseDéfini à false par défaut — le pilote JDBC de Tolgee ne peut pas utiliser de socket Cloud SQL ; il se connecte donc via l'IP privée (TCP, sslmode=require).

Groupe 5 — Contrôle d'accès et d'entrée​

VariableValeur par défautDescription
ingress_settingsallAutorise l'accès public à l'interface et à l'API de Tolgee. Restreignez-le ou placez IAP en frontal pour les déploiements privés.

Groupe 11 — Stockage et système de fichiers​

VariableValeur par défautDescription
enable_nfstrueProvisionne un NFS Cloud Filestore pour le stockage facultatif des pièces jointes de Tolgee.
gcs_volumes[]Montages de volumes GCS Fuse pour le bucket de stockage de fichiers facultatif.

Groupe 12 — Backend de base de données​

VariableValeur par défautDescription
db_nametolgeeNom de la base de données PostgreSQL. Immuable après le premier déploiement.
db_usertolgeeUtilisateur de la base de données de l'application. Mot de passe généré automatiquement dans Secret Manager.

Groupe 21 — Cache et file d'attente Redis​

VariableValeur par défautDescription
enable_redisfalseLaissez désactivé — Tolgee stocke tout son état dans PostgreSQL et n'a pas besoin de Redis.

Toutes les autres entrées suivent le comportement standard d'App_CloudRun.

5. Sorties​

Renvoyées lorsqu'un déploiement réussit — le moyen le plus rapide de localiser et d'explorer les ressources en cours d'exécution.

SortieDescription
service_nameNom du service Cloud Run.
service_urlURL run.app par défaut du service.
service_locationRégion dans laquelle s'exécute le service.
stage_servicesURL des services propres à chaque étape (Cloud Deploy).
load_balancer_ip / load_balancer_urlIP / URL de l'équilibreur de charge HTTPS externe (lorsqu'il est activé).
database_instance_nameNom de l'instance Cloud SQL.
database_name / database_userNom / utilisateur de la base de données de l'application.
database_password_secretSecret Secret Manager contenant le mot de passe de la base de données.
database_host / database_portPoint de terminaison / port de la base de données.
storage_bucketsBuckets Cloud Storage créés.
network_name / network_exists / regionsRéseau VPC, présence, régions.
container_image / container_registryImage déployée et dépôt Artifact Registry.
monitoring_enabled / monitoring_notification_channels / uptime_check_namesÉtat de la surveillance, canaux, tests de disponibilité.
initialization_jobsNoms des éventuels jobs de configuration.
deployment_id / tenant_id / resource_prefixIdentifiants de nommage.
project_id / project_numberIdentifiants du projet.
cicd_enabled / github_repository_url / github_repository_owner / github_repository_name / cicd_configurationÉtat et détails de la CI/CD.
artifact_registry_repository / cloudbuild_trigger_name / cloudbuild_trigger_idRegistre et déclencheur de build.
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_modeÉtat de VPC-SC.
audit_logging_enabled / artifact_registry_cmek_enabledÉtat de la journalisation d'audit et de CMEK.

6. Pièges de configuration et valeurs par défaut judicieuses​

Risque : Critique (perte de données / panne / sécurité) — Élevé (service dégradé) — Moyen (coût ou dégradation partielle) — Faible (mineur).

Validation héritée au moment du plan. Ce module fait passer sa configuration par le moteur du socle App_CloudRun, qui valide les valeurs et leurs combinaisons au moment du plan — un redis_port/backup_retention_days hors plage, IAP sans identités autorisées, un environnement d'exécution gen1 avec des montages NFS/GCS, un database_type qui ne correspond pas à une extension activée. Une configuration invalide fait échouer le plan avec une erreur claire et nommée avant la création de toute ressource ; la plupart des erreurs ci-dessous sont donc détectées en amont plutôt qu'à l'application ou à l'exécution.

ParamètreValeur judicieuseRisqueConséquence en cas d'erreur
TOLGEE_AUTHENTICATION_JWT_SECRET (généré automatiquement)Rotation uniquement pendant une fenêtre de maintenanceCritiqueSa rotation invalide toutes les sessions utilisateur actives et oblige tout le monde à se reconnecter immédiatement.
db_name / db_userDéfinis une seule foisCritiqueImmuables après le premier déploiement ; les renommer recrée la base de données et l'utilisateur et détruit toutes les données.
enable_cloudsql_volumefalseCritiqueLe pilote JDBC de Tolgee ne peut pas utiliser de socket Cloud SQL ; l'activer fait pointer DB_HOST vers un répertoire de socket et casse la connexion à la base de données.
memory_limit4Gi (≥ 2 GiB)ÉlevéEn dessous d'environ 2 GiB, la JVM Spring Boot tombe en OOM pendant les migrations Liquibase du premier démarrage.
application_versionÉpinglée en productionÉlevélatest peut récupérer une nouvelle version majeure avec des migrations incompatibles lors d'un redéploiement.
enable_redisfalseMoyenRedis n'est pas utilisé ; l'activer ajoute un coût sans bénéfice.
cpu_always_allocated / min_instance_counttrue / 1MoyenPasser à une facturation à la requête avec mise à zéro limite les traitements par lots asynchrones (traduction automatique en masse/imports) à ~0 CPU et les bloque.
startup_probe (/actuator/health)Conserver la large fenêtre du premier démarrageMoyenUne fenêtre trop étroite fait échouer la révision alors que les migrations Liquibase sont encore en cours sur une base neuve.
ingress_settingsall (ou IAP)MoyenLaisser l'accès public sans authentification expose l'interface et l'API de Tolgee ; le mot de passe administrateur initial doit être modifié immédiatement.

Pour le comportement du socle évoqué tout au long de ce guide — identité du service, mise à l'échelle et concurrence, ingress et équilibrage de charge, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir des images — consultez App_CloudRun. La configuration applicative propre à Tolgee, partagée avec la variante GKE, est décrite dans Tolgee_Common.

Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.

By · Google Cloud certified: ACE · PCA · PCD · PDE · PSE · CDL

Dernière mise à jour le