Skip to content

Creating a ChromaDB data service#

ChromaDB is a vector database. It stores, indexes and queries embeddings through an HTTP API and SDKs, which makes it a practical backend for semantic search and retrieval-augmented generation (RAG). This tutorial shows you how to create an Ametnes-managed ChromaDB service and connect to it over HTTPS with a token.

Ametnes offers two release series:

  • service/chromadb:1.5 — current release (Chroma 1.5.9). Uses the Setup Architecture tiers and is recommended for new deployments.
  • service/chromadb:1.4 — older release (Chroma 1.4.1) with legacy manual sizing: one node, up to 8 CPU / 32Gi memory / 1TiB storage.

Every tier in the 1.5 catalog is a single node; tiers differ by CPU, memory, storage and ACU. ChromaDB scales vertically rather than by adding replicas.

Prerequisites#

  1. A service location (see Service Location).

Networking is automatic by default

Creating a network access resource is optional. If you do not create one, Ametnes manages network access for the location and the service attaches automatically. Create your own only if you want to control exposure (see Network Access Resources).

Connections#

ChromaDB publishes one HTTPS connection:

Connection Default port Purpose
https 443 ChromaDB HTTP API (v2)

The host is the service's DNS name on your zone. The shared ingress routes the connection to ChromaDB's HTTP port (8000), so use port 443 and HTTPS. ChromaDB has no separate web UI; all operations go through the HTTP API and the Python/JavaScript clients.

Authenticate with the token from create time in the Authorization header:

Authorization: Bearer <token>

The 1.5 catalog uses Chroma's token authentication provider. No default token ships with the service; the value you set at create time is the only token.

Create the ChromaDB service#

  1. Navigate to the Services left menu and click New Service.
  2. Enter Name (for example ChromaService).
  3. Select Kind: Chroma Service (service/chromadb:1.5).
  4. Select the Location: your data service location. Leave Network unset to let Ametnes manage it.
  5. Select the Setup Architecture: Starter for evaluation, Small and above for production.
  6. Enter the Authentication token. The field is required and no token is generated for you.
  7. Leave Public unset for a private endpoint, or enable it to make the endpoint reachable from the internet.
  8. Click Create Service and wait for the status ready.
service.tf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
resource "ametnes_service" "chromadb" {
  name     = "ChromaService"
  project  = data.ametnes_project.project.id
  location = data.ametnes_location.location.id
  kind     = "chromadb:1.5"
  capacity {
    storage = 10
  }
  config = {
    "architecture"   = "Starter"
    "admin.password" = "<auth-token>"
  }
}

output "connections" {
  value = ametnes_service.chromadb.connections
}

The provider adds the service/ prefix. The architecture controls CPU, memory and storage; capacity.storage sets the data volume size.

Store the token immediately

The token is stored as a per-resource Secret and is shown at create time. Store it in a secrets manager before leaving the create screen; clients cannot retrieve it from the service later.

Connect#

Check that the service is healthy and that the token is accepted:

curl --request GET \
  --url "https://<host>/api/v2/heartbeat" \
  --header "Authorization: Bearer <token>"

List collections in the default tenant and database:

curl --request GET \
  --url "https://<host>/api/v2/tenants/default_tenant/databases/default_database/collections" \
  --header "Authorization: Bearer <token>"

From Python, install the client and connect over HTTPS:

pip install chromadb

import chromadb

client = chromadb.HttpClient(
    host="<host>",
    port=443,
    ssl=True,
    headers={"Authorization": "Bearer <token>"},
)

print(client.heartbeat())

Create a collection and query it#

The following example creates a collection, adds documents and runs a semantic query. ChromaDB's Python client uses its default embedding function (a small ONNX model) on the client side. Pass embeddings= to add and query_embeddings= to query if you want to use embeddings from your own model provider instead.

import chromadb

client = chromadb.HttpClient(
    host="<host>",
    port=443,
    ssl=True,
    headers={"Authorization": "Bearer <token>"},
)

collection = client.get_or_create_collection(name="docs")

collection.add(
    ids=["doc-1", "doc-2"],
    documents=[
        "Ametnes provisions data services on Kubernetes.",
        "Vector databases store embeddings for semantic search.",
    ],
    metadatas=[
        {"source": "handbook"},
        {"source": "handbook"},
    ],
)

results = collection.query(
    query_texts=["Which service stores embeddings?"],
    n_results=2,
)

print(results["documents"])

ChromaDB 1.x uses the default_tenant tenant and default_database database when the client does not specify them. Use explicit tenant= and database= arguments to isolate applications.

Architectures#

The 1.5 catalog uses a single node with a single data volume for every tier. Requests are half of the limits.

Architecture Nodes CPU / memory Storage ACU
Starter 1 1 CPU / 2Gi 10Gi 2
Small 1 2 CPU / 4Gi 25Gi 4
Basic 1 2 CPU / 4Gi 50Gi 4
Medium 1 4 CPU / 8Gi 100Gi 8
Large 1 8 CPU / 16Gi 250Gi 16
XLarge 1 16 CPU / 32Gi 500Gi 32
2XLarge 1 24 CPU / 64Gi 1000Gi 64
3XLarge 1 32 CPU / 96Gi 2000Gi 96
4XLarge 1 48 CPU / 128Gi 4000Gi 128

The older service/chromadb:1.4 kind does not use architecture tiers. Choose Nodes (1), then set CPU, Memory and Storage within the catalog limits: up to 8 CPU, 32Gi memory and 1TiB storage.

Scale#

Use Modify Resource in the console to move to a larger architecture on the 1.5 catalog. ChromaDB tiers keep the same single-node topology, so a tier change resizes CPU and memory without changing the number of nodes. The data volume keeps its current size unless you change the service's storage value.

The 1.5 and 1.4 release series are separate kinds. Use 1.5 for new deployments; keep 1.4 only for existing services that depend on its manual sizing.

Validation checklist#

  • ChromaDB resource status is ready in Ametnes Platform.
  • GET https://<host>/api/v2/heartbeat succeeds with the bearer token.
  • The Python client connects and returns a heartbeat.
  • You can create a collection, add documents and query it by text.

Next#