docs: Add comprehensive networking guide and access testing scripts for nginx-load-balancer

examples/nginx-load-balancer/NETWORKING.md

@@ -0,0 +1,131 @@
+# nginx-load-balancer Networking Guide
+
+## 🎯 **Quick Answer to Your Question**
+
+**Should you access from local hardware PC or within the cluster?**
+
+**For LoadBalancer services, the correct methods are cluster-internal access patterns.**
+
+---
+
+## 🌐 **Correct LoadBalancer Access Methods**
+
+For a **pure LoadBalancer service**, the standard and correct access methods are:
+
+### **✅ Standard LoadBalancer Behavior (k3s)**
+
+**Method 1: Port Forwarding (Development)**
+- **URL**: http://localhost:8080 (after port-forwarding)
+- **Expected**: ✅ Always works
+- **Use case**: Development and testing from local machine
+- **Command**: `kubectl port-forward svc/nginx-load-balancer-service 8080:8080`
+
+**Method 2: Cluster-Internal Access (Pure LoadBalancer)**
+- **URL**: http://nginx-load-balancer-service:8080
+- **Expected**: ✅ Real load balancing across 3 pods
+- **Use case**: Microservices communication, service mesh
+- **Command**: `kubectl run test --image=curlimages/curl --rm -it -- curl http://nginx-load-balancer-service:8080`
+
+---
+
+## 🔍 **Testing Your Setup**
+
+Run the comprehensive test to understand your networking:
+
+```bash
+./test-access.sh
+```
+
+This will test:
+1. **Cluster-internal access** (should work)
+2. **External access** from your PC (LoadBalancer IPs are cluster-internal only)
+3. **Network diagnostics** (helps understand why)
+4. **Pure LoadBalancer behavior** verification
+
+---
+
+## 📊 **What Your Deployment Shows**
+
+Your clean deploy was **100% successful**:
+
+```
+✅ EXCELLENT: No pods on master nodes (hard affinity working)
+Total pods running: 3
+✅ Perfect: 3/3 pods running
+
+LoadBalancer service created successfully
+✅ LoadBalancer IP assigned: 10.20.2.2
+```
+
+**Key Points:**
+- ✅ **Node affinity fixed**: Pods only on workers
+- ✅ **LoadBalancer service**: Multiple IPs assigned (IPv4 + IPv6)
+- ⚠️ **External access**: LoadBalancer IPs are cluster-internal (normal for k3s)
+
+---
+
+## 🛠️ **Expected LoadBalancer Behavior**
+
+### **Normal LoadBalancer Behavior (100% correct):**
+- **Port forwarding**: ✅ Works (standard development method)
+- **Cluster-internal access**: ✅ Works (real load balancing)
+- **LoadBalancer IP external**: ❌ Doesn't work (cluster-internal only)
+- **Reason**: Mycelium Cloud uses cluster-internal LoadBalancer IPs (standard for k3s)
+
+---
+
+## 💡 **How to Access Your LoadBalancer Website**
+
+### **Option 1: Port Forwarding (Always Works)**
+```bash
+kubectl port-forward svc/nginx-load-balancer-service 8080:8080
+# Then access: http://localhost:8080
+```
+
+### **Option 2: Cluster-Internal Testing (Real Load Balancing)**
+```bash
+kubectl run test --image=curlimages/curl --rm -it -- curl http://nginx-load-balancer-service:8080
+```
+
+### **Option 3: Test Load Balancing (Verify It Works)**
+```bash
+# Multiple requests should hit different pods
+for i in {1..6}; do
+    echo "Request $i:"
+    curl -s http://nginx-load-balancer-service:8080 | grep -o "pod-[a-z0-9]*"
+    sleep 1
+done
+```
+
+### **Option 4: Service Name Access**
+```bash
+kubectl run test --image=curlimages/curl --rm -it -- sh -c 'while true; do curl -s http://nginx-load-balancer-service:8080 | grep "pod-"; sleep 2; done'
+```
+
+---
+
+## 🎯 **Real Load Balancing Test**
+
+To verify your LoadBalancer is actually doing load balancing:
+
+**Expected**: You should see different pod names responding to different requests
+
+**Test Command**:
+```bash
+kubectl run test --image=curlimages/curl --rm -it -- sh -c 'for i in {1..6}; do echo "Request \$i:"; curl -s http://nginx-load-balancer-service:8080 | grep -o "pod-[a-z0-9]*"; sleep 1; done'
+```
+
+**Result**: Different pod names in the output = Load balancing is working! ✅
+
+---
+
+## 📋 **Summary**
+
+- **Your deployment is perfect** ✅
+- **LoadBalancer service is working** ✅  
+- **Node affinity is working** ✅
+- **LoadBalancer IPs are cluster-internal** (normal for k3s)
+- **Port forwarding is the standard access method** for development
+- **Service access shows real load balancing** across 3 pods
+
+**Next step**: Run `./show-loadbalancer-access.sh` to see the correct access methods!