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:

```hcl
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:

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

### Step 2: Update Kubernetes Manifests

#### Update Namespace References

**Before**:
```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: my-project
```

**After**: Remove namespace creation (managed by Terraform)

#### Update Resource Requests/Limits

Ensure resources match namespace quotas:

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

### Step 3: Configure Ingress

Use shared ingress controller:

```yaml
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:

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

### Step 5: Deploy Application

```bash
# 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:

```yaml
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:

```yaml
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)

```yaml
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