Aller au contenu principal

Chroma sur Google Cloud Run

Chroma sur Google Cloud Run

Chroma est une base de données vectorielle open source native de l'IA, conçue spécifiquement pour les embeddings et la recherche de similarité. Elle alimente les pipelines RAG, la recherche sémantique et les workflows LangChain/LlamaIndex. Ce module déploie Chroma sur Cloud Run v2 au-dessus de la fondation App_CloudRun, qui provisionne et gère l'infrastructure Google Cloud partagée.

Ce guide se concentre sur les services cloud utilisés par Chroma et sur la manière de les explorer et de les opérer depuis la console Google Cloud et la ligne de commande. Pour les mécanismes communs à chaque application Cloud Run — identité de service, ingestion 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 — veuillez vous référer au guide de la fondation App_CloudRun plutôt que de les répéter ici.


Ce que coûte Chroma sur RAD, et comment cela se compare​

Chroma sur le module Cloud Run de RAD coûte environ 19,14 $ US par mois dans un projet Google Cloud que vous possédez, plus des frais de module uniques de 40 crédits (4 $ US). Chroma est une base de données vectorielle native de l'IA pour les embeddings et la recherche de similarité, utilisée pour soutenir les pipelines RAG et la recherche sémantique. GKE Autopilot convient à Chroma qui doit rester actif, s'adapter à travers les pods ou s'exécuter à côté d'autres charges de travail Kubernetes ; pour le coût le plus bas, ce module Cloud Run est généralement le bon choix — consultez le guide GKE si vous avez besoin de l'autre.

Si Chroma n'est nécessaire qu'occasionnellement — une démo, un essai, une charge de travail saisonnière ou d'étude — un projet géré par RAD peut être supprimé et restauré dans les 30 jours sans frais supplémentaires, de sorte que les 19,14 $ US deviennent quelques dollars par mois à la place. Voir Mettez-le en pause gratuitement, ci-dessous.

Ce que vous payez sur RAD​

Dans un projet Google Cloud que vous possédezDans un projet que RAD gère pour vous
Frais de module, une fois par déploiement40 crédits (4 $ US au prix de la recharge)36 crédits (10 % de moins)
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 CloudFacturé par Google à votre propre compte de facturation, environ 19,14 $ US par mois pour la configuration par défaut (tableau ci-dessous)Mesuré à l'heure en crédits ; RAD publie 17 crédits par jour, environ 510 par mois (environ 51 $ US au prix de la recharge)
Qui possède quoiVous possédez le projet et sa facturation ; RAD le déploie et le met à jourRAD possède le projet, avec des garde-fous, des quotas et des alertes budgétaires ; vous avez accès à la console, et un solde minimum acheté est conservé en réserve

Votre premier déploiement réussi sur RAD est exempt de frais de module, quel que soit le montant des frais : une fois par compte, pour un module que vous déployez et payez vous-même (dans une solution, les frais d'une application : la première à réussir ; jamais une session de lab ou un projet client).

10 crédits coûtent 1 $ US pour une recharge unique, moins sur un plan. Dans un projet géré par RAD, la base de données, le serveur de fichiers et le réseau sont partagés par toutes les applications du projet, de sorte qu'une deuxième application n'ajoute pas une deuxième base de données.

Coût d'exécution par défaut dans votre propre projet (us-central1, prix catalogue Google) :

Ressource (module par défaut)Par mois
Cloud Run, 1x vCPU / 1 Gio (chaud)13,14 $ US
Cloud NAT et réseau5 $ US
Cloud Storage (modules complémentaires, sauvegardes)1 $ US
Totalenviron 19,14 $ US

Comment cela se compare​

  • L'offre gérée du projet, Chroma Cloud, commence à 0 $ par mois plus l'utilisation (10 bases de données, 5 $ de crédits inclus — environ 2,50 $/Gio écrit, 0,33 $/Gio stocké par mois, et une petite charge par requête et par Gio retourné), passant à 250 $ par mois plus l'utilisation sur le plan Team.
  • Si vous l'exécutez vous-même, un petit VPS exécutant le propre processus serveur de Chroma coûte moins cher en espèces : un Hetzner CPX22 ou un DigitalOcean 2 vCPU/4 Go coûte environ 24 $ par mois, ou un GCP e2-standard-2 environ 49 $ par mois — plus votre propre temps pour les sauvegardes, les correctifs de sécurité et les mises à niveau, que Cloud SQL, Secret Manager et la surveillance gérés par RAD couvrent pour vous.
  • RAD ne prétend jamais être moins cher que l'infrastructure nue en termes monétaires — ce n'est généralement pas le cas. La différence est ce que RAD gère pour vous : les correctifs, les sauvegardes, les secrets et la surveillance, ainsi que la possibilité de mettre Chroma en pause gratuitement plutôt que de payer pour une capacité inactive (voir ci-dessous).

Mettez-le en pause gratuitement : supprimez un projet géré par RAD, restaurez-le lorsque vous en avez besoin​

Si Chroma s'exécute dans un projet que RAD gère pour vous, vous avez une deuxième option qui va bien au-delà de la mise à l'échelle à zéro : supprimez l'ensemble du projet et restaurez-le dans les 30 jours pour presque rien. Cela convient bien mieux à Chroma dont vous n'avez besoin qu'occasionnellement que de le faire fonctionner en continu.

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, sera utilisable 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.

  • Comment ça marche. La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer le projet. Google ne supprime pas le projet immédiatement : il le conserve, récupérable, pendant 30 jours. Comme la facturation est déjà déliée, rien n'est facturé pendant cette attente. Contrairement à la suppression d'un module, cela ne supprime pas les ressources Cloud Run une par une — l'ensemble du projet, et tout ce qu'il contient, s'arrête simplement.
  • La restauration est une vérification, pas une reconstruction. Dans les 30 jours, le propriétaire du projet peut le restaurer. RAD demande à Google de récupérer le projet et de rattacher son compte de facturation, puis vous demande d'exécuter Update 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.
  • Ainsi, un mois d'utilisation occasionnelle peut coûter quelques dollars, et non les 51 $ US par mois pour le maintenir en fonctionnement. Déployez Chroma, utilisez-le, supprimez le projet. Restaurez-le la prochaine fois que vous en avez besoin, confirmez avec Update, et supprimez-le à nouveau lorsque vous avez terminé. Vous ne payez les frais de module qu'une seule fois et pour les heures où il était réellement actif.
  • Ce que cela nécessite. Vous devez être propriétaire du projet (pas un projet que vous apportez et dont RAD ne gère que la facturation), et vous le restaurez vous-même dans les 30 jours — après cela, Google le supprime définitivement. La restauration est admise comme la création d'un nouveau projet : 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.
  • Une véritable lacune : le bucket de sauvegarde ne survit pas. Les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du projet, et ce bucket n'est pas protégé par la suppression logicielle de Cloud Storage, il est donc très probable qu'il disparaisse 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é Chroma 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​

Cloud Run conserve une instance chaude, il ne se met donc pas entièrement à l'échelle zéro par lui-même. L'option ci-dessus ne s'applique qu'à un projet géré par RAD ; dans votre propre projet, ou une fois la fenêtre de 30 jours passée, le moyen d'arrêter de payer est de supprimer le déploiement et de le redéployer lorsque vous en avez besoin.

  • Ce que coûte un redéploiement. Les frais de module à nouveau (les builds sont inclus) : 40 crédits (4,00 $ US) dans votre propre projet. La suppression ne permet d'économiser de l'argent que si Chroma devait rester inutilisé pendant environ 8 jours ou plus dans votre propre projet (0,64 $ US par jour), ou environ 3 jours ou plus dans un projet géré par RAD (17 crédits par jour).
  • Conservez vos données en premier. Les sauvegardes nocturnes sont écrites dans un bucket à l'intérieur du déploiement et sont supprimées avec celui-ci, alors copiez la dernière sauvegarde avant de la supprimer si vous voulez la conserver.
  • Notez vos paramètres. RAD ne recrée pas un déploiement supprimé pour vous ; vous saisissez à nouveau les paramètres lorsque vous déployez.

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 sont reversés 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 Google Cloud de l'API Cloud Billing Catalog ; frais propres à RAD et estimations de crédits quotidiens de radmodules.dev/pricing ; Supprimer et restaurer des projets pour la fenêtre de récupération de 30 jours et ce qu'elle dit sur les objets Cloud Storage sans suppression logicielle ; Chroma Cloud. Les prix changent ; vérifiez chaque source avant de vous fier à un chiffre.

1. Vue d'ensemble​

Chroma s'exécute en tant que service de base de données vectorielle conteneurisée sur Cloud Run v2. Le déploiement relie un ensemble ciblé de services Google Cloud :

CapacitéService Google CloudNotes
CalculCloud Run v2 (Gen2)1 vCPU / 1 Gio par défaut ; min_instance_count = 1 pour éviter les démarrages à froid de rechargement d'index
Persistance des donnéesCloud Storage (GCS FUSE)Bucket <prefix>-data auto-provisionné monté à /data ; backend de stockage principal
Jeton d'authentificationSecret ManagerJeton API optionnel — CHROMA_SERVER_AUTHN_CREDENTIALS injecté à l'exécution
IngressURL interne Cloud Runingress_settings = "internal" par défaut ; équilibreur de charge HTTPS optionnel + domaine personnalisé

Valeurs par défaut judicieuses à connaître d'emblée :

  • Pas de base de données SQL et pas de Redis. Chroma gère son propre stockage embarqué. Aucune instance Cloud SQL n'est créée et aucune connexion Redis n'est configurée.
  • ingress_settings = "internal" par défaut. La sortie chroma_api_url n'est pas accessible depuis l'internet public avec ce paramètre. Le passage à "all" nécessite enable_auth_token = true (appliqué au moment de la planification).
  • Instance unique requise. max_instance_count = 1 est la valeur par défaut. Plusieurs instances Cloud Run sur le même montage GCS FUSE ne peuvent pas coordonner les écritures et corrompront les collections.
  • GCS FUSE est le backend de persistance. Un bucket <prefix>-data est automatiquement provisionné et monté à /data. L'environnement d'exécution Gen2 est requis.
  • Le jeton d'authentification est facultatif mais recommandé pour tout déploiement accessible en dehors du VPC. Lorsqu'il est activé, le jeton est stocké dans Secret Manager et doit être passé comme Authorization: Bearer <token> dans chaque appel API.
  • Les sondes de santé sont fixées à /api/v2/heartbeat. C'est le seul point d'accès de santé exposé par Chroma ; le chemin de la sonde ne peut pas être modifié.
  • La télémétrie anonymisée est toujours désactivée. ANONYMIZED_TELEMETRY=false est injecté automatiquement.

2. Services Google Cloud et comment les explorer​

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

A. Cloud Run — le service Chroma​

Chroma s'exécute en tant que service Cloud Run v2. Chaque déploiement crée une révision immuable ; le trafic peut être réparti entre les révisions pour des déploiements sûrs. cpu_always_allocated par défaut à false (facturation basée sur les requêtes) ; définissez-le true (avec `min_instance_count

= 1`) pour maintenir le CPU alloué entre les requêtes afin que les opérations d'index en arrière-plan et les vérifications de santé ne soient jamais ralenties.

  • Console : Cloud Run → sélectionnez le service pour les révisions, le trafic, les logs 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"

Voir App_CloudRun pour la mise à l'échelle, la concurrence, l'environnement d'exécution et la répartition du trafic.

B. Cloud Storage (GCS FUSE) — persistance des données Chroma​

Chroma stocke sa base de données SQLite embarquée, ses fichiers d'index HNSW et ses métadonnées de collection au chemin /data. Un bucket Cloud Storage dédié (<prefix>-data) est automatiquement provisionné et monté à /data via le pilote CSI GCS FUSE. Le compte de service Cloud Run se voit accorder un accès en lecture/écriture automatiquement.

  • Console : Cloud Storage → Buckets — recherchez le bucket dont le nom se termine par -data.
  • CLI :
    gcloud storage buckets list --project "$PROJECT"
    gcloud storage ls gs://<data-bucket>/chroma/ # inspect Chroma's on-disk layout
    # Confirm the GCS FUSE mount inside a running instance:
    gcloud run services describe <service-name> --region "$REGION" \
    --format='value(spec.template.spec.volumes)'

Voir App_CloudRun pour GCS Fuse, les options CMEK et la gestion des buckets.

C. Secret Manager​

Lorsque enable_auth_token = true, le jeton d'authentification API de Chroma est généré et stocké en tant que secret Secret Manager. Il est injecté dans le service au moment de l'exécution en tant que CHROMA_SERVER_AUTHN_CREDENTIALS ; le texte en clair n'apparaît jamais dans la configuration.

  • Console : Sécurité → Secret Manager.
  • CLI :
    gcloud secrets list --project "$PROJECT"
    # Retrieve the token to configure API clients:
    gcloud secrets versions access latest --secret=<prefix>-auth-token --project "$PROJECT"

Voir App_CloudRun pour les détails d'injection et de rotation.

D. Réseau et ingress​

Par défaut, le service n'est accessible qu'au sein du VPC (ingress_settings = "internal"). Un équilibreur de charge HTTPS externe avec un domaine personnalisé, Cloud CDN et Cloud Armor peuvent être superposés ; les paramètres d'égression contrôlent la connectivité.

  • Console : Cloud Run (URL du service) ; Services réseau → Équilibrage de charge.
  • CLI :
    gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
    gcloud compute addresses list --project "$PROJECT"
    # Test the Chroma heartbeat from inside the VPC:
    curl <internal-service-url>/api/v2/heartbeat

Voir App_CloudRun.

E. Cloud Logging et Monitoring​

Les logs des conteneurs sont envoyés à Cloud Logging ; les métriques Cloud Run sont envoyées à Cloud Monitoring, avec une vérification de disponibilité optionnelle contre /api/v2/heartbeat et des politiques d'alerte.

  • Console : Logging → Explorateur de logs ; Monitoring → Tableaux de bord / Alertes.
  • CLI :
    gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Comportement de l'application Chroma​

  • Pas de bootstrap de base de données. Chroma gère son propre stockage embarqué et ne nécessite aucun job d'initialisation de base de données. Aucun job db-init n'est injecté. Si vous fournissez des initialization_jobs personnalisés, ils s'exécutent en tant que jobs Cloud Run avant la mise à jour du service.
  • Chargement de l'index au démarrage à froid. Lorsqu'une nouvelle instance démarre (après une mise à l'échelle à zéro ou une nouvelle révision), elle charge les index HNSW depuis le bucket GCS. Pour les grandes collections, cela peut prendre des dizaines de secondes ; la sonde de démarrage à /api/v2/heartbeat attend que Chroma signale sa disponibilité. Gardez min_instance_count = 1 pour éviter cela à chaque requête.
  • Contrainte d'instance unique. Chroma est un stockage à écrivain unique. Plusieurs instances Cloud Run sur le même montage GCS FUSE corrompront les collections car il n'y a pas de verrou d'écriture distribué. Gardez toujours max_instance_count = 1. Mettez à l'échelle verticalement (augmentez le CPU et la mémoire) plutôt qu'horizontalement.
  • Utilisation du jeton d'authentification. Lorsque enable_auth_token = true, tous les appels API doivent inclure Authorization: Bearer <token>. Récupérez le jeton de Secret Manager, puis utilisez-le :
    TOKEN=$(gcloud secrets versions access latest \
    --secret=<prefix>-auth-token --project "$PROJECT")
    curl -H "Authorization: Bearer $TOKEN" <service-url>/api/v2/collections
    Client Python :
    import chromadb
    client = chromadb.HttpClient(
    host="<service-hostname>", port=443, ssl=True,
    headers={"Authorization": f"Bearer {TOKEN}"}
    )
  • Sonde de santé. Les sondes de démarrage et de vivacité ciblent toutes deux /api/v2/heartbeat via HTTP. Le chemin de la sonde est fixé par Chroma_Common et ne peut pas être modifié. La sonde de démarrage permet un délai initial de 15 secondes pour accommoder le montage GCS FUSE et le chargement de l'index.
  • Tâches planifiées. Chroma n'a pas de commandes planifiées intégrées. Utilisez cron_jobs si vous avez besoin de captures instantanées de collection périodiques ou de tâches de maintenance, déclenchées par Cloud Scheduler.

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 Chroma sont listés ; toute autre entrée est héritée de App_CloudRun avec son comportement standard.

Groupe 1 — Projet et identité​

VariableValeur par défautDescription
project_id(requis)Projet Google Cloud cible.
regionus-central1Région pour le service et les ressources régionales.
enable_auth_tokenfalseGénère un jeton API aléatoire et le stocke dans Secret Manager. Recommandé pour tout déploiement accessible en dehors du VPC.

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.

Groupe 3 — Identité de l'application​

VariableValeur par défautDescription
application_namechromaNom de base des ressources. Ne pas modifier après le premier déploiement.
application_display_nameChroma Vector DatabaseNom convivial affiché dans la console.
description(défini)Description du service Cloud Run.
application_versionlatestTag de version de l'image Chroma. Épinglez à une version spécifique pour des déploiements reproductibles.

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

VariableValeur par défautDescription
deploy_applicationtrueDéfinissez false pour provisionner uniquement l'infrastructure.
cpu_limit1000mCPU par instance ; augmentez à 2000m+ pour les charges de travail de requêtes de production.
memory_limit1GiMémoire par instance. Chroma charge les index HNSW en mémoire — taille basée sur le nombre de collections et les dimensions des vecteurs.
min_instance_count1Instances minimales. Gardez ≥ 1 pour éviter les démarrages à froid de rechargement d'index.
max_instance_count1Instances maximales. Gardez à 1 — plusieurs instances sur le même chemin GCS FUSE corrompront les collections.
container_port8000Port de l'API REST Chroma.
execution_environmentgen2Gen2 requis pour les montages GCS FUSE.
cpu_always_allocatedfalseFacturation basée sur les requêtes par défaut ; définissez true pour maintenir le CPU alloué entre les requêtes et éviter les délais d'attente des opérations d'index en arrière-plan.
timeout_seconds300Durée maximale de la requête. Augmentez pour les grandes recherches de similarité par lots.
enable_cloudsql_volumefalseNon applicable — Chroma n'a pas de base de données SQL.
enable_image_mirroringtrueMettez en miroir l'image Chroma dans Artifact Registry pour éviter les limites de débit de Docker Hub.
traffic_split[]Allocation de trafic Canary/bleu-vert entre les révisions.
max_revisions_to_retain7Nombre maximal de révisions Cloud Run à conserver.

Groupe 5 — Accès et réseau​

VariableValeur par défautDescription
ingress_settingsinternalGardez internal pour que Chroma ne soit accessible qu'au sein du VPC. La définition de all nécessite enable_auth_token = true (appliqué au moment de la planification).
vpc_egress_settingPRIVATE_RANGES_ONLYMode d'égression VPC.
enable_iapfalseExiger l'authentification Google Identity via IAP.
iap_authorized_users / iap_authorized_groups[]Qui peut accéder via IAP.

Groupe 6 — Variables d'environnement et secrets​

VariableValeur par défautDescription
environment_variables{}Paramètres supplémentaires non secrets. ANONYMIZED_TELEMETRY=false et CHROMA_SERVER_HTTP_PORT=8000 sont toujours injectés.
secret_environment_variables{}Mappage de variable d'environnement → nom de secret Secret Manager.
secret_propagation_delay30Secondes à attendre après la création du secret avant de continuer.
secret_rotation_period2592000sPériode de rappel de rotation des secrets (30 jours).

Groupe 7 — Sauvegarde et restauration​

VariableValeur par défautDescription
backup_schedule0 2 * * *Cron de sauvegarde automatisée (UTC). Laissez vide pour désactiver.
backup_retention_days7Rétention en jours. Augmentez pour la production/conformité.
enable_backup_import / backup_source / backup_uri / backup_formatoptions de restaurationRestaurer à partir d'une sauvegarde lors du déploiement.

Groupe 8 — CI/CD et autorisation binaire​

Intégration standard App_CloudRun Cloud Build / Cloud Deploy — voir App_CloudRun. Entrées clés : enable_cicd_trigger, github_repository_url, github_token, enable_cloud_deploy, enable_binary_authorization, binauthz_evaluation_mode, additional_cloudrun_sa_roles.

Groupe 9 — Scripts SQL personnalisés​

enable_custom_sql_scripts, custom_sql_scripts_bucket, custom_sql_scripts_path, custom_sql_scripts_use_root — non applicable à Chroma (pas de base de données SQL). Ces variables sont acceptées pour la compatibilité de la fondation mais n'ont aucun effet. Voir App_CloudRun.

Groupe 10 — Équilibreur de charge, CDN et Artifact Registry​

VariableValeur par défautDescription
enable_cloud_armorfalseProvisionne un équilibreur de charge HTTPS global avec Cloud Armor WAF.
admin_ip_ranges[]CIDR exemptés des règles WAF.
application_domains[]Noms de domaine personnalisés pour l'équilibreur de charge HTTPS.
enable_cdnfalseActive Cloud CDN sur l'équilibreur de charge HTTPS. Nécessite enable_cloud_armor = true.
max_images_to_retain / delete_untagged_images / image_retention_days(défini)Politique de nettoyage d'Artifact Registry.

Groupe 11 — Stockage et système de fichiers​

VariableValeur par défautDescription
create_cloud_storagetrueProvisionne des buckets GCS. Le bucket <prefix>-data est provisionné automatiquement par Chroma_Common.
storage_buckets / gcs_volumes(défini)Buckets supplémentaires / montages GCS FUSE.
enable_nfsfalseMonte Cloud Filestore NFS (nécessite gen2). Chroma utilise GCS pour le stockage principal ; activez uniquement pour les jobs d'initialisation personnalisés.
nfs_mount_path/mnt/nfsChemin de montage du conteneur NFS.
manage_storage_kms_iam / enable_artifact_registry_cmekfalseOptions CMEK.

Groupe 12 — Backend de base de données​

Non applicable — Chroma n'a pas de base de données SQL. Les variables suivantes sont acceptées uniquement pour la compatibilité de la fondation et sont fixes ou ignorées : database_type (fixé à NONE), database_password_length, enable_auto_password_rotation, rotation_propagation_delay_sec, db_host_env_var_name, db_user_env_var_name, db_name_env_var_name, db_port_env_var_name, service_url_env_var_name.

Groupe 13 — Jobs et tâches planifiées​

VariableValeur par défautDescription
initialization_jobs[]Chroma ne nécessite aucun job d'initialisation par défaut. Fournissez des jobs uniquement pour le chargement de données personnalisé.
cron_jobs[]Jobs récurrents déclenchés par Cloud Scheduler (par exemple, captures instantanées de collection).

Groupe 14 — Observabilité et santé​

VariableValeur par défautDescription
startup_probe / startup_probe_config/api/v2/heartbeatSonde de démarrage HTTP — Chroma renvoie 200 une fois entièrement initialisé. Le chemin de la sonde est fixe.
liveness_probe / health_check_config/api/v2/heartbeatSonde de vivacité.
uptime_check_configenabled=false, path=/api/v2/heartbeatVérification de disponibilité Cloud Monitoring ; désactivée par défaut.
alert_policies[]Politiques d'alerte métrique.

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

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

Retournées lors d'un déploiement réussi — le moyen le plus rapide de localiser et d'explorer les ressources en cours d'exécution.

SortieDescription
service_nameNom du service Cloud Run.
chroma_api_urlURL VPC interne pour l'API Chroma v2 (ajouter /collections, /heartbeat, etc.). Accessible uniquement au sein du VPC lorsque ingress_settings est internal.
service_locationRégion dans laquelle le service s'exécute.
stage_servicesDétails du service spécifiques à l'étape (Cloud Deploy).
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, vérifications de disponibilité.
initialization_jobsNoms des jobs de configuration personnalisés.
deployment_id / tenant_id / resource_prefixIdentifiants de nommage.
project_id / project_numberIdentifiants de projet.
cicd_enabled / github_repository_url / github_repository_owner / github_repository_name / cicd_configurationÉtat et détails 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 VPC-SC.
audit_logging_enabled / artifact_registry_cmek_enabledJournalisation d'audit et état 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
enable_auth_tokentrue pour tout déploiement accessible de l'extérieurCritiqueSans jeton, tout appelant pouvant atteindre l'API Chroma peut lire, écrire ou supprimer chaque collection.
ingress_settingsinternal (par défaut)ÉlevéLe passage à "all" sans enable_auth_token = true expose une base de données vectorielle non authentifiée à l'internet public (bloqué au moment de la planification).
max_instance_count1ÉlevéPlusieurs instances sur le même chemin GCS FUSE corrompront les collections — Chroma n'a pas de verrou d'écriture distribué.
execution_environmentgen2ÉlevéGCS FUSE nécessite Gen2. Le déploiement avec gen1 alors que les volumes GCS sont configurés échoue le déploiement.
memory_limit4Gi+ pour la productionÉlevéChroma charge les index HNSW en mémoire. Le 1Gi par défaut ne prend en charge que de très petites collections ; les arrêts OOM interrompent les requêtes en cours.
cpu_always_allocatedtrueMoyenLa définition de false provoque une limitation du CPU entre les requêtes, ralentissant les opérations d'index et pouvant entraîner des délais d'attente pour les vérifications de santé.
application_versionépingler à un tag spécifiqueMoyenL'utilisation de latest rend les déploiements non reproductibles. Les formats de données Chroma peuvent changer entre les versions majeures.
timeout_secondsaugmenter pour les grandes collectionsMoyenLes grandes recherches de similarité sur des millions de vecteurs peuvent prendre plusieurs secondes ; des 504 sont renvoyées aux clients si le délai d'attente est trop faible.
min_instance_count1MoyenLa mise à l'échelle à zéro provoque des démarrages à froid pendant lesquels les index HNSW doivent être rechargés depuis GCS, ajoutant de la latence pour la première requête après l'inactivité.
enable_iap / enable_cloud_armoractiver pour les services accessibles de l'extérieurÉlevéSans authentification, un point de terminaison Chroma exposé de l'extérieur est entièrement ouvert.
backup_retention_daysaugmenter pour la productionMoyenLes instantanés réguliers des buckets GCS sont le chemin de récupération principal ; une rétention trop courte limite les options de récupération.
enable_cloudsql_volumefalseFaibleChroma n'a pas de base de données SQL ; l'activation de ceci injecte un sidecar Cloud SQL Auth Proxy qui consomme des ressources inutilement.

Pour le comportement de la fondation référencé tout au long — identité de 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 d'images — voir App_CloudRun. La configuration d'application spécifique à Chroma partagée avec la variante GKE est décrite dans Chroma_Common.

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