Aller au contenu principal

RAGFlow sur GKE Autopilot

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_GKE nécessite que Elasticsearch_GKE soit déployé en premier. La variable elasticsearch_hosts est obligatoire — le plan est rejeté si elle est vide lorsque deploy_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émentVotre propre projetProjet géré par RAD
Frais de module300 crédits (une fois)270 crédits (une fois)
BuildsInclus 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 buildIdem
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 Gio158,69
Cloud SQL pour MySQL, 1 vCPU / 3,75 Go, zonal, 10 Go SSD51,02
Serveur de fichiers NFS/cache (petite VM)13,43
Cloud NAT et réseau5
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
Total229,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 CloudNotes
CalculGKE AutopilotPods RAGFlow personnalisés, 4 vCPU / 8 Gio par défaut, autoscalés horizontalement
Base de donnéesCloud SQL pour MySQL 8.0Obligatoire — RAGFlow ne prend pas en charge PostgreSQL
Recherche vectorielleElasticsearch (Elasticsearch_GKE)Dépendance externe — doit être déployé en premier ; elasticsearch_hosts est obligatoire
File d'attente de tâchesRedis (Memorystore)Obligatoire pour les workers de traitement de documents
Fichiers partagésFilestore (NFS)Activé par défaut pour le stockage partagé de traitement de documents
Stockage d'objetsMinIO (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é
SecretsSecret ManagerMot de passe de base de données auto-généré
IngressCloud Load BalancingService 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 NONE interrompt le démarrage.
  • elasticsearch_hosts est requis. RAGFlow ne peut pas indexer ou rechercher des documents sans un point de terminaison Elasticsearch accessible. Déployez Elasticsearch_GKE en 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 = true déploie un service MinIO à réplica unique avec un volume persistant (minio_storage_size 20 Gio, minio_storage_class standard). 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_HOST et REDIS_PORT sont 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_count est 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/ragflow en utilisant le Dockerfile dans RAGFlow_Common/scripts/, avec APP_VERSION défini à partir de application_version.
  • service_conf.yaml est 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_domain par défaut à true. Cela achemine le service via l'équilibreur de charge de l'API Gateway, qui — combiné avec le reserve_static_ip = true par défaut — provisionne un certificat géré et HTTPS prêt à l'emploi via un nom d'hôte <ip>.nip.io même lorsque application_domains est laissé vide. Définissez application_domains pour 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.

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.yaml gé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/health avec un délai initial de 120 secondes et 60 tentatives d'échec pour laisser amplement le temps. La vivacité passe à /v1/health une fois le démarrage réussi.
  • Points de terminaison de santé. Les sondes de disponibilité et de vivacité utilisent /v1/health et /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é​

VariableValeur par défautDescription
project_id(obligatoire)Projet Google Cloud cible.
regionus-central1Ré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​

VariableValeur par défautDescription
tenant_iddemoSuffixe 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​

VariableValeur par défautDescription
application_nameragflowNom de base des ressources. Ne pas modifier après le premier déploiement.
application_display_nameRAGFlowNom convivial affiché dans la console.
application_description / description(défini)Annotation de description de la charge de travail.
application_versionv0.13.0Tag 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​

VariableValeur par défautDescription
deploy_applicationtrueDéfinir false pour provisionner uniquement l'infrastructure.
cpu_limit4000mCPU par pod ; 4 vCPU recommandés pour les charges de travail d'analyse de documents.
memory_limit8GiMémoire par pod ; 8 Gio recommandés (les modèles d'intégration sont volumineux).
min_instance_count1Réplicas minimum. Plafonné à 1 — la mise à l'échelle à zéro n'est pas prise en charge.
max_instance_count5Réplicas maximum (plafond de l'autoscaler).
container_port80Le frontend Nginx de RAGFlow écoute sur le port 80.
enable_cloudsql_volumetrueSidecar Cloud SQL Auth Proxy pour les connexions socket.
termination_grace_period_seconds60Augmenter pour les jobs de traitement de documents en cours.
deployment_timeout1800Secondes pendant lesquelles Terraform attend le déploiement — généreux pour tenir compte du chargement du modèle.
enable_vertical_pod_autoscalingfalseLaisser Autopilot ajuster automatiquement les requêtes de ressources.

Groupe 5 — Variables d'environnement et secrets​

VariableValeur par défautDescription
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​

VariableValeur par défautDescription
service_typeLoadBalancerComment le service est exposé.
session_affinityClientIPRoutage persistant — requis pour des sessions de téléchargement et un traitement de documents cohérents.
workload_typenullSe 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.

VariableValeur par défautDescription
stateful_pvc_enablednullProvisionner un PVC pour le stockage local du modèle. Recommandé pour la production.
stateful_pvc_size10GiTaille du PVC ; provisionner au moins 50 Gio pour les charges de travail de documents en production.
stateful_pvc_mount_path/dataChemin de montage du conteneur pour le PVC.
stateful_pvc_storage_classstandard-rwoKubernetes StorageClass pour les PVC.
stateful_fs_group0GID 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​

VariableValeur par défautDescription
enable_resource_quotafalsePlafonner 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é​

VariableValeur par défautDescription
enable_pod_disruption_budgettrueProtéger la disponibilité pendant les mises à niveau de nœuds.
pdb_min_available1Augmenter min_instance_count au-dessus de 1 si vous avez besoin d'une marge d'éviction.
enable_topology_spreadfalseRépartir les pods sur plusieurs zones.

Groupe 10 — Observabilité et santé​

VariableValeur par défautDescription
startup_probe / startup_probe_config/v1/health, délai de 120 s, 60 tentativesSonde HTTP laissant amplement le temps pour le chargement du modèle d'intégration.
liveness_probe / health_check_config/v1/healthSonde 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​

VariableValeur par défautDescription
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)​

VariableValeur par défautDescription
enable_nfstrueVolume Filestore partagé pour le stockage de traitement de documents (garder activé pour les réplicas multiples).
nfs_mount_path/mnt/nfsChemin 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​

VariableValeur par défautDescription
create_cloud_storagetrueProvisionner 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_cmekfalseOptions de chiffrement CMEK.
max_images_to_retain7Nombre maximal d'images Artifact Registry récentes à conserver.

Groupe 15 — Elasticsearch et Redis​

VariableValeur par défautDescription
enable_redistrueUtiliser 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_port6379Port 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_elasticsearchfalseDéployer un sidecar Elasticsearch à nœud unique. Développement uniquement — les données sont perdues au redémarrage du pod.
elasticsearch_version8.13.0Tag d'image Elasticsearch pour l'instance intégrée.

Groupe 16 — Backend de base de données​

VariableValeur par défautDescription
database_typeMYSQL_8_0Fixe — ne pas modifier.
db_namerag_flowNom de la base de données. Immuable après le premier déploiement.
db_userragflowUtilisateur de l'application. Immuable après le premier déploiement.
database_password_length32Longueur du mot de passe généré (16–64).
enable_auto_password_rotationfalseRotation du mot de passe de la base de données sans interruption.

Groupe 17 — Sauvegarde et maintenance​

VariableValeur par défautDescription
backup_schedule0 2 * * *Cron de sauvegarde automatisée (UTC).
backup_retention_days7Rétention ; augmenter à 30–90 pour la production/conformité.
enable_backup_import / backup_source / backup_urioptions de restaurationRestaurer à 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​

VariableValeur par défautDescription
enable_custom_domaintrueProvisionner Ingress pour les noms d'hôtes personnalisés + certificat géré.
application_domains[]Noms d'hôtes à servir.
reserve_static_iptrueIP externe stable sur les redéploiements.
network_tags["nfsserver"]Tags réseau GCP appliqués aux pods.

Groupe 20 — Identity-Aware Proxy (IAP)​

VariableValeur par défautDescription
enable_iapfalseExiger 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​

VariableValeur par défautDescription
enable_cloud_armorfalseAttacher une politique Cloud Armor (WAF) au backend Ingress.
admin_ip_ranges[]CIDR autorisés à un accès privilégié.
cloud_armor_policy_namedefault-waf-policyNom de la politique.

Groupe 22 — VPC Service Controls et journalisation d'audit​

VariableValeur par défautDescription
enable_vpc_scfalseAppliquer 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_loggingfalseJournaux 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.

SortieDescription
service_nameNom du service Kubernetes.
namespaceEspace de noms dans lequel la charge de travail s'exécute.
service_cluster_ipClusterIP intra-cluster.
stage_service_cluster_ipsMappage des ClusterIP pour les services spécifiques à chaque étape (Cloud Deploy).
service_external_ipIP externe du LoadBalancer (lorsqu'une IP statique est réservée).
service_urlURL pour atteindre RAGFlow.
database_instance_nameNom de l'instance Cloud SQL.
database_nameNom de la base de données de l'application.
database_userUtilisateur de la base de données de l'application.
database_password_secretSecret Manager secret contenant le mot de passe de la base de données.
database_host / database_portPoint de terminaison de la base de données (127.0.0.1 via le proxy d'authentification) / port.
storage_bucketsBuckets Cloud Storage créés.
network_name / network_exists / regionsRéseau VPC, présence, régions disponibles.
container_image / container_registryImage déployée et dépôt Artifact Registry.
monitoring_enabled / monitoring_notification_channelsStatut et canaux de surveillance.
initialization_jobs / db_import_jobNoms des jobs de configuration et d'importation (facultatif).
deployment_id / tenant_id / resource_prefixIdentifiants de nommage.
project_id / project_numberIdentifiants du projet.
cicd_enabled / cicd_configurationStatut et détails CI/CD.
github_repository_url / github_repository_owner / github_repository_nameDétails du dépôt connecté.
artifact_registry_repository / cloudbuild_trigger_name / cloudbuild_trigger_idRegistre et déclencheur de build.
kubernetes_readyIndique 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_modeStatut VPC-SC.
audit_logging_enabled / artifact_registry_cmek_enabledJournalisation 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ètreValeur judicieuseRisqueConséquence si incorrect
elasticsearch_hostsrequis — défini à partir de Elasticsearch_GKECritiqueRAGFlow 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_redistrueCritiqueSans 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_typeMYSQL_8_0CritiqueRAGFlow nécessite MySQL ; PostgreSQL/NONE provoque un échec au démarrage.
enable_cloudsql_volumetrueCritiqueRAGFlow 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_userdéfini une foisCritiqueImmuable 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_importfalse sauf restaurationCritiqueL'activation sans backup_uri valide échoue le job d'importation.
quota_memory_requests / _limitsunités binairesCritiqueLes entiers bruts sont des octets et bloquent toute planification.
redis_hostIP Memorystore explicite ou "" (repli NFS)ÉlevéUn hôte Redis inaccessible ou incorrect interrompt silencieusement tous les workers de documents asynchrones.
min_instance_count1Élevé0 provoque une mise à l'échelle à zéro ; les démarrages à froid prennent 2 à 3 minutes et les requêtes expirent.
memory_limit8GiÉ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_enabledtrue pour la productionÉlevéSans PVC, les redémarrages de pod perdent tout état de traitement en cours.
session_affinityClientIPÉ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_nfstrueÉ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_armoractiver pour la productionMoyenL'interface utilisateur web de RAGFlow est autrement accessible publiquement.
backup_retention_days7 (augmenter pour la production)MoyenTrop court pour la rétention de conformité.
pdb_min_available vs min_instance_countlaisser de la margeMoyen1/1 peut bloquer les mises à niveau de nœuds (un seul pod ne peut pas être expulsé).
application_versionv0.13.0MoyenL'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.

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