@r8s/chromadb 0.2.0

package/__tests__/chromadb.test.ts

@@ -0,0 +1,374 @@
+import { describe, it, expect } from 'vitest'
+import { render, jsx } from '@r8s/core'
+import { OperatorContext, SecretContext, RoutingContext } from '@r8s/core/defaults'
+import { runGuardrails, noPlaintextSecrets, validateResource } from '@r8s/core'
+import { operators } from '@r8s/crds'
+import type { r8sElement } from '@r8s/core'
+
+// ChromaDb recipe tests:
+//   1. Operator declarations (deduped via OperatorContext)
+//   2. Rendering: defaults, all props, gateway/ingress adaptation
+//   3. Security: no plaintext credentials in rendered output
+import { ChromaDb } from '../src/index'
+
+/** Render ChromaDb inside a Platform-like secrets backend (OpenBao). */
+function renderChromaDb(props: Record<string, unknown>): ReturnType<typeof render> {
+  return render(
+    jsx(SecretContext.Provider, {
+      value: { backend: 'openbao', mount: 'kv', path: 'test' },
+      children: jsx(ChromaDb, props as never),
+    })
+  )
+}
+
+/** Render ChromaDb wrapped only in an OperatorContext (no secrets backend). */
+function renderChromaDbWithContext(operators_: any[], props: Record<string, unknown>): r8sElement {
+  return jsx(OperatorContext.Provider, {
+    value: operators_,
+    children: jsx(ChromaDb, props as never),
+  })
+}
+
+const openbao = { backend: 'openbao', mount: 'kv', path: 'test' }
+
+describe('operator declarations', () => {
+  it('declares the cnpg operator via the Database recipe when pg is enabled', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', pg: true })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(true)
+  })
+
+  it('requires no cnpg operator without pg', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com' })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(false)
+  })
+
+  it('deduplicates operators provided via context', () => {
+    const result = render(
+      renderChromaDbWithContext([operators['cnpg']()], {
+        host: 'vectors.example.com',
+        pg: true,
+      })
+    )
+    const names = result.operators.map((op) => op.name)
+    expect(names.filter((n) => n === 'cnpg')).toHaveLength(1)
+  })
+
+  it('allows version overrides through context operators', () => {
+    const result = render(
+      renderChromaDbWithContext([operators['cnpg']('1.26.0')], {
+        host: 'vectors.example.com',
+        pg: true,
+      })
+    )
+    const cnpg = result.operators.filter((op) => op.name === 'cnpg')
+    expect(cnpg).toHaveLength(1)
+    expect(cnpg[0].version).toBe('1.26.0')
+  })
+})
+
+describe('rendering defaults', () => {
+  it('renders PVC, deployment, service and endpoint', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('PersistentVolumeClaim')
+    expect(kinds).toContain('Deployment')
+    expect(kinds).toContain('Service')
+    expect(kinds).toContain('Ingress')
+    expect(kinds).not.toContain('Cluster')
+  })
+
+  it('defaults to a single replica (RWO-safe)', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com' })
+    const deployment = result.resources.find(
+      (r) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    expect(deployment.spec.replicas).toBe(1)
+  })
+
+  it('renders the data PVC with the requested storage', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com' })
+    const pvc = result.resources.find((r) => r.kind === 'PersistentVolumeClaim') as any
+    expect(pvc.metadata.name).toBe('chromadb-data')
+    expect(pvc.spec.resources.requests.storage).toBe('50Gi')
+  })
+
+  it('wires the v2 heartbeat health checks on port 8000', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com' })
+    const deployment = result.resources.find(
+      (r) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const container = deployment.spec.template.spec.containers[0]
+    expect(container.livenessProbe.httpGet.path).toBe('/api/v2/heartbeat')
+    expect(container.livenessProbe.httpGet.port).toBe(8000)
+    expect(container.readinessProbe.httpGet.path).toBe('/api/v2/heartbeat')
+    expect(container.ports[0].containerPort).toBe(8000)
+    expect(container.volumeMounts).toContainEqual({ name: 'data', mountPath: '/data' })
+    expect(deployment.spec.template.spec.volumes[0].persistentVolumeClaim.claimName).toBe(
+      'chromadb-data'
+    )
+  })
+
+  it('supports the probePath prop for older v1-API images', () => {
+    const result = renderChromaDb({
+      host: 'vectors.example.com',
+      probePath: '/api/v1/heartbeat',
+    })
+    const deployment = result.resources.find(
+      (r) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const container = deployment.spec.template.spec.containers[0]
+    expect(container.livenessProbe.httpGet.path).toBe('/api/v1/heartbeat')
+    expect(container.readinessProbe.httpGet.path).toBe('/api/v1/heartbeat')
+  })
+
+  it('wires CHROMA_SERVER_HTTP_PORT to the port prop on a custom port', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', port: 9000 })
+    const deployment = result.resources.find(
+      (r) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const container = deployment.spec.template.spec.containers[0]
+    const httpPort = container.env.find((e: any) => e.name === 'CHROMA_SERVER_HTTP_PORT')
+    expect(httpPort.value).toBe('9000')
+    expect(container.ports[0].containerPort).toBe(9000)
+    const service = result.resources.find(
+      (r) => r.kind === 'Service' && r.metadata.name === 'chromadb'
+    ) as any
+    expect(service.spec.ports[0].port).toBe(9000)
+  })
+
+  it('renders gateway resources when platform uses gateway routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'gateway', gatewayClassName: 'eg' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(ChromaDb, { host: 'vectors.example.com' }),
+        }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('HTTPRoute')
+    expect(kinds).not.toContain('Ingress')
+  })
+
+  it('renders a valid Ingress when platform uses ingress routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'ingress' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(ChromaDb, { host: 'vectors.example.com' }),
+        }),
+      })
+    )
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress).toBeDefined()
+    expect(ingress.spec.rules[0].host).toBe('vectors.example.com')
+    expect(ingress.spec.rules[0].http.paths[0].backend.service.port.number).toBe(8000)
+  })
+
+  it('passes resource validation', () => {
+    const result = renderChromaDb({
+      host: 'vectors.example.com',
+      pg: true,
+      autoscaling: true,
+      storageClassName: 'fast-ssd-rwx',
+      auth: true,
+      authTokenSecretName: 'chromadb-auth-token',
+    })
+    for (const resource of result.resources) {
+      expect(validateResource(resource)).toEqual([])
+    }
+  })
+})
+
+describe('rendering with all props', () => {
+  it('accepts the full prop surface', () => {
+    const result = renderChromaDb({
+      name: 'vectors',
+      namespace: 'ai',
+      version: '0.6.3',
+      host: 'vectors.example.com',
+      port: 8000,
+      replicas: 3,
+      storage: '100Gi',
+      storageClassName: 'fast-ssd-rwx',
+      auth: true,
+      authTokenSecretName: 'vectors-auth-token',
+      autoscaling: true,
+      pg: true,
+      resources: {
+        requests: { memory: '1Gi', cpu: '500m' },
+        limits: { memory: '4Gi', cpu: '2000m' },
+      },
+      tls: { secretName: 'vectors-tls', clusterIssuer: 'letsencrypt-prod' },
+    })
+    const deployment = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'vectors'
+    ) as any
+    expect(deployment.spec.template.spec.containers[0].image).toBe(
+      'ghcr.io/chroma-core/chroma:0.6.3'
+    )
+    expect(deployment.spec.replicas).toBe(3)
+    expect(deployment.spec.template.spec.containers[0].resources.limits.memory).toBe('4Gi')
+
+    const pvc = result.resources.find((r) => r.kind === 'PersistentVolumeClaim') as any
+    expect(pvc.metadata.name).toBe('vectors-data')
+    expect(pvc.spec.resources.requests.storage).toBe('100Gi')
+    expect(pvc.spec.storageClassName).toBe('fast-ssd-rwx')
+
+    const hpa = result.resources.find((r) => r.kind === 'HorizontalPodAutoscaler') as any
+    expect(hpa).toBeDefined()
+    expect(hpa.spec.scaleTargetRef).toMatchObject({ kind: 'Deployment', name: 'vectors' })
+    expect(hpa.spec.minReplicas).toBe(3)
+    expect(hpa.spec.maxReplicas).toBe(9)
+    expect(hpa.spec.metrics[0].resource.target.averageUtilization).toBe(70)
+
+    const cluster = result.resources.find((r) => r.kind === 'Cluster') as any
+    expect(cluster).toBeDefined()
+    expect(cluster.metadata.name).toBe('vectors-meta')
+  })
+})
+
+describe('secrets handling', () => {
+  it('accepts an explicit authTokenSecretName without a backend', () => {
+    expect(() =>
+      render(
+        jsx(ChromaDb, {
+          host: 'vectors.example.com',
+          auth: true,
+          authTokenSecretName: 'existing-token-secret',
+        })
+      )
+    ).not.toThrow()
+  })
+
+  it('provisions the auth token through a secrets backend at <path>/<name>/auth-token', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', auth: true })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('OpenBaoStaticSecret')
+    const secret = result.resources.find((r) => r.kind === 'OpenBaoStaticSecret') as any
+    expect(secret.metadata.name).toBe('chromadb-auth-token')
+    expect(secret.spec.path).toBe('test/chromadb/auth-token')
+    expect(secret.spec.destination.name).toBe('chromadb-auth-token')
+  })
+
+  it('provisions the auth token through vault', () => {
+    const result = render(
+      jsx(SecretContext.Provider, {
+        value: { backend: 'vault', mount: 'kv', path: 'ai' },
+        children: jsx(ChromaDb, { name: 'vectors', host: 'vectors.example.com', auth: true }),
+      })
+    )
+    const secret = result.resources.find((r) => r.kind === 'VaultStaticSecret') as any
+    expect(secret).toBeDefined()
+    expect(secret.spec.path).toBe('ai/vectors/auth-token')
+    expect(secret.spec.destination.name).toBe('vectors-auth-token')
+  })
+
+  it('wires the backend-provisioned auth token via secretKeyRef', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', auth: true })
+    const deployment = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const env = deployment.spec.template.spec.containers[0].env
+    const token = env.find((e: any) => e.name === 'CHROMA_SERVER_AUTH_CREDENTIALS')
+    expect(token.valueFrom.secretKeyRef.name).toBe('chromadb-auth-token')
+    expect(token.valueFrom.secretKeyRef.key).toBe('token')
+    expect(token.value).toBeUndefined()
+  })
+
+  it('wires the auth token via secretKeyRef (never plaintext env)', () => {
+    const result = renderChromaDb({
+      host: 'vectors.example.com',
+      auth: true,
+      authTokenSecretName: 'existing-token-secret',
+    })
+    const deployment = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const env = deployment.spec.template.spec.containers[0].env
+    const token = env.find((e: any) => e.name === 'CHROMA_SERVER_AUTH_CREDENTIALS')
+    expect(token.valueFrom.secretKeyRef.name).toBe('existing-token-secret')
+    expect(token.valueFrom.secretKeyRef.key).toBe('token')
+    expect(token.value).toBeUndefined()
+  })
+
+  it('wires Postgres credentials via secretKeyRef when pg is enabled', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', pg: true })
+    const deployment = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'chromadb'
+    ) as any
+    const env = deployment.spec.template.spec.containers[0].env
+    const host = env.find((e: any) => e.name === 'CHROMA_POSTGRES_HOST')
+    const password = env.find((e: any) => e.name === 'CHROMA_POSTGRES_PASSWORD')
+    expect(host.value).toBe('chromadb-meta-rw')
+    expect(password.valueFrom.secretKeyRef.name).toBe('chromadb-meta-db-credentials')
+    expect(password.valueFrom.secretKeyRef.key).toBe('password')
+    expect(password.value).toBeUndefined()
+  })
+
+  it('provisions Postgres credentials through the openbao backend when pg is enabled', () => {
+    const result = renderChromaDb({ host: 'vectors.example.com', pg: true })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('OpenBaoStaticSecret')
+  })
+
+  it('provisions Postgres credentials through vault when pg is enabled', () => {
+    const result = render(
+      jsx(SecretContext.Provider, {
+        value: { backend: 'vault', mount: 'kv', path: 'apps' },
+        children: jsx(ChromaDb, { host: 'vectors.example.com', pg: true }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('VaultStaticSecret')
+  })
+
+  it('renders no plaintext credentials anywhere', () => {
+    const result = renderChromaDb({
+      name: 'vectors',
+      host: 'vectors.example.com',
+      replicas: 3,
+      storageClassName: 'vectors-rwx',
+      auth: true,
+      authTokenSecretName: 'vectors-auth-token',
+      autoscaling: true,
+      pg: true,
+    })
+    const { passed, errors } = runGuardrails(result.resources as any[], [noPlaintextSecrets])
+    if (!passed) {
+      console.error('Plaintext credential violations:', errors)
+    }
+    expect(passed).toBe(true)
+  })
+})
+
+describe('validation errors', () => {
+  it('throws when auth is enabled without an auth token secret or backend', () => {
+    expect(() => render(jsx(ChromaDb, { host: 'vectors.example.com', auth: true }))).toThrow(
+      /auth token/
+    )
+  })
+
+  it('throws when autoscaling on RWO storage without an RWX StorageClass', () => {
+    expect(() =>
+      renderChromaDb({
+        host: 'vectors.example.com',
+        autoscaling: true,
+        storageClassName: 'fast-ssd',
+      })
+    ).toThrow(/Multi-Attach/)
+    expect(() => renderChromaDb({ host: 'vectors.example.com', autoscaling: true })).toThrow(
+      /ReadWriteMany/
+    )
+    // Explicit RWX class names (any case) are allowed
+    expect(() =>
+      renderChromaDb({
+        host: 'vectors.example.com',
+        autoscaling: true,
+        storageClassName: 'NFS-RWX',
+      })
+    ).not.toThrow()
+  })
+})

package/examples/basic.tsx

@@ -0,0 +1,3 @@
+import { ChromaDb } from '@r8s/chromadb'
+
+export default <ChromaDb name="vectors" host="vectors.example.com" />

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@r8s/chromadb",
+  "version": "0.2.0",
+  "description": "ChromaDB vector database — persistent storage, optional Postgres metadata backend, token auth, CPU autoscaling",
+  "license": "MIT",
+  "author": "Berget AI AB",
+  "homepage": "https://r8s.berget.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berget-ai/r8s.git",
+    "directory": "packages/chromadb"
+  },
+  "bugs": "https://github.com/berget-ai/r8s/issues",
+  "keywords": [
+    "chromadb",
+    "vector-database",
+    "embeddings",
+    "rag"
+  ],
+  "r8s": {
+    "category": "AI & Embeddings"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "category": "AI & Assistants",
+  "dependencies": {
+    "@r8s/core": "^0.2.0",
+    "@r8s/crds": "^0.2.0",
+    "@r8s/k8s-types": "^0.2.0",
+    "@r8s/recipes": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,368 @@
+import { jsx, Fragment, useContext } from '@r8s/core'
+import { SecretContext } from '@r8s/core/defaults'
+import { Database, Endpoint } from '@r8s/recipes'
+
+export interface ChromaDbProps {
+  /** Resource name (defaults to 'chromadb') */
+  name?: string
+  /** Kubernetes namespace (defaults to 'default') */
+  namespace?: string
+  /** Container image tag (defaults to 'latest' — pin a version in production) */
+  version?: string
+  /** Public hostname for the vector API (required) */
+  host: string
+  /** Port Chroma listens on (defaults to 8000) */
+  port?: number
+  /**
+   * Number of replicas (defaults to 1). The embedded data PVC is
+   * ReadWriteOnce — extra replicas on other nodes cause Multi-Attach
+   * errors; scale out only with a ReadWriteMany StorageClass via
+   * `storageClassName` (required for `autoscaling`).
+   */
+  replicas?: number
+  /** Persistent storage size for the embedded data volume (defaults to '50Gi') */
+  storage?: string
+  /** StorageClass for the data PersistentVolumeClaim (optional — cluster default) */
+  storageClassName?: string
+  /**
+   * HTTP path for liveness/readiness probes (defaults to
+   * '/api/v2/heartbeat' — the current image API). Set '/api/v1/heartbeat'
+   * for older images still serving the v1 API.
+   */
+  probePath?: string
+  /** Require token authentication for the server (defaults to false) */
+  auth?: boolean
+  /**
+   * Name of an existing Secret holding key `token` — the Chroma server
+   * auth credential. Required when `auth` is true, unless a secrets
+   * backend (openbao/vault) is configured on the surrounding Platform —
+   * the backend then provisions the token at path
+   * `<path>/<name>/auth-token` (key: token). Plaintext credentials are
+   * not supported.
+   */
+  authTokenSecretName?: string
+  /** Autoscale the Deployment via a CPU-based HorizontalPodAutoscaler (defaults to false) */
+  autoscaling?: boolean
+  /** Provision a CNPG Postgres cluster as the metadata store (defaults to false) */
+  pg?: boolean
+  /** Requested resources */
+  resources?: {
+    requests?: { cpu?: string; memory?: string }
+    limits?: { cpu?: string; memory?: string }
+  }
+  /** TLS configuration (defaults to letsencrypt-prod cluster issuer) */
+  tls?: {
+    secretName: string
+    clusterIssuer: string
+  }
+}
+
+/**
+ * ChromaDB — open-source vector database for AI embeddings.
+ *
+ * @title ChromaDb
+ * @category AI & Embeddings
+ *
+ * Composes:
+ * - PersistentVolumeClaim (`<name>-data`) mounted at /data for embedded
+ *   persistence (Chroma's default persist directory in the official image)
+ * - Chroma Deployment + Service (port 8000, heartbeat health checks,
+ *   /api/v2/heartbeat by default — override with `probePath` for older
+ *   v1-API images)
+ * - Endpoint (nginx Ingress or Envoy Gateway depending on RoutingContext)
+ * - Optional CNPG Postgres cluster for the metadata store (`pg`)
+ * - Optional CPU-based HorizontalPodAutoscaler (`autoscaling`) — requires
+ *   a ReadWriteMany StorageClass (`storageClassName` ending in 'rwx')
+ * - Optional token auth (`auth`): provisioned at path
+ *   `<path>/<name>/auth-token` through the Platform secrets backend
+ *   (openbao / vault), or referenced from an existing Secret (key: token)
+ *
+ * ChromaDB has no dedicated operator — it runs as a plain Deployment.
+ *
+ * @example
+ * import { ChromaDb } from '@r8s/chromadb'
+ *
+ * export default <ChromaDb name="vectors" host="vectors.example.com" />
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { ChromaDb } from '@r8s/chromadb'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'ai' }}>
+ *     <ChromaDb
+ *       name="vectors"
+ *       host="vectors.example.com"
+ *       storage="50Gi"
+ *       replicas={2}
+ *       storageClassName="nfs-rwx"
+ *       pg
+ *       autoscaling
+ *       auth
+ *     />
+ *   </Platform>
+ * )
+ */
+export function ChromaDb(props: ChromaDbProps) {
+  const {
+    name = 'chromadb',
+    namespace = 'default',
+    version = 'latest',
+    host,
+    port = 8000,
+    replicas = 1,
+    storage = '50Gi',
+    storageClassName,
+    probePath = '/api/v2/heartbeat',
+    auth = false,
+    authTokenSecretName,
+    autoscaling = false,
+    pg = false,
+    resources = {
+      requests: { memory: '512Mi', cpu: '250m' },
+      limits: { memory: '2Gi', cpu: '1000m' },
+    },
+    tls = { secretName: `${name}-tls`, clusterIssuer: 'letsencrypt-prod' },
+  } = props
+
+  const secretProvider = useContext(SecretContext)
+  const resources_: ReturnType<typeof jsx>[] = []
+
+  const tokenSecretName = authTokenSecretName ?? `${name}-auth-token`
+
+  // --- Autoscaling coherence --------------------------------------------------
+  // The data PVC is ReadWriteOnce: a HorizontalPodAutoscaler scaling to
+  // replicas on other nodes triggers Multi-Attach errors. Scaling out is
+  // only safe on a ReadWriteMany StorageClass.
+  if (autoscaling && !(storageClassName && storageClassName.toLowerCase().endsWith('rwx'))) {
+    throw new Error(
+      `ChromaDb "${name}" cannot autoscale on ReadWriteOnce storage.\n` +
+        `\n` +
+        `The data PVC uses ReadWriteOnce — scaling to replicas beyond one node ` +
+        `triggers Kubernetes Multi-Attach errors. A HorizontalPodAutoscaler ` +
+        `needs a ReadWriteMany (RWX) StorageClass.\n` +
+        `\n` +
+        `Fix: point storageClassName at a ReadWriteMany StorageClass ` +
+        `(its name must end with 'rwx'):\n` +
+        `  <ChromaDb name="${name}" host="${host}" storageClassName="nfs-rwx" autoscaling />`
+    )
+  }
+
+  // --- Auth token — provisioned through the backend or referenced -------------
+  // The token authenticates every request to the vector store — it must
+  // never be rendered as plaintext.
+  if (auth && !authTokenSecretName) {
+    if (
+      !secretProvider ||
+      (secretProvider.backend !== 'vault' && secretProvider.backend !== 'openbao')
+    ) {
+      throw new Error(
+        `ChromaDb "${name}" requires an auth token (key: token).\n` +
+          `\n` +
+          `The CHROMA_SERVER_AUTH_CREDENTIALS token authenticates every request ` +
+          `to the vector store — it must not be rendered as plaintext.\n` +
+          `\n` +
+          `Fix: configure a secrets backend on the Platform holding the token ` +
+          `at path <mount-path>/${name}/auth-token:\n` +
+          `  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'ai' }}>\n` +
+          `    <ChromaDb name="${name}" host="${host}" auth={true} />\n` +
+          `  </Platform>\n` +
+          `\n` +
+          `Or reference a pre-created Secret (key: token):\n` +
+          `  <ChromaDb name="${name}" host="${host}" auth={true} authTokenSecretName="${name}-auth-token" />`
+      )
+    }
+
+    const spec = {
+      ...(secretProvider.backend === 'vault'
+        ? { vaultAuthRef: secretProvider.authRef }
+        : { openbaoAuthRef: secretProvider.authRef }),
+      mount: secretProvider.mount,
+      type: 'kv-v2' as const,
+      path: `${secretProvider.path ?? name}/${name}/auth-token`,
+      destination: { create: true, name: tokenSecretName },
+    }
+    resources_.push(
+      secretProvider.backend === 'vault'
+        ? jsx('VaultStaticSecret', {
+            apiVersion: 'secrets.hashicorp.com/v1beta1',
+            kind: 'VaultStaticSecret',
+            metadata: { name: `${name}-auth-token`, namespace },
+            spec,
+          })
+        : jsx('OpenBaoStaticSecret', {
+            apiVersion: 'secrets.openbao.org/v1beta1',
+            kind: 'OpenBaoStaticSecret',
+            metadata: { name: `${name}-auth-token`, namespace },
+            spec,
+          })
+    )
+  }
+
+  // --- Env wiring -------------------------------------------------------------
+  // Only CHROMA_* env vars — every credential arrives via secretKeyRef at
+  // runtime (pushed first so dependent $(VAR) expansion resolves).
+  const envVars: {
+    name: string
+    value?: string
+    valueFrom?: { secretKeyRef: { name: string; key: string } }
+  }[] = []
+
+  // The listener port must track the `port` prop or the server ignores it
+  // and binds the image default (8000), breaking the Service and probes.
+  envVars.push({ name: 'CHROMA_SERVER_HTTP_PORT', value: String(port) })
+
+  if (pg) {
+    // Metadata store: CNPG cluster provisioned as `${name}-meta`. Its
+    // connection info follows the Database recipe convention.
+    const dbHost = `${name}-meta-rw`
+    envVars.push(
+      { name: 'CHROMA_POSTGRES_HOST', value: dbHost },
+      { name: 'CHROMA_POSTGRES_PORT', value: '5432' },
+      { name: 'CHROMA_POSTGRES_DATABASE', value: `${name}-meta` },
+      { name: 'CHROMA_POSTGRES_USER', value: `${name}-meta` },
+      {
+        name: 'CHROMA_POSTGRES_PASSWORD',
+        valueFrom: {
+          secretKeyRef: { name: `${name}-meta-db-credentials`, key: 'password' },
+        },
+      }
+    )
+  }
+
+  if (auth) {
+    envVars.push(
+      {
+        name: 'CHROMA_SERVER_AUTH_CREDENTIALS',
+        valueFrom: { secretKeyRef: { name: tokenSecretName, key: 'token' } },
+      },
+      {
+        name: 'CHROMA_SERVER_AUTH_PROVIDER',
+        value: 'chromadb.auth.token.TokenAuthenticationServerProvider',
+      }
+    )
+  }
+
+  // --- Data-plane resources ----------------------------------------------------
+  // WebService cannot mount volumes, so the app runs as a raw Deployment
+  // with heartbeat probes. Chroma persists to /data by default in the
+  // official image.
+  const dataPlane: ReturnType<typeof jsx>[] = []
+
+  dataPlane.push(
+    jsx('PersistentVolumeClaim', {
+      apiVersion: 'v1',
+      kind: 'PersistentVolumeClaim',
+      metadata: { name: `${name}-data`, namespace },
+      spec: {
+        accessModes: ['ReadWriteOnce'],
+        ...(storageClassName && { storageClassName }),
+        resources: { requests: { storage } },
+      },
+    })
+  )
+
+  // --- Deployment + Service (raw jsx — WebService lacks volume mounts) --------
+  dataPlane.push(
+    jsx('Deployment', {
+      apiVersion: 'apps/v1',
+      kind: 'Deployment',
+      metadata: { name, namespace, labels: { app: name } },
+      spec: {
+        replicas,
+        selector: { matchLabels: { app: name } },
+        template: {
+          metadata: { labels: { app: name } },
+          spec: {
+            containers: [
+              {
+                name: 'chroma',
+                image: `ghcr.io/chroma-core/chroma:${version}`,
+                imagePullPolicy: 'Always',
+                ports: [{ containerPort: port }],
+                env: envVars,
+                ...(resources && { resources }),
+                volumeMounts: [{ name: 'data', mountPath: '/data' }],
+                livenessProbe: {
+                  httpGet: { path: probePath, port },
+                  initialDelaySeconds: 10,
+                  periodSeconds: 10,
+                },
+                readinessProbe: {
+                  httpGet: { path: probePath, port },
+                  initialDelaySeconds: 5,
+                  periodSeconds: 5,
+                },
+              },
+            ],
+            volumes: [{ name: 'data', persistentVolumeClaim: { claimName: `${name}-data` } }],
+          },
+        },
+      },
+    }),
+    jsx('Service', {
+      apiVersion: 'v1',
+      kind: 'Service',
+      metadata: { name, namespace },
+      spec: {
+        type: 'ClusterIP',
+        selector: { app: name },
+        ports: [{ name: 'http', port, targetPort: port, protocol: 'TCP' }],
+      },
+    })
+  )
+
+  // --- Metadata store (CNPG) — wraps the data-plane resources so connection
+  // info stays consistent with the Database recipe convention -----------------
+  if (pg) {
+    resources_.push(
+      jsx(Database, {
+        name: `${name}-meta`,
+        namespace,
+        storage: '10Gi',
+        children: jsx(Fragment, { children: dataPlane }),
+      })
+    )
+  } else {
+    resources_.push(...dataPlane)
+  }
+
+  // --- Autoscaling --------------------------------------------------------------
+  if (autoscaling) {
+    resources_.push(
+      jsx('HorizontalPodAutoscaler', {
+        apiVersion: 'autoscaling/v2',
+        kind: 'HorizontalPodAutoscaler',
+        metadata: { name: `${name}-hpa`, namespace },
+        spec: {
+          scaleTargetRef: { apiVersion: 'apps/v1', kind: 'Deployment', name },
+          minReplicas: replicas,
+          maxReplicas: replicas * 3,
+          metrics: [
+            {
+              type: 'Resource',
+              resource: {
+                name: 'cpu',
+                target: { type: 'Utilization', averageUtilization: 70 },
+              },
+            },
+          ],
+        },
+      })
+    )
+  }
+
+  // --- Endpoint ------------------------------------------------------------------
+  resources_.push(
+    <Endpoint
+      name={`${name}-endpoint`}
+      namespace={namespace}
+      host={host}
+      serviceName={name}
+      servicePort={port}
+      tls={tls}
+    />
+  )
+
+  return jsx(Fragment, { children: resources_ })
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../k8s-types" },
+    { "path": "../crds" },
+    { "path": "../recipes" }
+  ]
+}