Kubernetes Deployment with Helm

Deploy Cognee on Kubernetes using the chart in deployment/helm for enterprise-grade deployments with full control over configuration and resources. Kubernetes deployment provides container orchestration, auto-healing, and declarative configuration for production workloads. The chart deploys the Cognee API together with a bundled PostgreSQL + pgvector database. Relational metadata and vectors both live in that Postgres instance — the chart does not bundle Neo4j or Qdrant.

Cognee runs as a single-replica deployment. The API pod is a single process with process-local locks and caches, so running multiple replicas against the same stores is not supported — do not enable horizontal autoscaling or set replicaCount above 1. The chart prints a warning after install when replicaCount > 1. Scale vertically (more CPU/memory per pod) instead.

Why Kubernetes + Helm?

Enterprise Ready

Resource requests/limits, a restricted security context, and a dedicated ServiceAccount ship as defaults

Auto-Healing

Startup and readiness probes keep traffic away from a pod until its dependencies are reachable

Validated Values

values.schema.json validates your values before anything is applied to the cluster

GitOps Integration

Version-controlled infrastructure with automated deployment pipelines

Prerequisites

Kubernetes Cluster

You need a running Kubernetes cluster:

Local: Minikube, Kind, or Docker Desktop
Cloud: GKE, EKS, AKS, or DigitalOcean Kubernetes
On-premise: Self-managed Kubernetes cluster

The chart targets Kubernetes 1.25+ and Helm 3.10+.

Install Tools

# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install kubectl /usr/local/bin/

# Install Helm
curl https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz | tar xz
sudo mv linux-amd64/helm /usr/local/bin/

# Verify installations
kubectl version --client
helm version

Configure Access

# Test cluster connectivity
kubectl cluster-info
kubectl get nodes

Quick Deployment

Clone Repository

git clone https://github.com/topoteretes/cognee.git
cd cognee

Create the credentials Secret

Credentials are kept out of values.yaml. Create a Secret holding LLM_API_KEY and DB_PASSWORD, and point the chart at it with existingSecret:

kubectl create namespace cognee

kubectl create secret generic cognee-credentials \
  --namespace cognee \
  --from-literal=LLM_API_KEY="sk-..." \
  --from-literal=DB_PASSWORD="strongpassword"

If you skip this step, the chart renders its own Secret from postgres.auth.password with an empty LLM_API_KEY. That is a development convenience only — the post-install notes print the kubectl patch command to fill the key in.

Configure Values

Create a values.yaml file to customize your deployment. Only keys that exist in the chart are accepted:

# values.yaml
replicaCount: 1   # Cognee is single-process; keep a single replica

image:
  repository: cognee/cognee
  tag: main
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8000

cognee:
  env: local
  llmProvider: openai
  llmModel: openai/gpt-4o-mini
  vectorDbProvider: pgvector
  enableBackendAccessControl: false

# Secret holding LLM_API_KEY and DB_PASSWORD
existingSecret: cognee-credentials

postgres:
  auth:
    username: cognee
    database: cognee_db
    password: ""      # unused when existingSecret is set
  storage: 2Gi

The chart ships a values.schema.json with additionalProperties: false, so unknown keys fail the install before anything reaches the cluster. Keys such as cognee.image, cognee.replicas, cognee.env.OPENAI_API_KEY, postgresql, neo4j, qdrant, monitoring, and networkPolicy are not part of this chart and will be rejected with a values don't meet the specifications of the schema error. The schema also constrains image.pullPolicy to Always/Never/IfNotPresent, service.type to ClusterIP/NodePort/LoadBalancer, and ports to 1–65535.

Deploy with Helm

# Install the Helm chart
helm upgrade --install cognee ./deployment/helm \
  --namespace cognee --create-namespace \
  -f values.yaml

# Check deployment status
kubectl get pods -n cognee -l app.kubernetes.io/instance=cognee
kubectl get services -n cognee

Verify Deployment

# Check pod status
kubectl get pods -n cognee

# View logs
kubectl logs -n cognee -l app.kubernetes.io/name=cognee-chart -f

# Test connectivity
kubectl port-forward svc/cognee-cognee-chart -n cognee 8000:8000
curl http://localhost:8000/health

Resource names are <release>-<chart> unless you set nameOverride / fullnameOverride, so a release named cognee produces cognee-cognee-chart and cognee-cognee-chart-postgres.

Values Reference

Key	Default	Description
`replicaCount`	`1`	Number of Cognee replicas. Keep at 1 — see the single-replica warning above.
`nameOverride` / `fullnameOverride`	`""`	Override generated resource names
`image.repository`	`cognee/cognee`	Cognee image repository
`image.tag`	`main`	Image tag
`image.pullPolicy`	`IfNotPresent`	`Always`, `Never`, or `IfNotPresent`
`service.type`	`ClusterIP`	`ClusterIP`, `NodePort`, or `LoadBalancer`
`service.port`	`8000`	Service and container port
`cognee.env`	`local`	Runtime environment (`ENV`)
`cognee.llmProvider`	`openai`	LLM provider (`LLM_PROVIDER`)
`cognee.llmModel`	`openai/gpt-4o-mini`	LLM model (`LLM_MODEL`)
`cognee.vectorDbProvider`	`pgvector`	Vector store (`VECTOR_DB_PROVIDER`)
`cognee.enableBackendAccessControl`	`false`	Multi-tenant access control (`ENABLE_BACKEND_ACCESS_CONTROL`)
`existingSecret`	`""`	Name of an existing Secret with `LLM_API_KEY` and `DB_PASSWORD`
`resources.requests`	`500m` CPU / `512Mi`	Cognee container requests
`resources.limits`	`4000m` CPU / `2Gi`	Cognee container limits
`serviceAccount.create`	`true`	Create a dedicated ServiceAccount
`serviceAccount.name`	`""`	Override the ServiceAccount name
`serviceAccount.automountServiceAccountToken`	`false`	Mount the API token into the pod
`podSecurityContext`	`{}`	Pod-level security context
`securityContext`	`allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`	Container security context
`startupProbe.enabled`	`true`	HTTP `GET /health`, `failureThreshold: 30`, `periodSeconds: 10`
`readinessProbe.enabled`	`true`	HTTP `GET /health`, `initialDelaySeconds: 10`, `periodSeconds: 10`
`livenessProbe.enabled`	`false`	Intentionally disabled — see Health & Probes
`postgres.image.repository` / `.tag`	`pgvector/pgvector` / `pg17`	Bundled Postgres image
`postgres.port`	`5432`	Postgres port
`postgres.auth.username` / `.database`	`cognee` / `cognee_db`	Postgres user and database
`postgres.auth.password`	`""`	Dev-only password; ignored when `existingSecret` is set
`postgres.storage`	`2Gi`	PVC size for Postgres data
`postgres.resources.requests`	`250m` CPU / `256Mi`	Postgres requests
`postgres.resources.limits`	`1000m` CPU / `1Gi`	Postgres limits

If you change service.port, set startupProbe.httpGet.port and readinessProbe.httpGet.port to match — the probe ports are separate values and default to 8000.

Architecture Components

Application Tier
Data Tier
Infrastructure

Cognee Services

Cognee API: single-replica Deployment running image.repository:image.tag
Service: ClusterIP on service.port (8000) by default
ServiceAccount: created by default with automountServiceAccountToken: false

Database Services

PostgreSQL + pgvector (pgvector/pgvector:pg17): a single-replica Deployment backed by a PersistentVolumeClaim (postgres.storage), serving both relational metadata and vectors
Probes: pg_isready drives the Postgres startup, readiness, and liveness probes
No graph-database provider is set in the ConfigMap, so Cognee falls back to its embedded default (Ladybug) inside the API container

Supporting Services

ConfigMap: non-sensitive runtime configuration, including DB_PROVIDER: postgres, DB_HOST/DB_PORT/DB_NAME/DB_USERNAME for the bundled database, and VECTOR_DB_PROVIDER
Secret: LLM_API_KEY and DB_PASSWORD, either pre-created (existingSecret) or rendered by the chart for development
Checksum annotations: the Deployment carries checksum/config and checksum/secret, computed from the chart-rendered ConfigMap and Secret, so values changes that alter either one trigger a rolling restart. An existingSecret is not rendered by the chart, so rotating it requires a manual kubectl rollout restart

Database Configuration

The ConfigMap pins DB_PROVIDER: postgres explicitly, so the API always talks to the bundled Postgres service rather than silently falling back to SQLite. DB_HOST is derived from the chart’s Postgres service name, and DB_PORT, DB_NAME, and DB_USERNAME follow postgres.port and postgres.auth.*. DB_PASSWORD comes only from the Secret. VECTOR_DB_PROVIDER defaults to pgvector, which is why the bundled image is pgvector/pgvector:pg17 — embeddings are stored in the same database.

To run against an external database instead of the bundled one, override the environment through your own ConfigMap/Secret layer or a chart fork; the shipped chart always deploys and points at its own Postgres.

Production Configuration

Credentials with existingSecret

Create the Secret outside Helm (kubectl, External Secrets, Vault, …), then reference it:

kubectl create secret generic cognee-credentials \
  --namespace cognee \
  --from-literal=LLM_API_KEY="sk-..." \
  --from-literal=DB_PASSWORD="strongpassword"

helm upgrade --install cognee ./deployment/helm \
  --namespace cognee --create-namespace \
  --set existingSecret="cognee-credentials" \
  --set postgres.auth.password=""

Both the Cognee Deployment and the Postgres Deployment read their credentials from this Secret, so the database password and the API’s DB_PASSWORD cannot drift apart. Helm never renders this Secret, so the checksum annotations do not notice updates to it — after rotating it, restart the pods explicitly (see Rotating credentials below).

Resources

Defaults are set for both containers; raise them for production workloads:

resources:
  requests:
    cpu: "1000m"
    memory: "2Gi"
  limits:
    cpu: "4000m"
    memory: "4Gi"

postgres:
  storage: 100Gi
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2000m"
      memory: "4Gi"

Security Context & ServiceAccount

The container security context defaults to allowPrivilegeEscalation: false with all Linux capabilities dropped, and the chart’s ServiceAccount does not mount an API token. Add pod-level settings as needed:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: false
  capabilities:
    drop:
      - ALL

serviceAccount:
  create: true
  name: ""
  automountServiceAccountToken: false

Set serviceAccount.create: false and serviceAccount.name to reuse an existing account (for example one bound to a cloud IAM role).

Probe tuning

startupProbe:
  enabled: true
  httpGet:
    path: /health
    port: 8000
  failureThreshold: 30   # up to 5 minutes at periodSeconds: 10
  periodSeconds: 10

readinessProbe:
  enabled: true
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 10

Increase startupProbe.failureThreshold if first boot (image pull plus database initialization) regularly takes longer than five minutes.

Health & Probes

The chart wires GET /health to a startup probe and a readiness probe. The startup probe allows up to 30 attempts, 10 seconds apart, before the pod is failed; the readiness probe then polls every 10 seconds after a 10 second delay and pulls the pod out of the Service whenever its dependencies are unhealthy.

livenessProbe is disabled by default and should stay that way with the current endpoint. /health verifies external dependencies — database, vector store, graph store, filesystem — so wiring it to liveness makes Kubernetes restart the pod during transient dependency outages, producing CrashLoopBackOff instead of letting the pod recover. Enable liveness only against a process-only endpoint that reports whether the process itself is alive.

Postgres uses pg_isready for its startup, readiness, and liveness probes, so the API’s readiness naturally follows the database coming up.

Upgrading from an Earlier Chart

Move credentials into a Secret

Inline API keys in values.yaml are no longer part of the values surface. Create a Secret with LLM_API_KEY and DB_PASSWORD and set existingSecret.

Rename your values keys

The values structure is flat: image.*, service.*, replicaCount, resources.requests/limits, and postgres.auth.*. Older layouts such as cognee.image, cognee.port, cognee.env.<VAR>, and cognee.resources.cpu are rejected by the schema.

Review database behavior

DB_PROVIDER is now pinned to postgres in the ConfigMap. Deployments that previously ran on the implicit SQLite fallback will start against Postgres and see an empty knowledge base.

Dry-run before applying

helm upgrade cognee ./deployment/helm -n cognee -f values.yaml --dry-run

Schema violations surface here rather than mid-rollout.

Scaling & Performance

Cognee scales vertically: give the single API pod more CPU and memory rather than adding replicas. Horizontal Pod Autoscaling is not supported — multiple Cognee pods writing to the same stores is not a supported configuration, and the chart warns after install when replicaCount > 1.

Vertical Pod Autoscaler

# VPA configuration
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: cognee-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: cognee-cognee-chart
  updatePolicy:
    updateMode: "Auto"

Scale the database, not the app

Give the bundled Postgres more CPU, memory, and PVC space through postgres.resources and postgres.storage, or run a managed Postgres alongside a chart fork.

Maintenance Operations

Updates & Rollbacks

# Update deployment
helm upgrade cognee ./deployment/helm -n cognee -f values.yaml

# Check rollout status
kubectl rollout status deployment/cognee-cognee-chart -n cognee

# Rollback if needed
helm rollback cognee 1 -n cognee

Rotating credentials

# Update the Secret in place
kubectl create secret generic cognee-credentials -n cognee \
  --from-literal=LLM_API_KEY="sk-new..." \
  --from-literal=DB_PASSWORD="newpassword" \
  --dry-run=client -o yaml | kubectl apply -f -

# Restart the pods — the checksum annotations track only the
# chart-rendered Secret, not an existingSecret managed outside Helm
kubectl rollout restart -n cognee \
  deployment/cognee-cognee-chart \
  deployment/cognee-cognee-chart-postgres

Changing DB_PASSWORD after Postgres has been initialized does not change the password already stored in the database volume — rotate it inside Postgres as well, or reinitialize the volume.

Health Monitoring

# Check pod health and probe events
kubectl describe pods -n cognee -l app.kubernetes.io/instance=cognee

# View resource usage
kubectl top pods -n cognee
kubectl top nodes

# Check service endpoints
kubectl get endpoints -n cognee

Troubleshooting

Values Rejected
Pod Not Ready
LLM Calls Failing
Database Issues

values don't meet the specifications of the schemaThe chart validates values against values.schema.json before rendering. The message names the offending path — most often an unknown top-level key or a key from an older values layout.

# Validate without touching the cluster
helm template cognee ./deployment/helm -f values.yaml

# Compare against the shipped defaults
helm show values ./deployment/helm

Startup or readiness probe failing

# Probe failures show up as events
kubectl describe pod <pod-name> -n cognee
kubectl logs <pod-name> -n cognee --previous

A pod that never becomes ready usually means /health cannot reach Postgres. Check that the Postgres pod is ready and that DB_PASSWORD in the Secret matches the password Postgres was initialized with.

Empty LLM_API_KEYWithout existingSecret, the chart-rendered Secret contains an empty LLM_API_KEY. Patch it, or reinstall with existingSecret:

kubectl patch secret cognee-cognee-chart-secret -n cognee \
  --type=merge \
  -p '{"data":{"LLM_API_KEY":"'$(echo -n "sk-..." | base64)'"}}'

Connection Problems

# Test database connectivity — psql ships in the Postgres container,
# not in the API image
kubectl exec -it deploy/cognee-cognee-chart-postgres -n cognee -- \
  psql -U cognee -d cognee_db -c "SELECT 1;"

# Check service DNS resolution from the API pod
kubectl exec -it <cognee-pod> -n cognee -- \
  sh -c 'getent hosts cognee-cognee-chart-postgres'

Uninstalling

Remove Helm Release

helm uninstall cognee -n cognee

Clean Up Resources

# Remove the Postgres volume (if desired)
kubectl delete pvc cognee-cognee-chart-postgres-pvc -n cognee

# Remove a pre-created credentials Secret
kubectl delete secret cognee-credentials -n cognee

Uninstalling will permanently delete all data unless you have backups. Ensure you have proper backup procedures in place.

Next Steps

Monitoring Setup

Observability StackThe chart does not ship ServiceMonitor or dashboard resources — wire Prometheus and Grafana in through your own manifests.

CI/CD Integration

GitOps DeploymentSet up automated deployments with ArgoCD or Flux.

Need Help?

Join our community for Kubernetes deployment support and production best practices.

Self-Hosting

Kubernetes (Helm)

Kubernetes Deployment with Helm

Why Kubernetes + Helm?

Enterprise Ready

Auto-Healing

Validated Values

GitOps Integration

Prerequisites

Quick Deployment

Values Reference

Architecture Components

Database Configuration

Production Configuration

Health & Probes

Upgrading from an Earlier Chart

Scaling & Performance

Maintenance Operations

Troubleshooting

Uninstalling

Next Steps

Monitoring Setup

CI/CD Integration

Need Help?

​Kubernetes Deployment with Helm

​Why Kubernetes + Helm?

Enterprise Ready

Auto-Healing

Validated Values

GitOps Integration

​Prerequisites

​Quick Deployment

​Values Reference

​Architecture Components

​Database Configuration

​Production Configuration

​Health & Probes

​Upgrading from an Earlier Chart

​Scaling & Performance

​Maintenance Operations

​Troubleshooting

​Uninstalling

​Next Steps

Monitoring Setup

CI/CD Integration

Need Help?

Kubernetes Deployment with Helm

Why Kubernetes + Helm?

Prerequisites

Quick Deployment

Values Reference

Architecture Components

Database Configuration

Production Configuration

Health & Probes

Upgrading from an Earlier Chart

Scaling & Performance

Maintenance Operations

Troubleshooting

Uninstalling

Next Steps