RAGFlow sur GKE Autopilot
RAGFlow est une plateforme open source d'intelligence documentaire et de génération augmentée par récupération (RAG). Elle ingère des PDF, des documents Word, des pages HTML et d'autres formats, les segmente et les intègre, stocke les vecteurs dans Elasticsearch, expose une API REST pour les questions-réponses, et fournit une interface utilisateur web pour la gestion des bases de connaissances et la recherche d'entreprise. Ce module déploie RAGFlow sur GKE Autopilot sur la base de la fondation App_GKE, qui provisionne et gère l'infrastructure partagée de Google Cloud et Kubernetes.
Ce guide se concentre sur les services cloud utilisés par RAGFlow 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, ingress, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, sauvegardes et cycle de vie du déploiement — reportez-vous au guide de la fondation App_GKE plutôt que de les répéter ici.
Prérequis de déploiement :
RAGFlow_GKEnécessite queElasticsearch_GKEsoit déployé en premier. La variableelasticsearch_hostsest obligatoire — le plan est rejeté si elle est vide lorsquedeploy_application = true.
Ce que coûte RAGFlow sur RAD, et comment cela se compare
L'exécution de RAGFlow dans votre propre projet Google Cloud coûte environ 229,14 $ US/mois en infrastructure, plus des frais de module uniques de 300 crédits RAD (dimensionnés à 4 vCPU / 8 Gio sur les pods GKE Autopilot). RAD facture les frais de module une seule fois, au moment du déploiement — jamais plus lors d'une mise à jour — et les builds sont inclus dans le prix ; l'utilisation de Google Cloud elle-même est facturée à votre propre compte de facturation au prix catalogue de Google. Sur un projet géré par RAD, les mêmes ressources sont mesurées à l'heure en crédits au prix catalogue plus la marge de RAD — environ 180 crédits/jour — et les frais de module sont inférieurs de 10 %, soit 270 crédits. Voir « Mettez-le en pause gratuitement » ci-dessous pour savoir comment un déploiement RAGFlow géré par RAD peut être arrêté, sans frais d'exécution, jusqu'à ce que vous en ayez à nouveau besoin. (ou voir le guide Cloud Run pour l'option moins chère)
Ce que vous payez sur RAD
| Élément | Votre propre projet | Projet géré par RAD |
|---|---|---|
| Frais de module | 300 crédits (une fois) | 270 crédits (une fois) |
| Builds | Inclus dans le prix : pas de frais de build pour la création, 5 mises à jour par mois (mois calendaire UTC) gratuites puis 2 crédits chacune, et rien pour la suppression ou pour un build échoué, dans la limite de 10 builds échoués par jour (UTC). Les sessions de lab et les projets clients sont l'exception : ils sont toujours facturés à la minute pour le temps de build | Idem |
| Coût d'exécution Google Cloud | ~229,14 $/mois, facturé à votre propre compte de facturation au prix catalogue de Google | ~180 crédits/jour, mesurés à l'heure au prix catalogue + marge de RAD |
Coût d'exécution par défaut dans votre propre projet
| Ressource | $/mois (prix catalogue Google, us-central1) |
|---|---|
| Pod GKE Autopilot, 4x vCPU / 8 Gio | 158,69 |
| Cloud SQL pour MySQL, 1 vCPU / 3,75 Go, zonal, 10 Go SSD | 51,02 |
| Serveur de fichiers NFS/cache (petite VM) | 13,43 |
| Cloud NAT et réseau | 5 |
| Cloud Storage (modules complémentaires, sauvegardes) | 1 |
| Frais de gestion de cluster GKE* | partagés entre toutes les applications GKE du projet ; 0 $ si c'est votre seul cluster, sinon ~73 |
| Total | 229,14 $ |
* Non inclus dans le total ci-dessus — il est partagé entre toutes les applications GKE exécutées dans le même projet, il est donc de 0 $ si c'est votre seul cluster GKE.
Comment cela se compare
- Nous n'avons pas pu vérifier un prix SaaS commercial actuel, directement comparable, pour ce projet open source exact, donc la comparaison honnête est un simple serveur autogéré : Hetzner CPX22 (2 vCPU/4 Go, ~24 $/mois), un Droplet DigitalOcean 2 vCPU/4 Go (~24 $/mois), ou un GCP Compute Engine e2-standard-2 (2 vCPU/8 Go, ~49 $/mois). L'empreinte propre de cette application (4+ vCPU, des dizaines de Gio de mémoire) est plus grande que n'importe laquelle de ces classes — une machine autogérée dimensionnée pour correspondre coûterait bien plus que les chiffres ci-dessous, avant de compter l'effort distinct de faire fonctionner sa propre base de données/couche de cache à la main.
- RAD ne prétend pas battre un VPS nu sur le prix affiché — ce n'est généralement pas le cas. Ce que RAD ajoute pour un montant en dollars identique ou similaire, c'est une base de données gérée, des identifiants conservés dans Secret Manager, la surveillance et une mise à jour en un clic, dont aucun n'est gratuit avec un VPS nu.
- Sur un VPS nu, c'est vous qui appliquez les correctifs de sécurité du système d'exploitation/de la base de données, effectuez et testez les sauvegardes, et renouvelez les certificats ; Cloud SQL géré, Secret Manager et la surveillance de RAD gèrent les trois pour vous.
Mettez-le en pause gratuitement : supprimez un projet géré par RAD, restaurez-le lorsque vous en avez besoin
C'est l'option phare sur un projet géré par RAD, et elle est gratuite pendant la pause. La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer le projet lui-même — la propre suppression logicielle récupérable de 30 jours de Google. Contrairement à la suppression d'un seul module, cela ne détruit pas la base de données, une VM ou la ressource de calcul une par une : l'ensemble du projet s'arrête simplement, et comme la facturation est déjà déliée, rien n'est facturé pendant qu'il attend.
Une restauration n'est pas garantie — conservez vos propres sauvegardes. Les conditions de Google Cloud ne garantissent pas qu'un projet restauré, ou les ressources qu'il contient, seront utilisables après sa restauration, de sorte que la restauration ne peut pas être considérée comme un moyen de récupérer un projet supprimé. Avant de supprimer, assurez-vous d'avoir effectué des sauvegardes appropriées des données et de la configuration de l'application et de les avoir stockées en dehors du projet. Si une restauration échoue, ou si le projet restauré ne fonctionne pas, la solution de repli consiste à redéployer l'application (voir la section suivante) et à restaurer sa configuration et ses données à partir de ces sauvegardes.
La restauration — dans les 30 jours, et uniquement par le propriétaire du projet — demande à Google de récupérer le projet et de rattacher son compte de facturation, puis vous demande d'exécuter la mise à jour sur chaque déploiement pour confirmer que tout est revenu. Comme rien n'a été détruit individuellement, cette mise à jour trouve les mêmes ressources déjà présentes : c'est une vérification, pas une reconstruction, et une mise à jour ne facture jamais les frais de module à nouveau. Les mises à jour sont incluses dans le prix (5 par mois pour chaque déploiement), donc une restauration ne coûte normalement aucun crédit. Ce qu'il faut : vous devez être propriétaire du projet (pas seulement faire gérer sa facturation par RAD), vous devez le restaurer vous-même dans les 30 jours — après quoi Google le supprime définitivement — et la restauration est admise comme la création d'un nouveau projet, de sorte que votre solde de crédits achetés doit toujours dépasser le seuil du palier (100 crédits pour le palier sandbox qui convient à la plupart des utilisations d'étude et de démonstration). Google indique que la plupart des services sont de nouveau pleinement fonctionnels dans les 36 heures suivant une restauration.
Un véritable manque : les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du projet, et ce bucket a la suppression logicielle de Cloud Storage explicitement désactivée, de sorte que le bucket de sauvegarde est très probablement supprimé dès que vous supprimez le projet — même si le projet lui-même est récupérable pendant 30 jours. Si vous avez personnalisé ce déploiement et que vous souhaitez conserver ce travail, copiez une sauvegarde (vers Google Drive, ou un bucket en dehors du projet) avant de supprimer. Pour une installation par défaut sans rien d'irremplaçable, cela n'a pas d'importance.
Payez uniquement pendant que vous l'utilisez, l'autre méthode : supprimer et redéployer
L'autre levier, pour un projet propre (ou un projet géré par RAD au-delà de sa fenêtre de restauration de 30 jours), est de supprimer RAGFlow purement et simplement et de le redéployer plus tard. Un redéploiement coûte à nouveau les frais de module (les builds sont inclus) — 300 crédits au total pour ce module.
La suppression ne permet d'économiser de l'argent que si RAGFlow reste inutilisé suffisamment longtemps pour que le coût de redéploiement soit inférieur à son propre coût d'exécution — pour ce module, cela représente environ 4 jours ou plus d'inactivité, basé sur son coût d'exécution de 229,14 $ US/mois mentionné ci-dessus. La majeure partie de ce coût d'exécution est généralement la base de données et toute VM de fichier/cache partagée, et elles ne s'arrêtent que lorsque rien d'autre dans le projet ne les utilise, donc la suppression de cette application seule n'économise que sa propre part de calcul si autre chose partage le projet.
Conservez d'abord les données : les sauvegardes nocturnes vont dans un bucket à l'intérieur du déploiement et sont supprimées avec celui-ci, donc copiez la dernière sauvegarde avant de supprimer si vous voulez la conserver.
Sessions de lab et environnements gérés
- Sessions de lab, pour la formation : un formateur anime une session pour une classe. Chaque participant dispose de l'application dans son propre projet Google Cloud pendant 15 minutes à 24 heures, dans la limite d'une allocation définie par le formateur. Le formateur peut aussi créer un seul environnement partagé pour toute la classe, et chacun utilise alors la même application et ses données. Soit le formateur finance toutes les places, soit chaque participant paie la sienne. Tout est supprimé à la fin de la session et les crédits inutilisés retournent au formateur.
- Environnements gérés, pour les sociétés de conseil : un partenaire exécute l'application pour un client à partir d'un portefeuille cloisonné qu'il finance, et règle directement avec le client. Si le portefeuille est faible, la facturation est suspendue et les données sont conservées, de sorte que personne ne reçoit de frais inattendus. À la fin, le partenaire transfère le projet et les déploiements deviennent la propriété du client.
- Les crédits peuvent être achetés dans plus de 20 devises, y compris XAF, XOF, NGN, GHS, KES et ZAR, par carte, virement bancaire ou argent mobile.
Sources (8 octobre 2026) : Prix catalogue de l'API Google Cloud Billing Catalog ; radmodules.dev/pricing pour les propres frais de RAD et les estimations de crédits quotidiens ; Resource Manager : supprimer et restaurer des projets pour les mécanismes de pause/restauration.
1. Vue d'ensemble
RAGFlow s'exécute comme une charge de travail web Python/Nginx conteneurisée. Le déploiement relie un ensemble ciblé de services Google Cloud :
| Capacité | Service Google Cloud | Notes |
|---|---|---|
| Calcul | GKE Autopilot | Pods RAGFlow personnalisés, 4 vCPU / 8 Gio par défaut, autoscalés horizontalement |
| Base de données | Cloud SQL pour MySQL 8.0 | Obligatoire — RAGFlow ne prend pas en charge PostgreSQL |
| Recherche vectorielle | Elasticsearch (Elasticsearch_GKE) | Dépendance externe — doit être déployé en premier ; elasticsearch_hosts est obligatoire |
| File d'attente de tâches | Redis (Memorystore) | Obligatoire pour les workers de traitement de documents |
| Fichiers partagés | Filestore (NFS) | Activé par défaut pour le stockage partagé de traitement de documents |
| Stockage d'objets | MinIO (dans l'espace de noms) | RAGFlow stocke chaque document téléchargé dans un stockage compatible S3, un bucket par base de connaissances. enable_inline_minio = true (par défaut) exécute un service MinIO supplémentaire à réplica unique sur un PVC de 20 Gio standard ; définissez minio_host pour utiliser un point de terminaison S3 externe à la place. Un bucket Cloud Storage documents est également provisionné |
| Secrets | Secret Manager | Mot de passe de base de données auto-généré |
| Ingress | Cloud Load Balancing | Service External LoadBalancer ; domaine personnalisé facultatif + certificat géré |
Valeurs par défaut judicieuses à connaître d'emblée :
- MySQL 8.0 est obligatoire. Le moteur de base de données est fixe ; la sélection de PostgreSQL ou
NONEinterrompt le démarrage. elasticsearch_hostsest requis. RAGFlow ne peut pas indexer ou rechercher des documents sans un point de terminaison Elasticsearch accessible. DéployezElasticsearch_GKEen premier.- Le stockage de documents est un MinIO dans l'espace de noms par défaut. RAGFlow conserve les documents téléchargés
dans un stockage compatible S3, créant un bucket par base de connaissances, donc
enable_inline_minio = truedéploie un service MinIO à réplica unique avec un volume persistant (minio_storage_size20 Gio,minio_storage_classstandard). Ses identifiants sont un mot de passe généré dans Secret Manager. Sans stockage d'objets, chaque analyse de document échoue tandis que le pod reste Ready. - Redis est requis pour le traitement des documents. Avec
enable_redis = true(par défaut),REDIS_HOSTetREDIS_PORTsont injectés automatiquement. Sans Redis, les fichiers téléchargés restent non traités indéfiniment. - La mise à l'échelle à zéro est désactivée.
min_instance_countest plafonné à 1. RAGFlow charge les modèles d'intégration au démarrage (2 à 3 minutes) ; la mise à l'échelle à zéro entraînerait l'expiration des requêtes. - Une image personnalisée est toujours construite. Cloud Build étend
infiniflow/ragflowen utilisant le Dockerfile dansRAGFlow_Common/scripts/, avecAPP_VERSIONdéfini à partir deapplication_version. service_conf.yamlest généré au démarrage. Le point d'entrée personnalisé écrit/ragflow/conf/service_conf.yamlà partir de variables d'environnement injectées avant de démarrer les processus RAGFlow.- L'affinité de session est
ClientIP. Cela garantit que les sessions de téléchargement et les requêtes de traitement de documents en plusieurs étapes atteignent toujours le même pod. enable_custom_domainpar défaut àtrue. Cela achemine le service via l'équilibreur de charge de l'API Gateway, qui — combiné avec lereserve_static_ip = truepar défaut — provisionne un certificat géré et HTTPS prêt à l'emploi via un nom d'hôte<ip>.nip.iomême lorsqueapplication_domainsest laissé vide. Définissezapplication_domainspour servir un vrai nom d'hôte à la place.- Le mot de passe de la base de données est généré automatiquement et stocké dans Secret Manager.
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 rapportés dans les Sorties du déploiement.
A. GKE Autopilot — la charge de travail RAGFlow
Les pods RAGFlow sont planifiés sur Autopilot, qui facture le CPU/la mémoire que les pods demandent réellement. L'autoscaling horizontal des pods dimensionne le déploiement entre les nombres de réplicas minimum et maximum.
- Console : Kubernetes Engine → Charges de travail → sélectionnez la charge de travail RAGFlow pour voir les pods, les révisions et les événements. Kubernetes Engine → Services et Ingress affiche l'adresse 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
Voir App_GKE pour la gestion d'Autopilot, de la mise à l'échelle et du type de charge de travail (Deployment vs StatefulSet).
B. Cloud SQL pour MySQL 8.0
RAGFlow stocke toutes les métadonnées de l'application (comptes utilisateurs, bases de connaissances, état des tâches) dans une instance Cloud SQL pour MySQL 8.0 gérée. Les pods y accèdent en privé via le sidecar Cloud SQL Auth Proxy via un socket Unix, de sorte qu'aucune IP publique n'est exposée. Lors du premier déploiement, un Job d'initialisation crée la base de données et l'utilisateur de l'application.
- Console : SQL → sélectionnez l'instance pour les connexions, les sauvegardes, les indicateurs 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> --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 sont tous affichés dans les Sorties. Pour le modèle de connexion, les sauvegardes automatisées et la rotation des mots de passe, voir App_GKE.
C. Elasticsearch — recherche vectorielle
RAGFlow nécessite une instance Elasticsearch externe pour l'indexation de documents et la recherche vectorielle.
Elle n'est pas incluse dans ce module — déployez Elasticsearch_GKE séparément et
passez sa sortie elasticsearch_endpoint comme elasticsearch_hosts. Les variables d'environnement
ELASTICSEARCH_HOSTS et ELASTICSEARCH_USERNAME sont injectées
automatiquement.
- Console : Kubernetes Engine → Charges de travail → espace de noms Elasticsearch.
- CLI :
# Confirm RAGFlow can reach Elasticsearch:
kubectl exec -n "$NAMESPACE" deploy/<service-name> -- \
curl -s "$ELASTICSEARCH_HOSTS/_cluster/health" | grep status
# Check connectivity from within the cluster:
kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
curl -s "http://<elasticsearch-ip>:9200/_cluster/health"
D. Redis — file d'attente de tâches
Redis est l'épine dorsale du pipeline de traitement de documents de RAGFlow. Les workers interrogent Redis pour les tâches ; sans lui, les fichiers téléchargés ne sont jamais analysés, segmentés ou intégrés.
- Console : Memorystore → Redis (si vous utilisez une instance gérée).
- CLI :
redis-cli -h <redis-host> ping # from a host with network access
redis-cli -h <redis-host> info keyspace
E. Filestore (NFS) et Cloud Storage
Par défaut, RAGFlow monte un partage Filestore (NFS) dans chaque pod pour le stockage partagé
de traitement de documents. Un bucket Cloud Storage dédié (ragflow-documents)
est également provisionné pour l'ingestion de documents ; le compte de service de la charge de travail se voit accorder
un accès automatique. Des volumes GCS Fuse supplémentaires peuvent être montés via gcs_volumes.
- Console : Filestore → Instances ; Cloud Storage → Buckets.
- CLI :
gcloud filestore instances list --project "$PROJECT"
gcloud storage buckets list --project "$PROJECT"
gcloud storage ls gs://<documents-bucket>/ # bucket name is in the Outputs
# Confirm the NFS share is mounted inside a pod:
kubectl exec -n "$NAMESPACE" deploy/<service-name> -- df -h | grep -i nfs
Voir App_GKE pour le provisionnement NFS, GCS Fuse et les options CMEK.
F. Secret Manager
Le mot de passe de la base de données est stocké en tant que secret Secret Manager et injecté dans les pods au moment de l'exécution ; le texte en clair n'apparaît jamais dans la configuration.
- Console : Sécurité → 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 se trouve dans les Sorties. Voir App_GKE pour l'intégration et la rotation de Secret Store CSI.
G. Réseau et ingress
enable_custom_domain par défaut à true, qui achemine la charge de travail via l'équilibreur de charge de l'API Gateway avec un certificat géré par Google — servant automatiquement
HTTPS sur un nom d'hôte <ip>.nip.io lorsque application_domains est vide. Définissez
application_domains pour servir un vrai nom d'hôte personnalisé à la place. Une IP statique est réservée
par défaut afin que l'adresse survive aux redéploiements.
- Console : Services réseau → Équilibrage de charge ; Réseau VPC → Adresses IP.
- CLI :
kubectl get ingress,svc -n "$NAMESPACE"
gcloud compute addresses list --project "$PROJECT"
Voir App_GKE pour les domaines personnalisés, Cloud CDN et les détails de l'IP statique.
H. Cloud Logging et Monitoring
Les sorties stdout/stderr des pods sont acheminées vers Cloud Logging ; les métriques GKE et Cloud SQL sont acheminées vers Cloud Monitoring. Des tests de disponibilité et des stratégies d'alerte facultatifs sont disponibles.
- Console : Logging → Explorateur de journaux ; Monitoring → Tableaux de bord / Alertes.
- CLI :
gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="'"$NAMESPACE"'"' \
--project "$PROJECT" --limit 50
3. Comportement de l'application RAGFlow
- Configuration de la base de données au premier déploiement. Un Job d'initialisation (
mysql:8.0-debian) crée la base de données RAGFlow (rag_flow) et l'utilisateur (ragflow) et accorde les privilèges avant le démarrage de l'application. Il est idempotent et peut être réexécuté en toute sécurité. service_conf.yamlgénéré au démarrage. Le point d'entrée personnalisé génère/ragflow/conf/service_conf.yamlà partir de variables d'environnement injectées — y compris l'hôte/utilisateur/base de données MySQL, le point de terminaison Elasticsearch, l'hôte/port Redis et les identifiants facultatifs — avant de démarrer les processus RAGFlow (serveur Nginx, serveur RAGFlow, workers de tâches).- Pipeline de traitement de documents. Les documents téléchargés sont mis en file d'attente dans Redis et traités de manière asynchrone par les workers de documents de RAGFlow : OCR, segmentation, intégration et indexation dans Elasticsearch. Sans Redis et Elasticsearch accessibles, les fichiers apparaissent téléchargés mais ne sont jamais traités.
- Chargement du modèle d'intégration au démarrage. RAGFlow télécharge et charge les modèles d'intégration
lors du premier démarrage. La sonde de démarrage cible
/v1/healthavec un délai initial de 120 secondes et 60 tentatives d'échec pour laisser amplement le temps. La vivacité passe à/v1/healthune fois le démarrage réussi. - Points de terminaison de santé. Les sondes de disponibilité et de vivacité utilisent
/v1/healthet/v1/system/version. Celles-ci renvoient HTTP 200 uniquement lorsque l'application est entièrement initialisée et que tous les services sont accessibles. - Affinité de session.
session_affinity = "ClientIP"achemine les requêtes d'un navigateur vers le même pod, garantissant que les sessions de téléchargement et les workflows de documents en cours restent cohérents.
4. Variables de configuration
Les variables sont regroupées exactement comme elles apparaissent sur la plateforme de déploiement. Seuls les paramètres spécifiques ou notables pour RAGFlow sont listés ; toutes les autres entrées sont héritées de App_GKE avec son comportement et ses valeurs par défaut standard.
Groupe 1 — Projet et identité
| Variable | Valeur par défaut | Description |
|---|---|---|
project_id | (obligatoire) | Projet Google Cloud cible. |
region | us-central1 | Région pour la charge de travail et les ressources régionales. |
elasticsearch_hosts | (obligatoire) | Point de terminaison HTTP Elasticsearch (par exemple http://10.0.0.5:9200). Définir sur la sortie elasticsearch_endpoint de Elasticsearch_GKE. |
Groupe 2 — Environnement de déploiement
| Variable | Valeur par défaut | Description |
|---|---|---|
tenant_id | demo | Suffixe court qui rend les noms de ressources uniques par environnement. |
support_users | [] | Adresses e-mail autorisées à accéder au projet et aux alertes de surveillance. |
resource_labels | {} | Étiquettes appliquées à toutes les ressources pour le suivi des coûts/propriétés. |
Groupe 3 — Identité de l'application
| Variable | Valeur par défaut | Description |
|---|---|---|
application_name | ragflow | Nom de base des ressources. Ne pas modifier après le premier déploiement. |
application_display_name | RAGFlow | Nom convivial affiché dans la console. |
application_description / description | (défini) | Annotation de description de la charge de travail. |
application_version | v0.13.0 | Tag de version de l'image RAGFlow passé comme APP_VERSION à Cloud Build ; incrémenter pour déployer une nouvelle version. |
Groupe 4 — Exécution et mise à l'échelle
| Variable | Valeur par défaut | Description |
|---|---|---|
deploy_application | true | Définir false pour provisionner uniquement l'infrastructure. |
cpu_limit | 4000m | CPU par pod ; 4 vCPU recommandés pour les charges de travail d'analyse de documents. |
memory_limit | 8Gi | Mémoire par pod ; 8 Gio recommandés (les modèles d'intégration sont volumineux). |
min_instance_count | 1 | Réplicas minimum. Plafonné à 1 — la mise à l'échelle à zéro n'est pas prise en charge. |
max_instance_count | 5 | Réplicas maximum (plafond de l'autoscaler). |
container_port | 80 | Le frontend Nginx de RAGFlow écoute sur le port 80. |
enable_cloudsql_volume | true | Sidecar Cloud SQL Auth Proxy pour les connexions socket. |
termination_grace_period_seconds | 60 | Augmenter pour les jobs de traitement de documents en cours. |
deployment_timeout | 1800 | Secondes pendant lesquelles Terraform attend le déploiement — généreux pour tenir compte du chargement du modèle. |
enable_vertical_pod_autoscaling | false | Laisser Autopilot ajuster automatiquement les requêtes de ressources. |
Groupe 5 — Variables d'environnement et secrets
| Variable | Valeur par défaut | Description |
|---|---|---|
environment_variables | {} | Paramètres supplémentaires non secrets. Ne pas écraser MYSQL_*, ELASTICSEARCH_* ou REDIS_* — ceux-ci sont injectés automatiquement. |
secret_environment_variables | {} | Mappage de variable d'environnement → nom de secret Secret Manager. |
Groupe 6 — Backend GKE et cluster
| Variable | Valeur par défaut | Description |
|---|---|---|
service_type | LoadBalancer | Comment le service est exposé. |
session_affinity | ClientIP | Routage persistant — requis pour des sessions de téléchargement et un traitement de documents cohérents. |
workload_type | null | Se résout automatiquement en StatefulSet lorsque le stockage par pod est activé. |
network_tags | ["nfsserver"] | Tags de nœud/pod ; nfsserver est requis pour la connectivité NFS. |
Groupe 7 — Configuration du StatefulSet
Ces paramètres s'appliquent uniquement lorsque workload_type = "StatefulSet" ou stateful_pvc_enabled = true.
| Variable | Valeur par défaut | Description |
|---|---|---|
stateful_pvc_enabled | null | Provisionner un PVC pour le stockage local du modèle. Recommandé pour la production. |
stateful_pvc_size | 10Gi | Taille du PVC ; provisionner au moins 50 Gio pour les charges de travail de documents en production. |
stateful_pvc_mount_path | /data | Chemin de montage du conteneur pour le PVC. |
stateful_pvc_storage_class | standard-rwo | Kubernetes StorageClass pour les PVC. |
stateful_fs_group | 0 | GID fsGroup pour la propriété du PVC ; définir si le processus du conteneur nécessite un GID spécifique. |
Groupe 8 — Quota de ressources
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_resource_quota | false | Plafonner les comptes de CPU/mémoire/objets de l'espace de noms. |
quota_memory_requests / quota_memory_limits | "" | Doit utiliser des unités binaires (8Gi, 16384Mi) — les entiers bruts sont lus comme des octets et bloquent la planification. |
Groupe 9 — Politiques de fiabilité
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_pod_disruption_budget | true | Protéger la disponibilité pendant les mises à niveau de nœuds. |
pdb_min_available | 1 | Augmenter min_instance_count au-dessus de 1 si vous avez besoin d'une marge d'éviction. |
enable_topology_spread | false | Répartir les pods sur plusieurs zones. |
Groupe 10 — Observabilité et santé
| Variable | Valeur par défaut | Description |
|---|---|---|
startup_probe / startup_probe_config | /v1/health, délai de 120 s, 60 tentatives | Sonde HTTP laissant amplement le temps pour le chargement du modèle d'intégration. |
liveness_probe / health_check_config | /v1/health | Sonde de vivacité HTTP une fois le démarrage réussi. |
uptime_check_config | { enabled=false, path="/v1/health" } | Test de disponibilité Cloud Monitoring facultatif ; désactivé par défaut. |
alert_policies | [] | Stratégies d'alerte métrique facultatives. |
Groupe 11 — Jobs et tâches planifiées
| Variable | Valeur par défaut | Description |
|---|---|---|
initialization_jobs | [] | Laisser vide pour utiliser le job db-init intégré. |
cron_jobs | [] | Tâches planifiées récurrentes déployées en tant que CronJobs Kubernetes. |
additional_services | [] | Déploiements Kubernetes compagnons supplémentaires (par exemple, Elasticsearch intégré pour le développement). |
Groupe 12 — CI/CD et intégration GitHub
Intégration standard App_GKE Cloud Build / Cloud Deploy — voir
App_GKE. Entrées clés : enable_cicd_trigger,
github_repository_url, github_token, enable_cloud_deploy.
Groupe 13 — Système de fichiers (NFS)
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_nfs | true | Volume Filestore partagé pour le stockage de traitement de documents (garder activé pour les réplicas multiples). |
nfs_mount_path | /mnt/nfs | Chemin de montage à l'intérieur du conteneur. |
nfs_instance_name | "" | Nom d'une VM NFS GCE existante ; découverte automatique si vide. |
Groupe 14 — Cloud Storage et Artifact Registry
| Variable | Valeur par défaut | Description |
|---|---|---|
create_cloud_storage | true | Provisionner le bucket de documents GCS. |
storage_buckets | [{ name_suffix="data" }] | Buckets GCS supplémentaires au-delà de ragflow-documents. |
gcs_volumes | [] | Volumes GCS Fuse montés dans le conteneur RAGFlow. |
manage_storage_kms_iam / enable_artifact_registry_cmek | false | Options de chiffrement CMEK. |
max_images_to_retain | 7 | Nombre maximal d'images Artifact Registry récentes à conserver. |
Groupe 15 — Elasticsearch et Redis
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_redis | true | Utiliser Redis pour la file d'attente de tâches de traitement de documents. |
redis_host | "" | Hôte Redis. Si vide et que NFS est activé, l'IP du serveur NFS est utilisée. Définir explicitement pour Memorystore. |
redis_port | 6379 | Port Redis. |
redis_auth | "" | Mot de passe d'authentification Redis facultatif (sensible). |
elasticsearch_username | "" | Nom d'utilisateur Elasticsearch. Laisser vide lorsque xpack.security.enabled = false. |
enable_inline_elasticsearch | false | Déployer un sidecar Elasticsearch à nœud unique. Développement uniquement — les données sont perdues au redémarrage du pod. |
elasticsearch_version | 8.13.0 | Tag d'image Elasticsearch pour l'instance intégrée. |
Groupe 16 — Backend de base de données
| Variable | Valeur par défaut | Description |
|---|---|---|
database_type | MYSQL_8_0 | Fixe — ne pas modifier. |
db_name | rag_flow | Nom de la base de données. Immuable après le premier déploiement. |
db_user | ragflow | Utilisateur de l'application. Immuable après le premier déploiement. |
database_password_length | 32 | Longueur du mot de passe généré (16–64). |
enable_auto_password_rotation | false | Rotation du mot de passe de la base de données sans interruption. |
Groupe 17 — Sauvegarde et maintenance
| Variable | Valeur par défaut | Description |
|---|---|---|
backup_schedule | 0 2 * * * | Cron de sauvegarde automatisée (UTC). |
backup_retention_days | 7 | Rétention ; augmenter à 30–90 pour la production/conformité. |
enable_backup_import / backup_source / backup_uri | options de restauration | Restaurer à partir d'une sauvegarde lors du déploiement. |
Groupe 18 — Scripts SQL personnalisés
enable_custom_sql_scripts, custom_sql_scripts_bucket, custom_sql_scripts_path,
custom_sql_scripts_use_root — exécuter du SQL à partir d'un bucket GCS après le provisionnement. Voir
App_GKE.
Groupe 19 — Domaine personnalisé, IP statique et réseau
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_custom_domain | true | Provisionner Ingress pour les noms d'hôtes personnalisés + certificat géré. |
application_domains | [] | Noms d'hôtes à servir. |
reserve_static_ip | true | IP externe stable sur les redéploiements. |
network_tags | ["nfsserver"] | Tags réseau GCP appliqués aux pods. |
Groupe 20 — Identity-Aware Proxy (IAP)
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_iap | false | Exiger la connexion Google devant RAGFlow. |
iap_authorized_users / iap_authorized_groups | [] | Qui peut accéder. |
iap_oauth_client_id / iap_oauth_client_secret | "" | Requis lorsque IAP est activé (sensible). |
iap_support_email | "" | Affiché sur l'écran de consentement OAuth. |
Groupe 21 — Cloud Armor
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_cloud_armor | false | Attacher une politique Cloud Armor (WAF) au backend Ingress. |
admin_ip_ranges | [] | CIDR autorisés à un accès privilégié. |
cloud_armor_policy_name | default-waf-policy | Nom de la politique. |
Groupe 22 — VPC Service Controls et journalisation d'audit
| Variable | Valeur par défaut | Description |
|---|---|---|
enable_vpc_sc | false | Appliquer un périmètre VPC-SC (nécessite organization_id). |
vpc_cidr_ranges / vpc_sc_dry_run | (défini) | CIDR de niveau d'accès / mode simulation. |
enable_audit_logging | false | Journaux d'audit Cloud détaillés. |
5. Sorties
Ces valeurs sont renvoyées lors d'un déploiement réussi et constituent le moyen le plus rapide de localiser et d'explorer les ressources en cours d'exécution.
| Sortie | Description |
|---|---|
service_name | Nom du service Kubernetes. |
namespace | Espace de noms dans lequel la charge de travail s'exécute. |
service_cluster_ip | ClusterIP intra-cluster. |
stage_service_cluster_ips | Mappage des ClusterIP pour les services spécifiques à chaque étape (Cloud Deploy). |
service_external_ip | IP externe du LoadBalancer (lorsqu'une IP statique est réservée). |
service_url | URL pour atteindre RAGFlow. |
database_instance_name | Nom de l'instance Cloud SQL. |
database_name | Nom de la base de données de l'application. |
database_user | Utilisateur de la base de données de l'application. |
database_password_secret | Secret Manager secret contenant le mot de passe de la base de données. |
database_host / database_port | Point de terminaison de la base de données (127.0.0.1 via le proxy d'authentification) / port. |
storage_buckets | Buckets Cloud Storage créés. |
network_name / network_exists / regions | Réseau VPC, présence, régions disponibles. |
container_image / container_registry | Image déployée et dépôt Artifact Registry. |
monitoring_enabled / monitoring_notification_channels | Statut et canaux de surveillance. |
initialization_jobs / db_import_job | Noms des jobs de configuration et d'importation (facultatif). |
deployment_id / tenant_id / resource_prefix | Identifiants de nommage. |
project_id / project_number | Identifiants du projet. |
cicd_enabled / cicd_configuration | Statut et détails CI/CD. |
github_repository_url / github_repository_owner / github_repository_name | Détails du dépôt connecté. |
artifact_registry_repository / cloudbuild_trigger_name / cloudbuild_trigger_id | Registre et déclencheur de build. |
kubernetes_ready | Indique si le cluster/la charge de travail est prêt(e). false lors du premier apply d'un nouveau cluster intégré — le pipeline CI/CD doit relancer l'apply pour terminer le déploiement. |
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_mode | Statut VPC-SC. |
audit_logging_enabled / artifact_registry_cmek_enabled | Journalisation d'audit et statut 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).
| Paramètre | Valeur judicieuse | Risque | Conséquence si incorrect |
|---|---|---|---|
elasticsearch_hosts | requis — défini à partir de Elasticsearch_GKE | Critique | RAGFlow ne peut pas indexer ou rechercher ; toutes les opérations d'ingestion et de récupération échouent. Le plan est rejeté si vide et deploy_application = true. |
enable_redis | true | Critique | Sans Redis, la file d'attente des tâches de traitement de documents ne s'exécute jamais ; les fichiers téléchargés restent non traités indéfiniment. |
database_type | MYSQL_8_0 | Critique | RAGFlow nécessite MySQL ; PostgreSQL/NONE provoque un échec au démarrage. |
enable_cloudsql_volume | true | Critique | RAGFlow se connecte via un socket Unix ; la désactivation du sidecar proxy entraîne un échec de connexion à la base de données au démarrage. |
db_name / db_user | défini une fois | Critique | Immuable après le premier déploiement ; le renommage recrée la base de données/l'utilisateur et détruit les données. |
enable_backup_import | false sauf restauration | Critique | L'activation sans backup_uri valide échoue le job d'importation. |
quota_memory_requests / _limits | unités binaires | Critique | Les entiers bruts sont des octets et bloquent toute planification. |
redis_host | IP Memorystore explicite ou "" (repli NFS) | Élevé | Un hôte Redis inaccessible ou incorrect interrompt silencieusement tous les workers de documents asynchrones. |
min_instance_count | 1 | Élevé | 0 provoque une mise à l'échelle à zéro ; les démarrages à froid prennent 2 à 3 minutes et les requêtes expirent. |
memory_limit | 8Gi | Élevé | Les modèles d'intégration et le serveur d'application nécessitent généralement 4 à 8 Gio ; trop peu provoque des arrêts OOM pendant le traitement des documents. |
stateful_pvc_enabled | true pour la production | Élevé | Sans PVC, les redémarrages de pod perdent tout état de traitement en cours. |
session_affinity | ClientIP | Élevé | Sans persistance de session, les sessions de téléchargement multi-réplicas peuvent être réparties entre les pods. |
elasticsearch_username | "" ou utilisateur correct | Élevé | Si la sécurité Elasticsearch est activée, laisser ce champ vide provoque une erreur HTTP 401 et interrompt toute indexation. |
enable_nfs | true | Élevé | Les déploiements multi-réplicas sans stockage partagé présentent des vues de documents incohérentes entre les pods. |
enable_iap / enable_cloud_armor | activer pour la production | Moyen | L'interface utilisateur web de RAGFlow est autrement accessible publiquement. |
backup_retention_days | 7 (augmenter pour la production) | Moyen | Trop court pour la rétention de conformité. |
pdb_min_available vs min_instance_count | laisser de la marge | Moyen | 1/1 peut bloquer les mises à niveau de nœuds (un seul pod ne peut pas être expulsé). |
application_version | v0.13.0 | Moyen | L'incrémentation déclenche une reconstruction d'image et un redémarrage progressif ; vérifier la compatibilité du schéma MySQL pour les sauts de version majeure. |
Pour le comportement de base référencé partout — IAM et Workload Identity, autoscaling, ingress et certificats, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, sauvegardes et mise en miroir d'images — voir App_GKE. La configuration d'application spécifique à RAGFlow partagée avec la variante Cloud Run est décrite dans RAGFlow_Common.
Guides associés
- Lab pratique : RAGFlow sur GKE Autopilot — déployez-le étape par étape, avec les écrans de la console et les commandes à chaque étape.
- RAGFlow sur Google Cloud Run — la même application sur Cloud Run, lorsque vous avez besoin de l'autre cible de déploiement.
- RAGFlow Common — Configuration d'application partagée — la configuration partagée par les deux cibles de déploiement.
- Déployé aux côtés de Elasticsearch sur GKE Autopilot, Qdrant sur Google Cloud Run, Paperless-ngx sur Google Cloud Run, Crawl4AI sur Google Cloud Run dans la solution RAG d'entreprise et intelligence documentaire.
Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.