Initial commit

docs/SETUP_LOCAL_K8S.md

@@ -0,0 +1,152 @@
+# Simple Kubernetes Setup Guide
+
+## 🎯 What We're Doing
+
+We'll run Kubernetes **inside containers** on your computer, then deploy your FastAPI + Worker apps to it.
+
+Think of it like:
+- **Kubernetes** = A manager that runs your apps
+- **k3d** = Tool that runs Kubernetes in Docker containers
+- **Your Apps** = FastAPI and Worker that we deploy
+
+## 📦 Step 1: Install k3d (Kubernetes in Docker)
+
+k3d runs Kubernetes in Docker containers - perfect for learning!
+
+**Windows (PowerShell):**
+```powershell
+# Install via Chocolatey (if you have it)
+choco install k3d
+
+# OR download from: https://k3d.io/
+```
+
+**Or use Docker Desktop with Kubernetes:**
+- Open Docker Desktop
+- Go to Settings → Kubernetes
+- Enable Kubernetes
+- Click "Apply & Restart"
+
+## 🚀 Step 2: Create a 3-Node Kubernetes Cluster
+
+```bash
+# Create cluster with 3 nodes (1 master + 2 workers)
+k3d cluster create mycluster --servers 1 --agents 2
+
+# OR if using Docker Desktop Kubernetes, skip this step
+```
+
+**What this does:**
+- Creates 3 containers running Kubernetes
+- 1 master node (controls everything)
+- 2 worker nodes (run your apps)
+
+## ✅ Step 3: Verify Cluster is Running
+
+```bash
+# Check if cluster is ready
+kubectl get nodes
+
+# You should see 3 nodes:
+# NAME              STATUS   ROLES
+# k3d-mycluster-0   Ready    control-plane
+# k3d-mycluster-1   Ready    <none>
+# k3d-mycluster-2   Ready    <none>
+```
+
+## 🐳 Step 4: Build Your Docker Images
+
+```bash
+# Go to your project folder
+cd E:\nats\kubernetes
+
+# Build API image
+docker build -f Dockerfile --target api -t fastapi-backend:latest .
+
+# Build Worker image
+docker build -f Dockerfile --target worker -t nats-worker:latest .
+```
+
+**What this does:**
+- Builds your FastAPI app into a Docker image
+- Builds your Worker app into a Docker image
+- Stores them locally (k3d can use local images)
+
+## 📝 Step 5: Update Image Names
+
+Edit `manifests/fastapi-deployment.yaml`:
+- Change `your-registry/fastapi-backend:latest` → `fastapi-backend:latest`
+
+Edit `manifests/worker-deployment.yaml`:
+- Change `your-registry/nats-worker:latest` → `nats-worker:latest`
+
+## 🚀 Step 6: Deploy Everything
+
+```bash
+# Make script executable (if on Linux/Mac)
+chmod +x deploy.sh
+
+# Run deployment
+./deploy.sh
+
+# OR manually:
+kubectl apply -f manifests/namespace.yaml
+kubectl apply -f manifests/secrets.yaml
+kubectl apply -f manifests/fastapi-deployment.yaml
+kubectl apply -f manifests/fastapi-service.yaml
+kubectl apply -f manifests/fastapi-hpa.yaml
+kubectl apply -f manifests/worker-deployment.yaml
+kubectl apply -f manifests/worker-hpa.yaml
+```
+
+## ✅ Step 7: Check Everything is Running
+
+```bash
+# See all your pods
+kubectl get pods -n nats-backend
+
+# See pods spread across nodes
+kubectl get pods -n nats-backend -o wide
+
+# Check if pods are running
+# You should see:
+# - 4 fastapi-backend pods
+# - 2 nats-worker pods
+```
+
+## 🧪 Step 8: Test Your App
+
+```bash
+# Forward port to access FastAPI
+kubectl port-forward -n nats-backend service/fastapi-backend 8000:80
+
+# In another terminal, test:
+curl http://localhost:8000/health
+```
+
+## 📊 Useful Commands
+
+```bash
+# See everything
+kubectl get all -n nats-backend
+
+# See logs
+kubectl logs -f deployment/fastapi-backend -n nats-backend
+
+# See which node a pod is on
+kubectl get pods -n nats-backend -o wide
+
+# Delete everything (if needed)
+kubectl delete namespace nats-backend
+```
+
+## 🎯 Summary
+
+1. **Install k3d** → Creates Kubernetes in containers
+2. **Create cluster** → 3 nodes ready
+3. **Build images** → Your apps as Docker images
+4. **Deploy** → Run `./deploy.sh`
+5. **Test** → Access your app
+
+**That's it!** Your apps are now running in Kubernetes! 🎉
+