feat: Add nginx-load-balancer example with LoadBalancer service and automatic IPv6 assignment
This commit is contained in:
mik-tf
252
examples/nginx-load-balancer/nginx-load-balancer.md
Normal file
252
examples/nginx-load-balancer/nginx-load-balancer.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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 worker node preferences
|
||||
4. ✅ Update website content with service information
|
||||
5. ✅ Verify load balancing functionality
|
||||
6. ✅ 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
|
||||
|
||||
---
|
||||
|
||||
## 📊 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!** 🚀
|
||||
Reference in New Issue
Block a user