Kubernetes Chart for Chroma AI application database

This chart deploys a single-node Chroma database on a Kubernetes cluster using the Helm package manager.

[!TIP] Deploying and managing multiple Chroma nodes support will arrive with the Chroma single-node Operator.

[!WARNING] For Chroma >= 1.0.0 (Rust server), chart values under chromadb.auth.* are legacy and ignored. Use network-level security controls (private networking, ingress auth, API gateways, mTLS) when deploying >= 1.0.0.

Roadmap

• [ ] Work in progress Security - the ability to secure chroma API with TLS
• [ ] Work in progress Backup and restore - the ability to back up and restore the index data
• [ ] Work in progress Observability - the ability to monitor the cluster using Prometheus and Grafana

Prerequisites

[!NOTE] Note: These prerequisites are necessary for local testing. If you have a Kubernetes cluster already setup you can skip

• Docker
• Minikube
• Helm

Installing the Chart

Setup the helm repo:

helm repo add chroma https://amikos-tech.github.io/chromadb-chart/
helm repo update
helm search repo chroma/

Update the values.yaml file to match your environment.

helm install chroma chroma/chromadb -f values.yaml

Example values.yaml file:

chromadb:
  allowReset: true

Alternatively you can specify each parameter using the --set key=value[,key=value] argument to helm install.

helm install chroma chroma/chromadb --set chromadb.allowReset=true

Chart Configuration Values

Legacy values for < 1.0.0

For Chroma >= 1.0.0 (Rust server), the chart keeps the following values only for backward compatibility and ignores them:

• chromadb.anonymizedTelemetry
• chromadb.logging.*
• chromadb.logConfigFileLocation
• chromadb.logConfigMap
• chromadb.maintenance.*
• chromadb.auth.*
• chromadb.apiImpl (removed; no longer read by the chart)

Use chromadb.telemetry.* and chromadb.extraConfig to configure Rust server behavior in >= 1.0.0.

Verifying installation

minikube service chroma-chromadb --url

Building the Docker image

docker build --no-cache -t <image:tag> -f image/Dockerfile .
docker push <image:tag>

Setup Kubernetes Cluster

For this example we'll set up a Kubernetes cluster using minikube.

minikube start --addons=ingress -p chroma #create a simple minikube cluster with ingress addon
minikube profile chroma #select chroma profile in minikube as active for kubectl commands

Chroma Authentication

[!NOTE] Token auth is enabled by default for < 1.0.0. For >= 1.0.0, chromadb.auth.* values are ignored.

By default, the chart will use a chromadb-auth secret in Chroma's namespace to authenticate requests. This secret is generated at install time.

Chroma authentication is supported for the following API versions:

• basic >= 0.4.7 and < 1.0.0
• token >= 0.4.8 and < 1.0.0

[!NOTE] Using auth parameters outside the supported versions above will result in auth settings being ignored.

Token Auth

Token Auth works with two types of headers that can be configured via chromadb.auth.token.headerType:

• AUTHORIZATION (default) - the clients are expected to pass Authorization: Bearer <token> header
• X-CHROMA-TOKEN (also works with X_CHROMA_TOKEN) - the clients are expected to pass X-Chroma-Token: <token> header

[!NOTE] The header type is case-insensitive.

Get the token:

export CHROMA_TOKEN=$(kubectl --namespace default get secret chromadb-auth -o jsonpath="{.data.token}" | base64 --decode)
export CHROMA_HEADER_NAME=$(kubectl --namespace default get configmap chroma-chromadb-token-auth-config -o jsonpath="{.data.CHROMA_AUTH_TOKEN_TRANSPORT_HEADER}")

[!NOTE] Note: The above examples assume default namespace is used for Chroma deployment.

Test the token:

curl -v http://localhost:8000/api/v1/collections -H "${CHROMA_HEADER_NAME}: Bearer ${CHROMA_TOKEN}"

[!NOTE] The above curl assumes a localhost forwarding is made to port 8000 If auth header is AUTHORIZATION then add Bearer prefix to the token when using curl.

Basic Auth

Get auth credentials:

CHROMA_BASIC_AUTH_USERNAME=$(kubectl --namespace default get secret chromadb-auth -o jsonpath="{.data.username}" | base64 --decode)
CHROMA_BASIC_AUTH_PASSWORD=$(kubectl --namespace default get secret chromadb-auth -o jsonpath="{.data.password}" | base64 --decode)

[!NOTE] The above examples assume default namespace is used for Chroma deployment.

Test the token:

curl -v http://localhost:8000/api/v1/collections -u "${CHROMA_BASIC_AUTH_USERNAME}:${CHROMA_BASIC_AUTH_PASSWORD}"
curl -v http://localhost:8000/api/v1/collections -u "${CHROMA_BASIC_AUTH_USERNAME}:${CHROMA_BASIC_AUTH_PASSWORD}"

[!NOTE] The above curl assumes a localhost forwarding is made to port 8000

Using custom/existing secret

Create a secret with the auth credentials:

kubectl create secret generic chromadb-auth-custom --from-literal=token="my-token"

To use a custom/existing secret for auth credentials, set chromadb.auth.existingSecret to the name of the secret.

chromadb:
  auth:
    existingSecret: "chromadb-auth-custom"

or

kubectl create secret generic chromadb-auth-custom --from-literal=token="my-token"
helm install chroma chroma/chromadb --set chromadb.auth.existingSecret="chromadb-auth-custom"

Verify the auth is working:

export CHROMA_TOKEN=$(kubectl --namespace default get secret chromadb-auth-custom -o jsonpath="{.data.token}" | base64 --decode)
export CHROMA_HEADER_NAME=$(kubectl --namespace default get configmap chroma-chromadb-token-auth-config -o jsonpath="{.data.CHROMA_AUTH_TOKEN_TRANSPORT_HEADER}")
curl -v http://localhost:8000/api/v1/collections -H "${CHROMA_HEADER_NAME}: Bearer ${CHROMA_TOKEN}"

Using the chart as a dependency

To use the chart as a dependency, add the following to your Chart.yaml file:

dependencies:
  - name: chromadb
    version: 0.2.2
    repository: "https://amikos-tech.github.io/chromadb-chart/"

Then, run helm dependency update to install the chart.

When using as a subchart, global.imagePullSecrets lets you define pull secrets once in the parent chart and have them propagated to all subcharts (including ChromaDB). Chart-level imagePullSecrets only applies to this chart. Both lists are merged, so there is no conflict if the same secret appears in both — though it may appear as a duplicate, Kubernetes handles this gracefully.

Rust v1 Config Options

For Chroma >= 1.0.0 (Rust server), these dedicated values map directly to the server config:

• chromadb.sqliteFilename -> sqlite_filename
• chromadb.sqliteDb.hashType -> sqlitedb.hash_type
• chromadb.sqliteDb.migrationMode -> sqlitedb.migration_mode
• chromadb.circuitBreaker.requests -> circuit_breaker.requests
• chromadb.telemetry.filters -> open_telemetry.filters
• chromadb.segmentManager.hnswIndexPoolCacheConfig -> segment_manager.hnsw_index_pool_cache_config

Example:

chromadb:
  sqliteFilename: "custom.db"
  sqliteDb:
    hashType: "sha256"
    migrationMode: "validate"
  circuitBreaker:
    requests: 500
  telemetry:
    filters:
      - crate_name: "chroma_frontend"
        filter_level: "info"
  segmentManager:
    hnswIndexPoolCacheConfig:
      policy: "memory"
      capacity: 65536

Extra Config

For Chroma >= 1.0.0 (Rust server), chromadb.extraConfig lets you inject arbitrary config keys into the server's YAML config file. This is useful for setting options not yet exposed as dedicated chart values.

chromadb:
  extraConfig:
    compactor:
      disabled_collections: []

[!WARNING] Keys in extraConfig override chart-managed and dedicated keys of the same name. Dedicated value validation (for example enum/range checks on sqlitedb and circuit_breaker) is applied before extraConfig merge, so overrides in extraConfig are treated as advanced escape hatches and are not re-validated by the chart.

Overriding port or listen_address via extraConfig is not allowed and will cause template rendering to fail. Use chromadb.serverHttpPort and chromadb.serverHost instead so that the Service, container port, and health probes remain in sync.

References

• Chroma: https://docs.trychroma.com/docs/overview/getting-started
• Helm install: https://helm.sh/docs/intro/install/
• Minikube install: https://minikube.sigs.k8s.io/docs/start/