myceliumcloud-examples/examples/nginx-load-balancer/nginx-load-balancer.md

# nginx-load-balancer - Mycelium Cloud LoadBalancer Website Example

Production-ready example for deploying a secure, globally accessible website on Mycelium Cloud using **LoadBalancer** services with automatic IPv6 assignment and traffic distribution.

## 🚀 Quick Start (One Command!)

**Deploy a production-ready LoadBalancer service:**

```bash
cd myceliumcloud-examples/examples/nginx-load-balancer
./deploy-and-test.sh
```

**What this script does:**
1. ✅ Deploy 3 nginx replicas (production-ready scaling)
2. ✅ Create LoadBalancer service with automatic IPv6
3. ✅ Configure hard worker node affinity (ensures pods on workers only)
4. ✅ Support both LoadBalancer IP and direct node access
5. ✅ Update website content with service information
6. ✅ Verify load balancing functionality
7. ✅ Show you the automatic IPv6 assignment

**Expected output:**
```
🎉 Deploy and Test Complete!
==================================

🌐 Access Information:
  • Service URL: http://[auto-assigned-ipv6]:8080
  • Load balancing: Active across 3 replicas
  • Service type: LoadBalancer with IPv6

To access from a machine with Mycelium installed:
  curl -6 "http://[ipv6]:8080/"
```

---

## 🎯 What This Example Teaches

- **LoadBalancer Services** - Production-grade service exposure
- **Automatic IPv6 Assignment** - Mycelium assigns IPv6 to service endpoints
- **Traffic Distribution** - Automatic load balancing across 3 replicas
- **Worker Node Preferences** - Deploy only on worker nodes (not masters)
- **Production Patterns** - Real-world scaling and reliability
- **Dual-Access Networking** - Both LoadBalancer IP and direct node access supported

---

## 📊 Architecture

```
User (with Mycelium)
    ↓
http://[mycelium-ipv6]:8080 (LoadBalancer Service)
    ↓
Kubernetes LoadBalancer Service (IPv4 + IPv6)
    ↓
Traffic distributed across 3 replicas
    ↓
Pod 1 ← Pod 2 ← Pod 3 (worker nodes)
    ↓
nginx → HTML (load balanced)
```

**Key Points:**
- Service type: **LoadBalancer** (not NodePort)
- IP families: **Dual-stack (IPv4 + IPv6)** ⭐ Critical
- Pod network: **Isolated** (no hostNetwork)
- Replicas: **3 by default** (production-ready)
- Traffic policy: **Local** (preserves source IP)
- IPv6: **Automatically assigned by Mycelium**

---

## ⚖️ LoadBalancer vs NodePort Comparison

| Feature | NodePort | LoadBalancer |
|---------|----------|--------------|
| **Access Method** | `http://[node-ipv6]:port` | `http://[service-ipv6]:port` |
| **IPv6 Assignment** | Manual (node IPv6) | Automatic (service IPv6) |
| **Load Balancing** | Manual (per node) | Automatic (per service) |
| **Traffic Distribution** | Via multiple NodePorts | Via single LoadBalancer |
| **Production Use** | Development/Testing | **Production Ready** |
| **Management** | Multiple URLs to manage | Single service endpoint |
| **Scalability** | Limited by node count | True service-level scaling |

**When to use each:**
- **NodePort**: Learning, development, testing
- **LoadBalancer**: Production, high availability, true scaling

---

## 🔧 Manual Deployment (Alternative)

If you want to do it step-by-step:

```bash
# 1. Deploy resources
kubectl apply -f nginx-load-balancer-configmaps.yaml
kubectl apply -f nginx-load-balancer-deployment.yaml
kubectl apply -f nginx-load-balancer-service.yaml

# 2. Wait for ready
kubectl wait --for=condition=ready pod -l app=nginx-load-balancer --timeout=90s

# 3. Update content
./update-content-load-balancer.sh
kubectl rollout restart deployment/nginx-load-balancer

# 4. Check service status
kubectl get svc nginx-load-balancer-service

# 5. Test load balancing
kubectl get pods -l app=nginx-load-balancer -o wide
```

---

## 🌍 Understanding LoadBalancer Behavior

### **Automatic IPv6 Assignment**
- Mycelium automatically assigns IPv6 address to the LoadBalancer service
- No manual IPv6 discovery needed
- Single endpoint for all traffic
- Service handles IPv6 assignment transparently

### **Load Balancing**
- **3 replicas** distributed across worker nodes
- Traffic automatically distributed by Kubernetes
- Failover and redundancy built-in
- True horizontal scaling capability

### **Production Features**
- Resource limits and requests
- Health checks (liveness + readiness)
- Worker node preferences
- Clean network isolation

---

## 📁 Files in This Directory

### Configuration
- `nginx-load-balancer-deployment.yaml` - 3-replica deployment
- `nginx-load-balancer-service.yaml` - LoadBalancer service (IPv4 + IPv6)
- `nginx-load-balancer-configmaps.yaml` - HTML content + nginx config

### Scripts
- `deploy-and-test.sh` - ⭐ **Main script** (deploy + test + verify)
- `update-content-load-balancer.sh` - Content updates for LoadBalancer
- `debug-networking.sh` - Network debugging tools

### Documentation
- `nginx-load-balancer.md` - This guide
- `PLAN.md` - Implementation details

---

## ✅ Success Indicators

**When working correctly:**
- ✅ Service type: `LoadBalancer`
- ✅ External IP: `[mycelium-ipv6]` (assigned automatically)
- ✅ IP families: `["IPv4","IPv6"]`
- ✅ Pod status: `Running` (3 replicas)
- ✅ Load balancing: Active across all replicas

**Check service status:**
```bash
kubectl get svc nginx-load-balancer-service
```

---

## 🔄 Scaling and Management

### **Scale Replicas**
```bash
# Scale to 5 replicas
kubectl scale deployment nginx-load-balancer --replicas=5

# Scale down to 2 replicas
kubectl scale deployment nginx-load-balancer --replicas=2
```

### **Monitor Load Balancing**
```bash
# Check pod distribution
kubectl get pods -l app=nginx-load-balancer -o wide

# Monitor service status
kubectl get svc nginx-load-balancer-service -w

# Check load balancing behavior
kubectl get pods -l app=nginx-load-balancer
```

### **Update Content**
```bash
./update-content-load-balancer.sh
kubectl rollout restart deployment/nginx-load-balancer
```

---

## 🚨 Troubleshooting

**If LoadBalancer has no external IP:**
- Wait for Mycelium to assign IPv6 (may take 1-2 minutes)
- Check: `kubectl get svc nginx-load-balancer-service`
- Verify: `kubectl get pods -l app=nginx-load-balancer`

**If only 1 pod is running:**
- Check pod status: `kubectl get pods -l app=nginx-load-balancer`
- Review events: `kubectl describe deployment nginx-load-balancer`
- Check logs: `kubectl logs -l app=nginx-load-balancer`

**If load balancing doesn't work:**
- Verify all 3 pods are running
- Check service endpoints: `kubectl get endpoints nginx-load-balancer-service`
- Test individual pods: `kubectl exec -it [pod-name] -- curl -s localhost:8080`

---

## 🆘 Common Questions

**Q: How is LoadBalancer different from NodePort?**
A: LoadBalancer provides a single service endpoint with automatic IPv6 assignment, while NodePort requires accessing individual node IPv6 addresses.

**Q: Why 3 replicas by default?**
A: 3 replicas provide a good balance of resource usage and high availability for learning/demonstration purposes.

**Q: How do I know if load balancing is working?**
A: All 3 pods should respond to requests, and the service should distribute traffic between them automatically.

**Q: Can I use this in production?**
A: Yes! This follows production patterns with proper resource limits, health checks, and worker node preferences.

**Q: What if I need more replicas?**
A: Use `kubectl scale deployment nginx-load-balancer --replicas=5` or any number you need.

---

## 🎉 Success!

Once deployed, you'll have:
- ✅ **Production-ready** LoadBalancer service
- ✅ **Automatic IPv6** assignment from Mycelium
- ✅ **Load balancing** across 3 replicas
- ✅ **Global accessibility** via IPv6
- ✅ **High availability** with failover

**You're ready for production LoadBalancer deployments on Mycelium Cloud!** 🚀