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.
I