Kubernetes Deployment with Helm

Deploy Cognee on Kubernetes using Helm charts for enterprise-grade, production-ready deployments with full control over configuration and resources. Kubernetes deployment provides container orchestration, auto-healing, and declarative configuration for production workloads.

Cognee runs as a single-replica deployment. The API pod is a single process, and running multiple replicas against the same stores is not supported — do not enable horizontal autoscaling or set replicas above 1. Scale vertically (more CPU/memory per pod) instead, and use external databases (Postgres, Neo4j, Qdrant) so the pod itself stays stateless.

Why Kubernetes + Helm?

Enterprise Ready

Production-grade deployment with security, monitoring, and compliance

Auto-Healing

Failed pods are restarted automatically and health-checked continuously

Resource Management

Fine-grained control over CPU, memory, and storage allocation

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

Minimum requirements: 3 nodes, 4 CPU cores, 8GB RAM per node

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

Configure Values

Create a values.yaml file to customize your deployment:

# values.yaml
cognee:
  image:
    repository: cognee/cognee
    tag: latest
    pullPolicy: Always
  
  replicas: 1   # Cognee is single-process; keep a single replica
  
  env:
    OPENAI_API_KEY: "your-api-key"
    POSTGRES_URL: "postgresql://user:pass@postgres:5432/cognee"
    NEO4J_URL: "bolt://neo4j:password@neo4j:7687"
    QDRANT_URL: "http://qdrant:6333"

# Database configurations
postgresql:
  enabled: true
  auth:
    database: cognee
    username: cognee
    password: secure-password

neo4j:
  enabled: true
  auth:
    password: neo4j-password

qdrant:
  enabled: true

Deploy with Helm

# Install the Helm chart
helm install cognee ./deployment/helm -f values.yaml

# Check deployment status
kubectl get pods -l app=cognee
kubectl get services

Verify Deployment

# Check pod status
kubectl get pods

# View logs
kubectl logs -f deployment/cognee

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

Architecture Components

Application Tier
Data Tier
Infrastructure

Cognee Services

Cognee API: Main application pod (single replica)
Service: Stable endpoint and health checks for the API pod
Ingress: External traffic routing with SSL termination

Production Configuration

Production Resources

# Production values.yaml
cognee:
  replicas: 1   # single-process; scale vertically, not horizontally
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi

postgresql:
  primary:
    persistence:
      size: 100Gi
      storageClass: fast-ssd
  readReplicas:
    replicaCount: 2

Security Configuration

# Security settings
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

networkPolicy:
  enabled: true
  ingress:
    - from:
      - namespaceSelector:
          matchLabels:
            name: cognee-namespace

podSecurityPolicy:
  enabled: true

Monitoring & Observability

# Monitoring configuration
monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    namespace: monitoring
  
  grafana:
    dashboards:
      enabled: true
  
  prometheus:
    rules:
      enabled: true

logging:
  level: INFO
  format: json
  aggregation:
    enabled: true
    endpoint: "http://loki:3100"

Database Management

PostgreSQL

Relational Data

Persistent metadata storage
User management and permissions
Pipeline state and configuration

Neo4j

Graph Database

Knowledge graph relationships
Entity connections
Semantic network storage

Qdrant

Vector Database

Embeddings storage
Similarity search
Semantic retrieval

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.

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
  updatePolicy:
    updateMode: "Auto"

Scale the databases, not the app

Postgres read replicas, Neo4j clustering, and Qdrant replication are managed by their own charts and can scale independently of the single Cognee pod.

Maintenance Operations

Updates & Rollbacks

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

# Check rollout status
kubectl rollout status deployment/cognee

# Rollback if needed
helm rollback cognee 1

Backup & Recovery

# Database backups
kubectl create job --from=cronjob/postgres-backup backup-$(date +%Y%m%d)

# Persistent volume snapshots
kubectl apply -f backup-volumesnapshot.yaml

Health Monitoring

# Check pod health
kubectl describe pods -l app=cognee

# View resource usage
kubectl top pods
kubectl top nodes

# Check service endpoints
kubectl get endpoints

Troubleshooting

Common Issues
Database Issues
Performance Issues

Pod Failures

# Check pod status and events
kubectl describe pod <pod-name>
kubectl logs <pod-name> --previous

# Resource constraints
kubectl top pods
kubectl describe nodes

Connection Problems

# Test database connectivity
kubectl exec -it <cognee-pod> -- psql $POSTGRES_URL -c "SELECT 1;"
kubectl exec -it <neo4j-pod> -- cypher-shell -u neo4j -p password

# Check service DNS resolution
kubectl exec -it <pod> -- nslookup postgres

Resource Monitoring

# Check resource utilization
kubectl top pods --sort-by=memory
kubectl top nodes

# Review VPA recommendations
kubectl describe vpa cognee-vpa

Uninstalling

Remove Helm Release

helm uninstall cognee

Clean Up Resources

# Remove persistent volumes (if desired)
kubectl delete pvc -l app=cognee

# Remove secrets
kubectl delete secret -l app=cognee

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

Next Steps

Monitoring Setup

Observability StackConfigure Prometheus, Grafana, and alerting for production monitoring.

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

Resource Management

GitOps Integration

Prerequisites

Quick Deployment

Architecture Components

Production Configuration

Database Management

PostgreSQL

Neo4j

Qdrant

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

Resource Management

GitOps Integration

​Prerequisites

​Quick Deployment

​Architecture Components

​Production Configuration

​Database Management

PostgreSQL

Neo4j

Qdrant

​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

Architecture Components

Production Configuration

Database Management

Scaling & Performance

Maintenance Operations

Troubleshooting

Uninstalling

Next Steps