Kubernetes Installation

Deploy GoPie on Kubernetes with Helm charts for scalable production environments

Deploy GoPie on Kubernetes for highly scalable, production-grade installations using our official Helm charts.

Best For: Large-scale deployments, multi-node clusters, auto-scaling requirements, and enterprise environments.

Prerequisites

Before deploying to Kubernetes:

Kubernetes cluster 1.24+ (EKS, GKE, AKS, or self-managed)
kubectl configured to access your cluster
Helm 3.8+ installed (Install Helm)
Minimum cluster resources:
- 3 nodes with 4 vCPUs and 16GB RAM each
- 100GB persistent storage available
Optional:
- Ingress controller (Nginx, Traefik)
- cert-manager for TLS certificates
- Prometheus/Grafana for monitoring

Verify your setup:

kubectl version --client
helm version
kubectl get nodes

Quick Deployment

Add GoPie Helm Repository

# Add the GoPie Helm repository
helm repo add gopie https://charts.gopie.io
helm repo update

# Verify the chart is available
helm search repo gopie

Create Namespace and Secrets

# Create dedicated namespace
kubectl create namespace gopie

# Create secret for AI provider (choose one)
kubectl create secret generic gopie-ai-secret \
  --from-literal=openai-api-key='your-openai-key' \
  --namespace gopie

# Create secret for database
kubectl create secret generic gopie-db-secret \
  --from-literal=postgres-password='secure-password' \
  --namespace gopie

Install GoPie

Deploy with default values:

helm install gopie gopie/gopie \
  --namespace gopie \
  --set global.aiProvider.existingSecret=gopie-ai-secret \
  --set postgresql.auth.existingSecret=gopie-db-secret

Or with custom values file:

# Download values file
helm show values gopie/gopie > values.yaml

# Edit values.yaml with your configuration
helm install gopie gopie/gopie \
  --namespace gopie \
  --values values.yaml

Verify Deployment

# Check pod status
kubectl get pods -n gopie

# Check services
kubectl get svc -n gopie

# View deployment details
helm status gopie -n gopie

Configuration Options

values.yaml Structure

global:
  # Domain for your GoPie installation
  domain: gopie.example.com
  
  # Environment: development, staging, production
  environment: production
  
  # Image settings
  imageRegistry: docker.io
  imagePullSecrets: []
  
  # Security context
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000

# Service-specific settings
web:
  replicaCount: 3
  image:
    repository: factly/gopie-web
    tag: latest
    pullPolicy: IfNotPresent
  
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi
  
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 80

server:
  replicaCount: 3
  image:
    repository: factly/gopie-server
    tag: latest
  
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 2Gi

chat:
  replicaCount: 2
  image:
    repository: factly/gopie-chat
    tag: latest
  
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2000m
      memory: 4Gi

# PostgreSQL settings
postgresql:
  enabled: true
  auth:
    database: gopie
    username: gopie
    # Use existingSecret for production
    existingSecret: gopie-db-secret
    secretKeys:
      adminPasswordKey: postgres-password
      userPasswordKey: user-password
  
  primary:
    persistence:
      enabled: true
      size: 50Gi
      storageClass: gp3
    
    resources:
      requests:
        cpu: 250m
        memory: 512Mi
      limits:
        cpu: 1000m
        memory: 2Gi
  
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

# Qdrant vector database
qdrant:
  enabled: true
  persistence:
    size: 20Gi
    storageClass: gp3
  
  config:
    storage:
      wal:
        wal_capacity_mb: 2048
    service:
      grpc_port: 6334
      http_port: 6333
  
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2000m
      memory: 4Gi

# External database (if postgresql.enabled: false)
externalDatabase:
  host: ""
  port: 5432
  database: gopie
  username: gopie
  existingSecret: ""
  existingSecretPasswordKey: ""

# AI Provider Configuration
aiProvider:
  # Options: openai, anthropic, azure-openai, custom
  provider: openai
  
  # Use existing secret for API keys
  existingSecret: gopie-ai-secret
  
  # Or specify directly (not recommended for production)
  # openai:
  #   apiKey: "your-key"
  #   model: "gpt-4"
  #   maxTokens: 4096
  
  # Anthropic configuration
  # anthropic:
  #   apiKey: "your-key"
  #   model: "claude-3-opus-20240229"
  
  # Azure OpenAI
  # azureOpenai:
  #   endpoint: "https://your-resource.openai.azure.com"
  #   apiKey: "your-key"
  #   deploymentName: "gpt-4"
  
  # LiteLLM proxy for multiple providers
  litellm:
    enabled: false
    endpoint: "http://litellm-proxy:8000"

# Model configuration
models:
  chat:
    temperature: 0.7
    maxTokens: 4096
    topP: 0.9
  
  embeddings:
    model: "text-embedding-3-small"
    dimensions: 1536

# MinIO Object Storage
minio:
  enabled: true
  mode: distributed
  replicas: 4
  
  auth:
    rootUser: admin
    # Use existingSecret for production
    existingSecret: gopie-minio-secret
  
  persistence:
    enabled: true
    size: 100Gi
    storageClass: gp3
  
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 2Gi
  
  metrics:
    serviceMonitor:
      enabled: true

# External S3 (if minio.enabled: false)
externalS3:
  endpoint: "s3.amazonaws.com"
  bucket: "gopie-data"
  region: "us-east-1"
  accessKeyId: ""
  secretAccessKey: ""
  existingSecret: ""
  useSSL: true

# Ingress Configuration
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "500m"
  
  hosts:
    - host: gopie.example.com
      paths:
        - path: /
          pathType: Prefix
          service: web
        - path: /api
          pathType: Prefix
          service: server
        - path: /chat
          pathType: Prefix
          service: chat
  
  tls:
    - secretName: gopie-tls
      hosts:
        - gopie.example.com

# Service configuration
service:
  web:
    type: ClusterIP
    port: 3000
  server:
    type: ClusterIP
    port: 8000
  chat:
    type: ClusterIP
    port: 8001

Production Deployment Guide

1. Prepare Your Cluster

Install Ingress Controller

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.type=LoadBalancer

helm repo add traefik https://helm.traefik.io/traefik
helm install traefik traefik/traefik \
  --namespace traefik \
  --create-namespace \
  --set service.type=LoadBalancer

kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller/crds"
helm repo add eks https://aws.github.io/eks-charts
helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  --namespace kube-system \
  --set clusterName=your-cluster-name

Install cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create ClusterIssuer for Let's Encrypt
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

Set Up Monitoring

# Install Prometheus Stack
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace \
  --set grafana.adminPassword=your-password

2. Create Production Values

Create values-production.yaml:

global:
  domain: gopie.yourdomain.com
  environment: production
  
  # High availability settings
  podDisruptionBudget:
    enabled: true
    minAvailable: 2

# Web service configuration
web:
  replicaCount: 3
  
  # Pod affinity for distribution
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values:
              - gopie-web
          topologyKey: kubernetes.io/hostname
  
  # Health checks
  livenessProbe:
    httpGet:
      path: /api/health
      port: 3000
    initialDelaySeconds: 30
    periodSeconds: 10
  
  readinessProbe:
    httpGet:
      path: /api/ready
      port: 3000
    initialDelaySeconds: 5
    periodSeconds: 5

# Enable autoscaling
autoscaling:
  web:
    enabled: true
    minReplicas: 3
    maxReplicas: 20
    metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

# Database high availability
postgresql:
  architecture: replication
  replication:
    enabled: true
    slaveReplicas: 2
    synchronousCommit: "on"
    numSynchronousReplicas: 1
  
  backup:
    enabled: true
    cronjob:
      schedule: "0 2 * * *"
      storage:
        size: 100Gi

# Production storage
minio:
  mode: distributed
  replicas: 4
  pools: 1
  drivesPerPool: 4
  
  persistence:
    size: 500Gi
    storageClass: fast-ssd

# Security policies
networkPolicy:
  enabled: true
  ingress:
    - from:
      - namespaceSelector:
          matchLabels:
            name: gopie
      - podSelector:
          matchLabels:
            app: gopie

# Resource quotas
resourceQuota:
  enabled: true
  hard:
    requests.cpu: "100"
    requests.memory: "200Gi"
    persistentvolumeclaims: "20"

3. Deploy to Production

# Create namespace with labels
kubectl create namespace gopie
kubectl label namespace gopie name=gopie

# Create secrets
./scripts/create-secrets.sh

# Deploy GoPie
helm install gopie gopie/gopie \
  --namespace gopie \
  --values values-production.yaml \
  --timeout 10m \
  --wait

Scaling and Performance

Horizontal Pod Autoscaling

Configure HPA for dynamic scaling:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: gopie-web-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: gopie-web
  minReplicas: 3
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
      - type: Percent
        value: 100
        periodSeconds: 15

Vertical Pod Autoscaling

Enable VPA for right-sizing:

# Install VPA
kubectl apply -f https://github.com/kubernetes/autoscaler/releases/latest/download/vertical-pod-autoscaler-crd.yaml

# Create VPA resource
cat <<EOF | kubectl apply -f -
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: gopie-server-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: gopie-server
  updatePolicy:
    updateMode: "Auto"
EOF

Database Performance

Optimize PostgreSQL for Kubernetes:

postgresql:
  postgresqlConfiguration:
    shared_buffers: "2GB"
    max_connections: "200"
    effective_cache_size: "6GB"
    maintenance_work_mem: "512MB"
    checkpoint_completion_target: "0.9"
    wal_buffers: "16MB"
    default_statistics_target: "100"
    random_page_cost: "1.1"
    effective_io_concurrency: "200"
    work_mem: "10MB"
    min_wal_size: "1GB"
    max_wal_size: "4GB"

Security Hardening

Network Policies

Implement zero-trust networking:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: gopie-web-netpol
spec:
  podSelector:
    matchLabels:
      app: gopie-web
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
    ports:
    - protocol: TCP
      port: 3000
  egress:
  - to:
    - podSelector:
        matchLabels:
          app: gopie-server
    ports:
    - protocol: TCP
      port: 8000

Pod Security Standards

Apply security policies:

apiVersion: v1
kind: Namespace
metadata:
  name: gopie
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

RBAC Configuration

Create service accounts with minimal permissions:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: gopie-server
  namespace: gopie
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gopie-server-role
  namespace: gopie
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gopie-server-rolebinding
  namespace: gopie
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: gopie-server-role
subjects:
- kind: ServiceAccount
  name: gopie-server
  namespace: gopie

Monitoring and Observability

Prometheus Metrics

GoPie exposes metrics on /metrics:

serviceMonitor:
  enabled: true
  interval: 30s
  path: /metrics
  selector:
    matchLabels:
      app: gopie

Grafana Dashboards

Import GoPie dashboards:

kubectl apply -f https://raw.githubusercontent.com/factly/gopie/main/k8s/dashboards/

Log Aggregation

Configure Fluentd/Fluent Bit:

apiVersion: v1
kind: ConfigMap
metadata:
  name: fluent-bit-config
data:
  fluent-bit.conf: |
    [SERVICE]
        Flush         5
        Log_Level     info
        Daemon        off

    [INPUT]
        Name              tail
        Path              /var/log/containers/gopie-*.log
        Parser            docker
        Tag               gopie.*
        Refresh_Interval  5

    [OUTPUT]
        Name              es
        Match             gopie.*
        Host              elasticsearch
        Port              9200
        Index             gopie
        Type              _doc

Backup and Disaster Recovery

Automated Backups

Deploy Velero for cluster backups:

# Install Velero
helm repo add vmware-tanzu https://vmware-tanzu.github.io/helm-charts
helm install velero vmware-tanzu/velero \
  --namespace velero \
  --create-namespace \
  --set provider=aws \
  --set bucket=your-backup-bucket \
  --set config.region=us-east-1

# Create backup schedule
velero schedule create gopie-daily \
  --schedule="0 2 * * *" \
  --include-namespaces gopie \
  --ttl 720h

Database Backups

Configure automated PostgreSQL backups:

postgresql:
  backup:
    enabled: true
    cronjob:
      schedule: "0 */6 * * *"  # Every 6 hours
      storage:
        storageClass: gp3
        size: 100Gi
      s3:
        enabled: true
        bucket: gopie-db-backups
        region: us-east-1

Troubleshooting

Common Issues

Pods stuck in Pending state

Check for resource constraints:

kubectl describe pod <pod-name> -n gopie
kubectl get events -n gopie --sort-by='.lastTimestamp'
kubectl top nodes

Database connection errors

Verify database connectivity:

# Check PostgreSQL pod
kubectl exec -it gopie-postgresql-0 -n gopie -- pg_isready

# Test connection from app pod
kubectl exec -it <app-pod> -n gopie -- nc -zv gopie-postgresql 5432

Ingress not working

Debug ingress issues:

# Check ingress status
kubectl describe ingress gopie -n gopie

# Verify ingress controller
kubectl get pods -n ingress-nginx

# Check SSL certificate
kubectl describe certificate gopie-tls -n gopie

Useful Commands

# Get all GoPie resources
kubectl get all -n gopie

# View recent events
kubectl get events -n gopie --sort-by='.lastTimestamp'

# Check pod logs
kubectl logs -f deployment/gopie-server -n gopie

# Execute commands in pod
kubectl exec -it deployment/gopie-server -n gopie -- /bin/sh

# Port forward for debugging
kubectl port-forward svc/gopie-web 3000:3000 -n gopie

# Get Helm values
helm get values gopie -n gopie

# Upgrade deployment
helm upgrade gopie gopie/gopie -n gopie --values values.yaml

Migration from Docker Compose

Migrate existing Docker Compose deployment:

Export data:

# Backup PostgreSQL
docker exec gopie-postgres pg_dump -U gopie > backup.sql

# Export MinIO data
docker run --rm -v gopie_minio-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/minio-backup.tar.gz -C /data .

Import to Kubernetes:

# Restore PostgreSQL
kubectl exec -i gopie-postgresql-0 -n gopie -- psql -U gopie < backup.sql

# Restore MinIO
kubectl cp minio-backup.tar.gz gopie-minio-0:/tmp/ -n gopie
kubectl exec gopie-minio-0 -n gopie -- tar xzf /tmp/minio-backup.tar.gz -C /data

Next Steps

Security Best Practices - Harden your Kubernetes deployment
Monitoring Setup - Configure comprehensive monitoring
Performance Tuning - Optimize for your workload
Multi-Region Deployment - Scale globally

Enterprise Ready! Your GoPie Kubernetes deployment is configured for production use with high availability, auto-scaling, and comprehensive monitoring.

Kubernetes Installation

On this page