tfgrid/myceliumcloud-examples
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e8eef188302927717e8d567ebbb44830eb5a1408
myceliumcloud-examples/examples/nginx-load-balancer/nginx-load-balancer.md

7.6 KiB
Raw Blame History

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:

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:

# 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:

kubectl get svc nginx-load-balancer-service

🔄 Scaling and Management

Scale Replicas

# 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

# 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

./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! 🚀