Skip to main content

​
Kubernetes Deployment with Helm

Deploy Cognee on Kubernetes using Helm charts for enterprise-grade, production-ready deployments with full control and high availability.
Kubernetes deployment provides container orchestration, auto-healing, and horizontal scaling for production workloads.

​
Why Kubernetes + Helm?

Enterprise Ready

Production-grade deployment with security, monitoring, and compliance

High Availability

Multi-replica deployments with automatic failover and load balancing

Resource Management

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

GitOps Integration

Version-controlled infrastructure with automated deployment pipelines

​
Prerequisites

1

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
2

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
3

Configure Access

# Test cluster connectivity
kubectl cluster-info
kubectl get nodes

​
Quick Deployment

1

Clone Repository

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

Configure Values

Create a values.yaml file to customize your deployment:
# values.yaml
cognee:
  image:
    repository: cognee/cognee
    tag: latest
    pullPolicy: Always
  
  replicas: 3
  
  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
3

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
4

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 pods (3+ replicas)
  • Worker Pods: Background processing (auto-scaling)
  • Load Balancer: Service distribution and health checks
  • Ingress: External traffic routing with SSL termination

​
Production Configuration

High Availability Setup

# Production values.yaml
cognee:
  replicas: 5
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 20
    targetCPUUtilizationPercentage: 70

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

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

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

podSecurityPolicy:
  enabled: true

# 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

1

Horizontal Pod Autoscaler

# Enable autoscaling
kubectl autoscale deployment cognee --cpu-percent=70 --min=3 --max=20

# Check HPA status
kubectl get hpa
2

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"
3

Node Autoscaling

Configure cluster autoscaling for dynamic node provisioning based on workload demands.

​
Maintenance Operations

# 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

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

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

# 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

​
Uninstalling

1

Remove Helm Release

helm uninstall cognee
2

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.