Kubernetes Deployment Guide

Detailed Kubernetes deployment instructions for DevOps teams

Deployment Architecture

Prerequisites

Kubernetes Cluster

Minimum Requirements:

Kubernetes 1.26+ (1.28+ recommended)
3+ worker nodes
8 vCPU, 16 GB RAM per node minimum, 32 GB+ RAM recommended
Dynamic storage provisioning (CSI driver)

Required Components:

Ingress controller (NGINX, Traefik, or Istio)
cert-manager for SSL certificates
Persistent volume support

External Dependencies

Required Services (can be hosted on the same cluster):

PostgreSQL 14+ (metadata storage)
Redis 7+ (caching)
RabbitMQ 3.12+ (message queuing)

Graph Database (your existing infrastructure):

Neo4j or Memgraph
Network connectivity from Kubernetes cluster

Network Requirements

Outbound HTTPS to graphpolaris.azurecr.io (container images)
Inbound HTTPS/443 for user access
DNS resolution for services
TLS certificates (Let's Encrypt or your CA)

Tools Required

kubectl v1.26+
helm v3.12+
Access to container registry credentials

Installation

Add Helm Repository

helm repo add graphpolaris https://charts.graphpolaris.com
helm repo update

Create Namespace

kubectl create namespace graphpolaris

Create Registry Secret

kubectl create secret docker-registry graphpolaris-registry \
  --namespace graphpolaris \
  --docker-server=graphpolaris.azurecr.io \
  --docker-username=<provided-username> \
  --docker-password=<provided-password>

Configure Values

Create a values.yaml file:

global:
  imagePullSecrets:
    - graphpolaris-registry

  # Your domain
  domain: graphpolaris.yourdomain.com

# PostgreSQL connection
postgresql:
  host: postgresql.default.svc.cluster.local
  port: 5432
  database: graphpolaris
  username: graphpolaris
  existingSecret: graphpolaris-db-credentials
  existingSecretPasswordKey: password

# Redis connection
redis:
  host: redis-master.default.svc.cluster.local
  port: 6379
  existingSecret: graphpolaris-redis-credentials
  existingSecretPasswordKey: password

# RabbitMQ connection
rabbitmq:
  host: rabbitmq.default.svc.cluster.local
  port: 5672
  username: graphpolaris
  existingSecret: graphpolaris-rabbitmq-credentials
  existingSecretPasswordKey: password

# Ingress configuration
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: graphpolaris.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: graphpolaris-tls
      hosts:
        - graphpolaris.yourdomain.com

# Resource limits
clientGateway:
  replicas: 2
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 2000m
      memory: 2Gi

databaseService:
  replicas: 2
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 2000m
      memory: 2Gi

Install

helm install graphpolaris graphpolaris/graphpolaris \
  --namespace graphpolaris \
  --values values.yaml

Verify Installation

# Check pod status
kubectl get pods -n graphpolaris

# Check services
kubectl get svc -n graphpolaris

# Check ingress
kubectl get ingress -n graphpolaris

Configuration Reference

Environment Variables

Variable	Description	Required
`DATABASE_URL`	PostgreSQL connection string	Yes
`REDIS_URL`	Redis connection string	Yes
`RABBITMQ_URL`	RabbitMQ connection string	Yes
`JWT_SECRET`	Secret for JWT signing	Yes
`ENCRYPTION_KEY`	32-byte encryption key	Yes

Secrets Management

Create secrets for sensitive values:

# Database credentials
kubectl create secret generic graphpolaris-db-credentials \
  --namespace graphpolaris \
  --from-literal=password=<your-password>

# Redis credentials
kubectl create secret generic graphpolaris-redis-credentials \
  --namespace graphpolaris \
  --from-literal=password=<your-password>

# RabbitMQ credentials
kubectl create secret generic graphpolaris-rabbitmq-credentials \
  --namespace graphpolaris \
  --from-literal=password=<your-password>

# Application secrets
kubectl create secret generic graphpolaris-app-secrets \
  --namespace graphpolaris \
  --from-literal=jwt-secret=$(openssl rand -base64 32) \
  --from-literal=encryption-key=$(openssl rand -base64 32)

Autoscaling

Horizontal Pod Autoscaler

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: client-gateway-hpa
  namespace: graphpolaris
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: client-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Air-Gapped Deployment

For disconnected environments without internet access:

Export Images

On a connected machine:

# Pull and save images
docker pull graphpolaris.azurecr.io/graphpolaris-frontend:latest
docker pull graphpolaris.azurecr.io/client-gateway:latest
docker pull graphpolaris.azurecr.io/database-service:latest
docker pull graphpolaris.azurecr.io/ml-service:latest
docker pull graphpolaris.azurecr.io/llm-service:latest
docker pull graphpolaris.azurecr.io/graphimporter:latest

# Save to tar files
docker save graphpolaris.azurecr.io/graphpolaris-frontend:latest > frontend.tar
docker save graphpolaris.azurecr.io/client-gateway:latest > gateway.tar
# ... repeat for all images

Transfer and Load

Transfer tar files to air-gapped environment and load:

docker load < frontend.tar
docker tag graphpolaris.azurecr.io/graphpolaris-frontend:latest \
  your-private-registry.local/graphpolaris-frontend:latest
docker push your-private-registry.local/graphpolaris-frontend:latest

Update Values

global:
  imageRegistry: your-private-registry.local
  imagePullSecrets:
    - your-registry-secret

Upgrades

Upgrade Process

# Update Helm repository
helm repo update

# Check available versions
helm search repo graphpolaris --versions

# Upgrade
helm upgrade graphpolaris graphpolaris/graphpolaris \
  --namespace graphpolaris \
  --values values.yaml \
  --version <new-version>

Rollback

# List revisions
helm history graphpolaris -n graphpolaris

# Rollback to previous version
helm rollback graphpolaris <revision> -n graphpolaris

Monitoring

Health Checks

All services expose health endpoints:

/health - Liveness probe
/ready - Readiness probe

Prometheus Metrics

Services expose Prometheus metrics at /metrics:

# ServiceMonitor for Prometheus Operator
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: graphpolaris
  namespace: graphpolaris
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: graphpolaris
  endpoints:
    - port: metrics
      interval: 30s

Troubleshooting

Common Issues

Pods not starting:

kubectl describe pod <pod-name> -n graphpolaris
kubectl logs <pod-name> -n graphpolaris

Database connection failed:

Verify PostgreSQL is accessible from cluster
Check credentials in secrets
Test with: kubectl run -it --rm debug --image=postgres:14 -- psql <connection-string>

Registry authentication failed:

Verify registry secret is created correctly
Check imagePullSecrets in deployment
Test with: kubectl get secret graphpolaris-registry -n graphpolaris -o yaml

Getting Help

Contact your account representative for:

Deployment assistance
Architecture review
Troubleshooting support

Authentication

Authentication methods powered by Better Auth framework

Azure Guide

Detailed Azure deployment instructions using ARM templates