feat: Add comprehensive nginx-mycelium deployment with global IPv6 access
This commit is contained in:
mik-tf
354
examples/nginx-mycelium/nginx-mycelium.md
Normal file
354
examples/nginx-mycelium/nginx-mycelium.md
Normal file
@@ -0,0 +1,354 @@
|
||||
# 🌍 Nginx-Mycelium: Global Web Hosting with Load Balancing
|
||||
|
||||
A **simple and practical** example of hosting a static website globally using Mycelium Cloud Kubernetes. Unlike complex applications, this demonstrates the core concept: **deploy once, access worldwide**.
|
||||
|
||||
## 🎯 What's This About?
|
||||
|
||||
This example shows how to:
|
||||
- ✅ **Host a website globally** via Mycelium IPv6 addresses
|
||||
- ✅ **Use LoadBalancer services** for traffic distribution
|
||||
- ✅ **Scale across multiple nodes** for better performance
|
||||
- ✅ **Demonstrate real web hosting** on Mycelium infrastructure
|
||||
|
||||
## 📁 What This Contains
|
||||
|
||||
```
|
||||
nginx-mycelium/
|
||||
├── nginx-mycelium.md # This guide
|
||||
├── nginx-mycelium-deployment.yaml # Host network + scaled deployment
|
||||
├── nginx-mycelium-service.yaml # LoadBalancer + IPv6 external IPs
|
||||
└── index.html # Very basic HTML content
|
||||
```
|
||||
|
||||
## 🚀 Quick Start - Global Website (2 minutes)
|
||||
|
||||
```bash
|
||||
# 1. Create the nginx deployment with load balancing
|
||||
kubectl apply -f nginx-mycelium-deployment.yaml
|
||||
|
||||
# 2. Create the LoadBalancer service with IPv6 access
|
||||
kubectl apply -f nginx-mycelium-service.yaml
|
||||
|
||||
# 3. Wait for pods to be ready
|
||||
kubectl wait --for=condition=ready pod -l app=nginx-mycelium --timeout=60s
|
||||
|
||||
# 4. Test global access from ANY Mycelium IPv6 address!
|
||||
curl http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80
|
||||
curl http://[476:c4f:b4cb:7205:ff0f:f56e:abea:6905]:80
|
||||
curl http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80
|
||||
```
|
||||
|
||||
## 🌍 Global Access URLs
|
||||
|
||||
Once deployed, your website is **globally accessible** at all 6 Mycelium IPv6 addresses:
|
||||
|
||||
```
|
||||
🌐 Master Nodes:
|
||||
http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80
|
||||
http://[476:c4f:b4cb:7205:ff0f:f56e:abea:6905]:80
|
||||
http://[538:964a:a1e1:4057:ff0f:63c7:960b:7c27]:80
|
||||
|
||||
🌐 Worker Nodes:
|
||||
http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80
|
||||
http://[437:9faf:1f1a:e2b1:ff0f:1fd9:7fd5:1095]:80
|
||||
http://[5c3:a162:45ab:6c53:ff0f:8c55:36b0:24af]:80
|
||||
```
|
||||
|
||||
**Any Mycelium user can access your website from anywhere in the world!**
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Load Balancing Design
|
||||
|
||||
```
|
||||
🌍 Internet (Mycelium Clients)
|
||||
↓
|
||||
🌐 Mycelium IPv6 Network
|
||||
↓
|
||||
🔄 LoadBalancer Service (nginx-mycelium-service)
|
||||
↓
|
||||
🖥️ 3 Nginx Pods (deployed across different nodes)
|
||||
↓
|
||||
📊 Static Content (index.html)
|
||||
```
|
||||
|
||||
### Key Features
|
||||
|
||||
#### **Host Network Mode**
|
||||
```yaml
|
||||
spec:
|
||||
hostNetwork: true # Direct access to host's Mycelium IPv6 interface
|
||||
```
|
||||
|
||||
#### **LoadBalancer with IPv6 External IPs**
|
||||
```yaml
|
||||
spec:
|
||||
type: LoadBalancer
|
||||
externalIPs:
|
||||
- "51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c" # All 6 cluster IPv6 addresses
|
||||
# ... complete list of IPv6 addresses
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
```
|
||||
|
||||
#### **Multi-Node Scaling**
|
||||
```yaml
|
||||
spec:
|
||||
replicas: 3 # Distribute across different cluster nodes
|
||||
nodeSelector: {} # Allow any node for load balancing
|
||||
```
|
||||
|
||||
## 📊 Load Balancing Benefits
|
||||
|
||||
### **Traffic Distribution**
|
||||
- **Across Nodes**: 3 pods spread across different cluster nodes
|
||||
- **Health Monitoring**: Kubernetes automatically routes around failed pods
|
||||
- **No Single Point of Failure**: Multiple nginx instances serve traffic
|
||||
|
||||
### **Performance Advantages**
|
||||
- **Reduced Latency**: Traffic routes to nearest healthy pod
|
||||
- **Higher Throughput**: Multiple nginx instances handle more concurrent requests
|
||||
- **Fault Tolerance**: Automatic failover if a pod or node fails
|
||||
|
||||
### **Scalability**
|
||||
```bash
|
||||
# Scale up if you need more capacity
|
||||
kubectl scale deployment nginx-mycelium --replicas=5
|
||||
|
||||
# Scale down to save resources
|
||||
kubectl scale deployment nginx-mycelium --replicas=1
|
||||
```
|
||||
|
||||
## 🔧 Testing & Verification
|
||||
|
||||
### **Basic Connectivity Test**
|
||||
```bash
|
||||
# Test from your machine (requires Mycelium client)
|
||||
curl -6 http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80
|
||||
|
||||
# Test with IPv6 resolution
|
||||
curl -6 http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80 --resolve 51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c:80:[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]
|
||||
```
|
||||
|
||||
### **Load Balancing Test**
|
||||
```bash
|
||||
# Check which pods are running where
|
||||
kubectl get pods -l app=nginx-mycelium -o wide
|
||||
|
||||
# Test multiple requests to see load distribution
|
||||
for i in {1..10}; do curl -s http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80 | grep -o "Node: [^<]*"; done
|
||||
```
|
||||
|
||||
### **Health Monitoring**
|
||||
```bash
|
||||
# Check service endpoints
|
||||
kubectl get endpoints nginx-mycelium-service
|
||||
|
||||
# Monitor pod status
|
||||
kubectl get pods -l app=nginx-mycelium -w
|
||||
|
||||
# Check nginx logs
|
||||
kubectl logs -l app=nginx-mycelium --tail=10
|
||||
```
|
||||
|
||||
## 🌍 Global Use Cases
|
||||
|
||||
### **Perfect For:**
|
||||
- ✅ **Static Website Hosting**: Company sites, portfolios, blogs
|
||||
- ✅ **Application Frontends**: Web UIs for your applications
|
||||
- ✅ **Documentation Sites**: API docs, user guides
|
||||
- ✅ **Proof of Concepts**: Demonstrate global infrastructure
|
||||
- ✅ **Multi-Region Access**: Users worldwide access the same site
|
||||
|
||||
### **Technical Benefits:**
|
||||
- ✅ **Global CDN**: No centralized server, distributed across nodes
|
||||
- ✅ **Low Latency**: Users connect to nearest healthy pod
|
||||
- ✅ **No Bandwidth Limits**: Uses Mycelium's peer-to-peer network
|
||||
- ✅ **Automatic Scaling**: Kubernetes handles pod creation/deletion
|
||||
|
||||
## 📋 Monitoring & Management
|
||||
|
||||
### **Real-Time Status**
|
||||
```bash
|
||||
# Check deployment status
|
||||
kubectl get deployment nginx-mycelium
|
||||
|
||||
# View service configuration
|
||||
kubectl get svc nginx-mycelium-service -o yaml
|
||||
|
||||
# Check external IPs are configured
|
||||
kubectl get svc nginx-mycelium-service
|
||||
```
|
||||
|
||||
### **Performance Monitoring**
|
||||
```bash
|
||||
# Check resource usage
|
||||
kubectl top pods -l app=nginx-mycelium
|
||||
|
||||
# Monitor nginx access logs
|
||||
kubectl logs -l app=nginx-mycelium -f
|
||||
|
||||
# Check pod distribution
|
||||
kubectl get pods -l app=nginx-mycelium -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,IP:.status.podIP
|
||||
```
|
||||
|
||||
### **Scaling Operations**
|
||||
```bash
|
||||
# Current replica count
|
||||
kubectl get deployment nginx-mycelium
|
||||
|
||||
# Scale up for more capacity
|
||||
kubectl scale deployment nginx-mycelium --replicas=5
|
||||
|
||||
# Check load distribution after scaling
|
||||
kubectl get pods -l app=nginx-mycelium -o wide
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### **Common Issues**
|
||||
|
||||
#### **Pod Won't Start**
|
||||
```bash
|
||||
# Check pod status and events
|
||||
kubectl describe pod -l app=nginx-mycelium
|
||||
|
||||
# Check node resource availability
|
||||
kubectl get nodes
|
||||
|
||||
# Look for scheduling issues
|
||||
kubectl get events --sort-by='.lastTimestamp'
|
||||
```
|
||||
|
||||
#### **IPv6 Access Not Working**
|
||||
```bash
|
||||
# Test IPv6 connectivity
|
||||
ping 51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c
|
||||
|
||||
# Check if pods are running
|
||||
kubectl get pods -l app=nginx-mycelium
|
||||
|
||||
# Verify service configuration
|
||||
kubectl get svc nginx-mycelium-service -o wide
|
||||
```
|
||||
|
||||
#### **Load Balancing Issues**
|
||||
```bash
|
||||
# Check all pods are ready
|
||||
kubectl get pods -l app=nginx-mycelium
|
||||
|
||||
# Verify endpoints are healthy
|
||||
kubectl get endpoints nginx-mycelium-service
|
||||
|
||||
# Check pod logs for errors
|
||||
kubectl logs -l app=nginx-mycelium
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### **Deployment Strategy**
|
||||
1. **Start Small**: Deploy 1 replica initially
|
||||
2. **Test Connectivity**: Verify IPv6 access works
|
||||
3. **Scale Gradually**: Increase replicas based on traffic
|
||||
4. **Monitor Performance**: Watch resource usage and response times
|
||||
|
||||
### **Content Management**
|
||||
- **Static Files**: Update `index.html` for content changes
|
||||
- **Volume Mounts**: Use ConfigMaps for dynamic content
|
||||
- **Health Checks**: Implement proper liveness/readiness probes
|
||||
|
||||
### **Security Considerations**
|
||||
- **No Authentication**: Open access for demonstration purposes
|
||||
- **Rate Limiting**: Consider adding nginx rate limiting for production
|
||||
- **HTTPS**: Use TF Gateway CRDs for SSL certificates
|
||||
|
||||
## 🚀 Advanced Features
|
||||
|
||||
### **Custom Content**
|
||||
Replace the `index.html` with your own content:
|
||||
```bash
|
||||
# Update content
|
||||
kubectl create configmap nginx-content --from-file=index.html=custom.html
|
||||
|
||||
# Rollout update
|
||||
kubectl rollout restart deployment/nginx-mycelium
|
||||
```
|
||||
|
||||
### **Additional Services**
|
||||
Add more services following the same pattern:
|
||||
```bash
|
||||
# Apply additional nginx services
|
||||
kubectl apply -f additional-services.yaml
|
||||
|
||||
# Each service gets its own LoadBalancer with IPv6
|
||||
```
|
||||
|
||||
### **TF Gateway Integration**
|
||||
For custom domains and HTTPS:
|
||||
```yaml
|
||||
# Use TF Gateway CRD for public domain
|
||||
apiVersion: ingress.grid.tf/v1
|
||||
kind: TFGW
|
||||
metadata:
|
||||
name: my-website
|
||||
spec:
|
||||
hostname: "my-website"
|
||||
backends:
|
||||
- "http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80"
|
||||
```
|
||||
|
||||
## 📊 Performance Characteristics
|
||||
|
||||
### **Expected Latency**
|
||||
- **Local Access**: < 50ms (same node)
|
||||
- **Regional Access**: 100-300ms (same country/region)
|
||||
- **Global Access**: 200-500ms (worldwide)
|
||||
|
||||
### **Capacity Planning**
|
||||
- **Single Pod**: ~1,000 concurrent connections
|
||||
- **3 Pods**: ~3,000 concurrent connections
|
||||
- **5 Pods**: ~5,000 concurrent connections
|
||||
|
||||
### **Resource Usage**
|
||||
- **Memory**: ~50MB per nginx pod
|
||||
- **CPU**: ~100m CPU per pod
|
||||
- **Storage**: Minimal (static files)
|
||||
|
||||
## 🌟 Success Metrics
|
||||
|
||||
### **Technical Success Indicators**
|
||||
- ✅ All 3 pods running on different nodes
|
||||
- ✅ LoadBalancer service shows 6 IPv6 external IPs
|
||||
- ✅ IPv6 connectivity successful from outside cluster
|
||||
- ✅ Traffic distributes across all healthy pods
|
||||
|
||||
### **User Experience Success**
|
||||
- ✅ Website loads from any Mycelium IPv6 address
|
||||
- ✅ Consistent content regardless of access point
|
||||
- ✅ No authentication required (as intended)
|
||||
- ✅ Global accessibility confirmed
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
### **Infrastructure Dependencies**
|
||||
- **Mycelium Network**: Requires Mycelium client for IPv6 access
|
||||
- **Kubernetes Cluster**: 3+ nodes recommended for load balancing
|
||||
- **External Connectivity**: Mycelium must be reachable from internet
|
||||
|
||||
### **Limitations**
|
||||
- **Port 80 Only**: HTTP only (no HTTPS without TF Gateway)
|
||||
- **Static Content**: Designed for static websites
|
||||
- **Public Access**: No authentication/authorization
|
||||
|
||||
## 🎉 Conclusion
|
||||
|
||||
This nginx-mycelium example demonstrates that **Mycelium Cloud can host real, globally accessible websites** with load balancing and high availability.
|
||||
|
||||
**Key Takeaways:**
|
||||
1. **Simple Deployment**: Much cleaner than complex applications
|
||||
2. **Global Reach**: Any Mycelium user can access your site
|
||||
3. **Load Balancing**: Traffic distributes across multiple pods
|
||||
4. **Real Infrastructure**: This is production-grade web hosting
|
||||
|
||||
**Perfect for:** Demonstrating the power of Mycelium's global IPv6 internet infrastructure with actual web hosting capabilities!
|
||||
Reference in New Issue
Block a user