docs/K8S_MIGRATION_GUIDE.md

Kubernetes Migration Guide

Date: 2025-01-27 Purpose: Guide for migrating projects to shared Kubernetes clusters Status: Complete

---

Overview

This guide provides instructions for migrating projects to shared Kubernetes clusters with namespace isolation.

---

Prerequisites

• Access to shared Kubernetes cluster
• kubectl configured
• Appropriate RBAC permissions
• Project containerized (Docker/Kubernetes manifests)

---

Migration Steps

Step 1: Prepare Namespace

Create namespace using Terraform module:

module "namespace" {
  source = "../../infrastructure/terraform/modules/kubernetes/namespace"

  name = "my-project"

  labels = {
    app     = "my-project"
    env     = "production"
    managed = "terraform"
  }

  resource_quota = {
    "requests.cpu"    = "4"
    "requests.memory" = "8Gi"
    "limits.cpu"      = "8"
    "limits.memory"   = "16Gi"
  }
}

Or create manually:

kubectl create namespace my-project
kubectl label namespace my-project app=my-project env=production

Step 2: Update Kubernetes Manifests

Update Namespace References

Before:

apiVersion: v1
kind: Namespace
metadata:
  name: my-project

After: Remove namespace creation (managed by Terraform)

Update Resource Requests/Limits

Ensure resources match namespace quotas:

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Step 3: Configure Ingress

Use shared ingress controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-project
  namespace: my-project
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts:
        - my-project.example.com
      secretName: my-project-tls
  rules:
    - host: my-project.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-project
                port:
                  number: 80

Step 4: Configure Secrets

Use shared Key Vault or Kubernetes secrets:

apiVersion: v1
kind: Secret
metadata:
  name: my-project-secrets
  namespace: my-project
type: Opaque
stringData:
  database-url: "postgresql://..."
  api-key: "..."

Step 5: Deploy Application

# Apply manifests
kubectl apply -f k8s/ -n my-project

# Verify deployment
kubectl get pods -n my-project
kubectl get services -n my-project
kubectl get ingress -n my-project

---

Namespace Isolation

Resource Quotas

Enforced at namespace level:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: my-project-quota
  namespace: my-project
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi

Network Policies

Isolate network traffic:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: my-project-policy
  namespace: my-project
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: shared-services
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              name: shared-services

---

Monitoring Integration

ServiceMonitor (Prometheus)

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-project
  namespace: my-project
spec:
  selector:
    matchLabels:
      app: my-project
  endpoints:
    - port: metrics
      path: /metrics

Logging

Logs automatically collected by shared Loki instance.

---

Best Practices

Resource Management

• Set appropriate requests/limits
• Use horizontal pod autoscaling
• Monitor resource usage

Security

• Use RBAC for access control
• Implement network policies
• Use secrets management

Monitoring

• Expose metrics endpoints
• Configure ServiceMonitor
• Set up alerts

---

Troubleshooting

Pod Not Starting

Check:

• Resource quotas
• Resource requests/limits
• Image pull secrets
• Service account permissions

Network Issues

Check:

• Network policies
• Service endpoints
• Ingress configuration

Storage Issues

Check:

• Persistent volume claims
• Storage classes
• Access modes

---

Migration Checklist

• Create namespace
• Configure resource quotas
• Update Kubernetes manifests
• Configure ingress
• Set up secrets
• Deploy application
• Verify deployment
• Configure monitoring
• Set up network policies
• Test functionality
• Update documentation

---

Last Updated: 2025-01-27