Chroma sur GKE Autopilot

Chroma est une base de données vectorielle open source, conçue nativement pour l'IA et dédiée aux embeddings et à la recherche par similarité. Elle alimente les pipelines RAG, la recherche sémantique et les workflows LangChain/LlamaIndex. Ce module déploie Chroma sur GKE Autopilot au-dessus du socle App_GKE, qui provisionne et gère l'infrastructure Google Cloud et Kubernetes partagée.

Ce guide se concentre sur les services cloud qu'utilise Chroma 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 à toute application 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 du socle App_GKE plutôt que de les répéter ici.

1. Vue d'ensemble

Chroma s'exécute sous la forme d'une charge de travail de base de données vectorielle conteneurisée. Le déploiement assemble un ensemble restreint de services Google Cloud :

Fonctionnalité	Service Google Cloud	Remarques
Calcul	GKE Autopilot	Pods StatefulSet ou Deployment, 1 vCPU / 1 GiB par défaut
Persistance des données	PVC de StatefulSet (recommandé) ou GCS FUSE	PVC pour la production ; GCS FUSE pour le développement ou les déploiements à moindre coût
Stockage d'objets	Cloud Storage	Bucket `<prefix>-data` provisionné automatiquement ; utilisé comme stockage principal lorsque le PVC n'est pas activé
Jeton d'authentification	Secret Manager	Jeton d'API facultatif — `CHROMA_SERVER_AUTHN_CREDENTIALS` injecté à l'exécution
Entrée	Cloud Load Balancing	`ClusterIP` par défaut (accès interne au cluster) ; `LoadBalancer` facultatif avec IAP ou jeton d'authentification

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

Ni base de données SQL ni Redis. Chroma gère son propre stockage embarqué. Aucune instance Cloud SQL n'est créée et aucune connexion Redis n'est configurée.
ClusterIP par défaut. Le service n'est joignable qu'à l'intérieur du cluster ; avec cette valeur par défaut, la sortie endpoint_url n'est pas accessible depuis l'extérieur du cluster. Définissez service_type = "LoadBalancer" uniquement si un accès externe est nécessaire, et activez enable_auth_token ou IAP en parallèle.
Instance unique recommandée. max_instance_count = 1 est la valeur par défaut. Plusieurs pods Chroma partageant un même PVC ne sont pas pris en charge — des écritures concurrentes corrompraient les collections.
PVC de StatefulSet pour la production. Définir stateful_pvc_enabled = true résout automatiquement le type de charge de travail en StatefulSet et désactive le volume GCS FUSE sur /data afin d'éviter un conflit de double montage.
Le jeton d'authentification est facultatif mais recommandé pour tout déploiement joignable en dehors de l'espace de noms du pod. Lorsqu'il est activé, le jeton est stocké dans Secret Manager et doit être transmis sous la forme Authorization: Bearer <token> dans chaque appel d'API.
Les sondes de santé sont fixées sur /api/v2/heartbeat. C'est le seul point de terminaison de santé qu'expose Chroma.
La télémétrie anonymisée est toujours désactivée. ANONYMIZED_TELEMETRY=false est injecté automatiquement.
De nombreuses entrées de base de données, Redis et configuration de build sont inertes. Chroma_GKE déclare l'ensemble des variables d'App_GKE (base de données, Redis, build de conteneur, quotas et autres entrées reflétant le socle) pour la parité avec check_conventions.py, mais la plupart sont codées en dur ou ignorées par Chroma_Common/main.tf — consultez la section 4 pour la liste complète, groupe par groupe.

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

A. GKE Autopilot — la charge de travail Chroma

Les pods Chroma sont planifiés sur Autopilot, qui facture le CPU et la mémoire effectivement demandés par les pods. Le déploiement s'exécute en tant que StatefulSet (avec un PVC) ou Deployment (avec GCS FUSE), le Horizontal Pod Autoscaling gérant le nombre de réplicas.

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

CLI :

kubectl get pods,svc,hpa -n "$NAMESPACE"
kubectl logs -n "$NAMESPACE" deploy/<service-name> --tail=100
kubectl describe statefulset -n "$NAMESPACE"    # when using StatefulSet

Consultez App_GKE pour la gestion d'Autopilot, du scaling et du type de charge de travail (Deployment ou StatefulSet).

B. Persistance des données — PVC de StatefulSet ou GCS FUSE

Chroma stocke sa base SQLite embarquée, ses fichiers d'index HNSW et les métadonnées de ses collections dans un volume persistant monté sur /data. Deux backends de stockage sont disponibles :

PVC de StatefulSet (recommandé pour la production) : un PersistentVolumeClaim Kubernetes adossé à un Balanced PD (standard-rwo) ou à un SSD (premium-rwo) est provisionné pour chaque pod, offrant un accès disque local à faible latence pour les lectures et écritures d'index.

Console : Kubernetes Engine → Storage → PersistentVolumeClaims.

CLI :

kubectl get pvc -n "$NAMESPACE"
kubectl describe pvc -n "$NAMESPACE" <pvc-name>

GCS FUSE (par défaut lorsque le PVC n'est pas activé) : un bucket Cloud Storage (<prefix>-data) est provisionné et monté sur /data via le pilote CSI GCS FUSE.

Console : Cloud Storage → Buckets — repérez 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 pod:
kubectl exec -n "$NAMESPACE" <pod-name> -- df -h | grep /data

Consultez App_GKE pour GCS Fuse, les options CMEK et le provisionnement des PVC.

C. Secret Manager

Lorsque enable_auth_token = true, le jeton d'authentification de l'API de Chroma est généré et stocké sous forme de secret dans Secret Manager. Il est injecté dans les pods à l'exécution sous la forme CHROMA_SERVER_AUTHN_CREDENTIALS ; la valeur en clair n'apparaît jamais dans la configuration.

Console : Security → 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"

Consultez App_GKE pour l'intégration Secret Store CSI et la rotation.

D. Réseau et entrée

Par défaut, le service Chroma est exposé en ClusterIP, accessible uniquement à l'intérieur du cluster. Lorsque service_type = "LoadBalancer" est défini, une IP externe Cloud Load Balancing est provisionnée. Un domaine personnalisé, une IP statique et Cloud Armor peuvent s'y ajouter.

Console : Kubernetes Engine → Services & Ingress ; Network services → Load balancing ; VPC network → IP addresses.

CLI :

kubectl get ingress,svc -n "$NAMESPACE"
gcloud compute addresses list --project "$PROJECT"
# Test the Chroma heartbeat from inside the cluster:
kubectl run -n "$NAMESPACE" --rm -it curl --image=curlimages/curl -- \
  curl http://<cluster-ip>:8000/api/v2/heartbeat

Consultez App_GKE pour les domaines personnalisés, Cloud CDN et les détails sur l'IP statique.

E. Cloud Logging et Monitoring

Les flux stdout/stderr des pods sont envoyés vers Cloud Logging ; les métriques GKE vers Cloud Monitoring. Des tests de disponibilité sur /api/v2/heartbeat et des règles d'alerte sont disponibles en option.

Console : Logging → Logs Explorer ; Monitoring → Dashboards / Alerting.

CLI :

gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="'"$NAMESPACE"'"' \
  --project "$PROJECT" --limit 50

3. Comportement de l'application Chroma

Aucune initialisation 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 avant le démarrage de l'application.
Chargement des index au démarrage. Lorsque Chroma redémarre (après l'éviction d'un pod ou une mise à jour progressive), il charge ses index HNSW depuis le PVC ou le bucket GCS. Pour de grandes collections, cela peut prendre plusieurs dizaines de secondes ; la sonde de démarrage sur /api/v2/heartbeat attend que Chroma signale qu'il est prêt.
Contrainte d'écrivain unique. Chroma ne dispose d'aucun verrouillage distribué sur son stockage. Exécuter plus d'un pod écrivant sur le même PVC ou le même chemin GCS corrompra les collections. Conservez max_instance_count = 1, sauf si vous exécutez un déploiement Chroma en cluster avec un stockage distinct par pod.

Utilisation du jeton d'authentification. Lorsque enable_auth_token = true, tous les appels d'API doivent inclure Authorization: Bearer <token>. Récupérez le jeton dans Secret Manager, puis utilisez-le avec le client Python :

# Retrieve token
TOKEN=$(gcloud secrets versions access latest \
  --secret=<prefix>-auth-token --project "$PROJECT")

import chromadb
client = chromadb.HttpClient(
    host="<cluster-ip>", port=8000,
    headers={"Authorization": f"Bearer {TOKEN}"}
)

Sonde de santé. Les sondes de démarrage et de vivacité ciblent toutes deux /api/v2/heartbeat avec un délai initial de 15 secondes. Le chemin de la sonde est fixé par Chroma_Common et ne peut pas être modifié.
Tâches planifiées. Chroma ne dispose d'aucune commande planifiée intégrée. Utilisez cron_jobs si vous avez besoin d'instantanés périodiques des collections ou de tâches de maintenance.

4. Variables de configuration

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