Certification track: Professional Cloud Database Engineer (PCDE) · AI Tooling

Chroma on GKE Autopilot

Chroma is an AI-native open-source vector database purpose-built for embeddings and similarity search. It powers RAG pipelines, semantic search, and LangChain/LlamaIndex workflows. This module deploys Chroma on GKE Autopilot on top of the App_GKE foundation, which provisions and manages the shared Google Cloud and Kubernetes infrastructure.

This guide focuses on the cloud services Chroma uses and how to explore and operate them from the Google Cloud Console and the command line. For the mechanics that are common to every GKE application — Workload Identity, ingress, autoscaling, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, backups, and the deployment lifecycle — refer to the App_GKE foundation guide rather than repeating them here.

1. Overview

Chroma runs as a containerised vector-database workload. The deployment wires together a focused set of Google Cloud services:

Capability	Google Cloud service	Notes
Compute	GKE Autopilot	StatefulSet or Deployment pods, 1 vCPU / 1 GiB by default
Data persistence	StatefulSet PVC (recommended) or GCS FUSE	PVC-backed for production; GCS FUSE for development or lower-cost deployments
Object storage	Cloud Storage	Auto-provisioned `<prefix>-data` bucket; used as primary store when PVC is not enabled
Auth token	Secret Manager	Optional API token — `CHROMA_SERVER_AUTHN_CREDENTIALS` injected at runtime
Ingress	Cloud Load Balancing	`ClusterIP` by default (internal cluster access); optional `LoadBalancer` with IAP or auth token

Sensible defaults worth knowing up front:

No SQL database and no Redis. Chroma manages its own embedded storage. No Cloud SQL instance is created and no Redis connection is configured.
ClusterIP by default. The service is reachable only within the cluster; the endpoint_url output is not accessible from outside the cluster with this default. Set service_type = "LoadBalancer" only if external access is needed, and enable enable_auth_token or IAP alongside it.
Single-instance recommended. max_instance_count = 1 is the default. Multiple Chroma pods sharing a single PVC are not supported — concurrent writes would corrupt collections.
StatefulSet PVC for production. Setting stateful_pvc_enabled = true automatically resolves the workload type to StatefulSet and disables the GCS FUSE volume at /data to prevent a double-mount conflict.
Auth token is optional but recommended for any deployment reachable outside the pod namespace. When enabled, the token is stored in Secret Manager and must be passed as Authorization: Bearer <token> in every API call.
Health probes are fixed to /api/v2/heartbeat. This is the only health endpoint Chroma exposes.
Anonymised telemetry is always disabled. ANONYMIZED_TELEMETRY=false is injected automatically.
Many database/Redis/build-config inputs are inert. Chroma_GKE declares the full App_GKE variable surface (database, Redis, container build, quota, and other Foundation-mirror inputs) for check_conventions.py parity, but most of them are hardcoded or ignored by Chroma_Common/main.tf — see Section 4 for the full, per-group list.

2. Google Cloud Services & How to Explore Them

All commands assume you have run gcloud container clusters get-credentials <cluster> --region <region> --project <project> and that PROJECT, REGION, and NAMESPACE are set. The namespace and other identifiers are reported in the deployment Outputs.

A. GKE Autopilot — the Chroma workload

Chroma pods are scheduled on Autopilot, which bills for the CPU and memory the pods actually request. The deployment runs as a StatefulSet (when PVC-backed) or a Deployment (when GCS FUSE-backed), with Horizontal Pod Autoscaling managing replica count.

Console: Kubernetes Engine → Workloads → select the Chroma workload to see pods, revisions, and events. Kubernetes Engine → Services & Ingress shows the service IP.

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

See App_GKE for how Autopilot, scaling, and the workload type (Deployment vs StatefulSet) are managed.

B. Data Persistence — StatefulSet PVC or GCS FUSE

Chroma stores its embedded SQLite database, HNSW index files, and collection metadata in a persistent volume at /data. Two storage backends are available:

StatefulSet PVC (recommended for production): A Kubernetes PersistentVolumeClaim backed by a Balanced PD (standard-rwo) or SSD (premium-rwo) is provisioned per pod, providing low-latency local-disk access for index reads and writes.

Console: Kubernetes Engine → Storage → PersistentVolumeClaims.

CLI:

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

GCS FUSE (default when PVC is not enabled): A Cloud Storage bucket (<prefix>-data) is provisioned and mounted at /data via the GCS FUSE CSI driver.

Console: Cloud Storage → Buckets — look for the bucket whose name ends in -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

See App_GKE for GCS Fuse, CMEK options, and PVC provisioning.

C. Secret Manager

When enable_auth_token = true, Chroma's API authentication token is generated and stored as a Secret Manager secret. It is injected into pods at runtime as CHROMA_SERVER_AUTHN_CREDENTIALS; plaintext never appears in 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"

See App_GKE for the Secret Store CSI integration and rotation.

D. Networking & ingress

By default the Chroma service is exposed as a ClusterIP, accessible only within the cluster. When service_type = "LoadBalancer" is set, an external Cloud Load Balancing IP is provisioned. A custom domain, static IP, and Cloud Armor can be layered on.

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

See App_GKE for custom domains, Cloud CDN, and static IP details.

E. Cloud Logging & Monitoring

Pod stdout/stderr flow to Cloud Logging; GKE metrics flow to Cloud Monitoring. Optional uptime checks against /api/v2/heartbeat and alert policies are available.

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. Chroma Application Behaviour

No database bootstrap. Chroma manages its own embedded storage and requires no database initialisation job. No db-init job is injected. If you provide custom initialization_jobs, they run before the application starts.
Index loading on start. When Chroma restarts (after a pod eviction or rolling update), it loads its HNSW indexes from the PVC or GCS bucket. For large collections this can take tens of seconds; the startup probe at /api/v2/heartbeat waits until Chroma signals readiness.
Single-writer constraint. Chroma does not have distributed locking over its storage. Running more than one pod writing to the same PVC or GCS path will corrupt collections. Keep max_instance_count = 1 unless you are running a Chroma cluster deployment with separate storage per pod.

Auth token usage. When enable_auth_token = true, all API calls must include Authorization: Bearer <token>. Retrieve the token from Secret Manager, then use it with the Python client:

# 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}"}
)

Health probe. Both the startup and liveness probes target /api/v2/heartbeat with a 15-second initial delay. The probe path is fixed by Chroma_Common and cannot be changed.
Scheduled tasks. Chroma has no built-in scheduled commands. Use cron_jobs if you need periodic collection snapshots or maintenance tasks.

4. Configuration Variables

Variables are grouped exactly as they appear on the deployment platform. Only settings specific to or notable for Chroma are listed; every other input is inherited from App_GKE with its standard behaviour and defaults.