Initial commit: add .gitignore and README

K8S_MIGRATION_GUIDE.md

@@ -0,0 +1,283 @@
+# 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
+