DocumentationNeuronDB Cloud-Native
Documentation Branch: You are viewing documentation for the main branch (3.0.0-devel). Select a branch to view its documentation:
main (3.0.0-devel) - LatestREL2_STABLE (2.0.0) - StableREL1_STABLE (1.0.0) - StableGitHub Repository →

Kubernetes Deployment with Helm

Overview

The NeuronDB Helm chart provides a production-ready, cloud-native deployment of the entire NeuronDB ecosystem on Kubernetes. This includes:

  • NeuronDB - PostgreSQL with NeuronDB extension (StatefulSet with persistent storage)
  • NeuronAgent - AI agent service (Deployment with HPA)
  • NeuronMCP - Model Context Protocol server (Deployment)
  • NeuronDesktop - Web UI (API + Frontend Deployments)
  • Observability Stack - Prometheus, Grafana, and Jaeger

✨ Key Features

  • High Availability: Pod Disruption Budgets, multiple replicas, health checks
  • Auto-scaling: Horizontal Pod Autoscaling for NeuronAgent
  • Security: ServiceAccounts, Network Policies, Secrets management
  • Observability: Complete monitoring stack with Prometheus, Grafana, and Jaeger
  • Storage: Persistent volumes with configurable storage classes
  • Ingress: TLS-enabled external access

Quick Start

Get NeuronDB running on Kubernetes in minutes:

1. Prerequisites

Verify prerequisites

# Kubernetes cluster (1.24+)
kubectl version --client --short

# Helm 3.8+
helm version

# Check cluster access
kubectl cluster-info

# List available storage classes
kubectl get storageclass

2. Create Namespace and Secret

Setup namespace and password

# Create namespace
kubectl create namespace neurondb

# Generate secure password
POSTGRES_PASSWORD=$(openssl rand -base64 32)

# Create secret (or use Helm values.yaml)
kubectl create secret generic neurondb-secrets \
  --from-literal=postgres-password="$POSTGRES_PASSWORD" \
  --namespace=neurondb

3. Install Helm Chart

Install NeuronDB from repository

# Clone repository
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb

# Install chart
helm install neurondb ./helm/neurondb \
  --namespace neurondb \
  --create-namespace \
  --set secrets.postgresPassword="$POSTGRES_PASSWORD"

4. Verify Installation

Check deployment status

# Wait for pods to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=neurondb -n neurondb --timeout=300s

# Check all pods
kubectl get pods -n neurondb

# Check services
kubectl get svc -n neurondb

# Check persistent volumes
kubectl get pvc -n neurondb

5. Access Services

Port-forward to services

# NeuronDesktop UI
kubectl port-forward svc/neurondb-neurondesktop-frontend 3000:3000 -n neurondb
# Access at: http://localhost:3000

# NeuronAgent API
kubectl port-forward svc/neurondb-neuronagent 8080:8080 -n neurondb

# Grafana
kubectl port-forward svc/neurondb-grafana 3001:3000 -n neurondb
# Access at: http://localhost:3001 (admin/admin)

# Prometheus
kubectl port-forward svc/neurondb-prometheus 9090:9090 -n neurondb
# Access at: http://localhost:9090

Architecture

The Helm chart deploys the complete NeuronDB ecosystem with the following resource types:

Components

  • StatefulSet: NeuronDB (PostgreSQL) with persistent storage
  • Deployments: NeuronAgent, NeuronMCP, NeuronDesktop API/Frontend
  • Services: ClusterIP for internal communication
  • Ingress: Optional external access with TLS
  • ConfigMaps: Configuration files
  • Secrets: Passwords and API keys
  • PVCs: Persistent volumes for database and monitoring data
  • HPA: Horizontal Pod Autoscaling for NeuronAgent
  • PDB: Pod Disruption Budgets for high availability
  • NetworkPolicy: Optional network security

Observability Stack

  • Prometheus: Metrics collection and alerting
  • Grafana: Pre-configured dashboards and visualization
  • Jaeger: Distributed tracing
  • ServiceMonitors: Automatic service discovery for Prometheus
  • PrometheusRules: Alert rules for all components

Installation

Basic Installation

Install with default values

helm install neurondb ./helm/neurondb \
  --namespace neurondb \
  --create-namespace \
  --set secrets.postgresPassword="$(openssl rand -base64 32)"

Production Installation

Create a values file for production:

production-values.yaml

# production-values.yaml
neurondb:
  persistence:
    size: 100Gi
    storageClass: "fast-ssd"
  resources:
    limits:
      memory: "16Gi"
      cpu: "8"

neuronagent:
  replicas: 3
  autoscaling:
    enabled: true
    maxReplicas: 20

monitoring:
  enabled: true
  prometheus:
    retention: "90d"
  grafana:
    adminPassword: "change-me-in-production"

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: neurondb.example.com
  tls:
    - secretName: neurondb-tls
      hosts:
        - neurondb.example.com

Install with production values

helm install neurondb ./helm/neurondb \
  --namespace neurondb \
  --create-namespace \
  --values production-values.yaml \
  --set secrets.postgresPassword="$(openssl rand -base64 32)"

Development Installation

Minimal development setup

helm install neurondb ./helm/neurondb \
  --namespace neurondb-dev \
  --create-namespace \
  --set neurondb.persistence.size=10Gi \
  --set neuronagent.replicas=1 \
  --set monitoring.enabled=false \
  --set secrets.postgresPassword="dev-password"

Configuration

Key Configuration Options

See helm/neurondb/values.yaml for all available options. Key sections:

NeuronDB (PostgreSQL)

  • Image repository and tag
  • Database credentials and port
  • Persistent volume size and storage class
  • Resource requests and limits
  • PostgreSQL configuration

NeuronAgent

  • Replica count
  • Horizontal Pod Autoscaling (min/max replicas, target CPU)
  • Log level and environment variables
  • Resource limits

Monitoring

  • Enable/disable Prometheus, Grafana, Jaeger
  • Prometheus retention period
  • Grafana admin password and dashboards
  • Storage for monitoring data

Ingress

  • Enable/disable ingress
  • Ingress controller class
  • Hostnames and paths
  • TLS certificate configuration

📋 Complete Configuration: See helm/neurondb/values.yaml and Kubernetes Helm Guide for detailed configuration options.

Monitoring & Observability

The Helm chart includes a complete observability stack with Prometheus, Grafana, and Jaeger pre-configured.

Prometheus Metrics

All services expose Prometheus-compatible metrics:

  • NeuronAgent: http://neurondb-neuronagent:8080/metrics
  • NeuronDesktop API: http://neurondb-neurondesktop-api:8081/metrics
  • NeuronDB: Via PostgreSQL exporter

Grafana Dashboards

Grafana is pre-configured with:

  • Prometheus datasource
  • Default dashboard provisioning
  • Custom dashboards for service health, request rates, latencies, and resource utilization

Jaeger Tracing

Distributed tracing is available at:

  • UI: Port 16686
  • OTLP gRPC: Port 4317
  • OTLP HTTP: Port 4318

For detailed observability setup, see Observability Stack documentation.

Scaling & High Availability

Horizontal Pod Autoscaling

NeuronAgent supports automatic scaling based on CPU utilization:

Check HPA status

kubectl get hpa -n neurondb

# Manually scale
kubectl scale deployment neurondb-neuronagent --replicas=5 -n neurondb

High Availability

  • Pod Disruption Budgets: Ensure minimum availability during updates
  • Multiple Replicas: Configurable for all services
  • Health Checks: Liveness and readiness probes for all pods
  • Init Containers: Wait for database before starting services

Pod Anti-Affinity

Configure pod anti-affinity to distribute pods across nodes for better resilience.

Upgrading

Upgrade to New Version

Upgrade Helm release

# Update values if needed
helm upgrade neurondb ./helm/neurondb \
  --namespace neurondb \
  --values my-values.yaml \
  --set neurondb.image.tag="2.0.0-pg17-cpu"

Rollback

Rollback if needed

# List releases
helm list -n neurondb

# Rollback to previous version
helm rollback neurondb -n neurondb

# Rollback to specific revision
helm rollback neurondb 2 -n neurondb

Troubleshooting

Check Pod Status

Diagnose pod issues

# Get pod status
kubectl get pods -n neurondb

# Describe pod
kubectl describe pod <pod-name> -n neurondb

# View logs
kubectl logs <pod-name> -n neurondb

# View previous container logs (if crashed)
kubectl logs <pod-name> -n neurondb --previous

Database Connection Issues

Verify database connectivity

# Check NeuronDB pod
kubectl get pod -n neurondb -l app.kubernetes.io/component=neurondb

# Test connection
kubectl exec -it -n neurondb \
  $(kubectl get pod -n neurondb -l app.kubernetes.io/component=neurondb -o jsonpath='{.items[0].metadata.name}') \
  -- psql -U neurondb -d neurondb -c "SELECT neurondb.version();"

Storage Issues

Check persistent volumes

# Check PVC status
kubectl get pvc -n neurondb

# Check storage class
kubectl get storageclass

# Describe PVC if pending
kubectl describe pvc <pvc-name> -n neurondb

Resource Issues

Monitor resource usage

# View resource requests/limits
kubectl describe pod <pod-name> -n neurondb | grep -A 5 "Limits\|Requests"

# Check node resources
kubectl top nodes
kubectl top pods -n neurondb

Uninstalling

Remove deployment

# Uninstall Helm release
helm uninstall neurondb -n neurondb

# Delete namespace (removes all resources)
kubectl delete namespace neurondb

# ⚠️ WARNING: This deletes all data in PVCs!
# Backup data before uninstalling if needed

Additional Resources

  • CLOUD_NATIVE.md - Complete cloud-native deployment guide with architecture, configuration, and best practices
  • Kubernetes Helm Guide - Detailed deployment guide with troubleshooting and advanced configuration
  • Helm Chart - Chart source code, README, and values files
  • Observability Stack - Prometheus, Grafana, and Jaeger setup with metrics and alerting
  • Operational Scripts - Automation scripts for deployments, database operations, and monitoring
PreviousAnsible Infrastructure Provisioning
NextObservability Stack