myceliumcloud-examples/examples/nginx-variants.md

Nginx on Mycelium Cloud: Complete Deployment Guide

This guide covers 4 different ways to deploy nginx on Mycelium Cloud, from simple demos to production-ready deployments.

📚 Quick Navigation

Variant	Status	Use Case	Access Pattern	Directory
hostNetwork	✅ Complete	Demo/POC	[pod-ip]:8080	nginx-mycelium/
NodePort	✅ Complete	Testing/Dev	[node-ip]:30091	nginx-nodeport/
LoadBalancer	🚧 Planned	Production	[lb-ip]:80	Coming soon
Ingress	🚧 Planned	Web Apps	domain.com	Coming soon

🎯 Which One Should I Use?

Decision Tree

Start here
    │
    ├─ Just learning Kubernetes? → hostNetwork (nginx-mycelium)
    │
    ├─ Need production security? → NodePort (nginx-nodeport)
    │
    ├─ Need external LB? → LoadBalancer (coming soon)
    │
    └─ Need domains & SSL? → Ingress (coming soon)

Detailed Comparison

Feature	hostNetwork	NodePort	LoadBalancer	Ingress
Complexity	⭐ Simple	⭐⭐ Easy	⭐⭐⭐ Medium	⭐⭐⭐⭐ Advanced
Security	⚠️ Low	✅ Good	✅ Good	✅ Excellent
Scalability	❌ Limited	✅ Good	✅ Excellent	✅ Excellent
Production Ready	❌ No	✅ Yes	✅ Yes	✅ Yes
Learning Value	✅ High	✅ High	✅ Medium	✅ High
Setup Time	2 min	3 min	5 min	10 min

📖 Complete Variant Details

1. hostNetwork (nginx-mycelium) - ⭐ Start Here

Best for: Learning, experimentation, proof of concepts

How it works:

• Pod directly accesses host network interfaces
• Pod gets the host node's Mycelium IPv6 address
• Direct access to Mycelium network without Kubernetes service layer

Access: http://[pod-mycelium-ipv6]:8080

Pros:

• ✅ Simplest setup
• ✅ Direct Mycelium IP access
• ✅ No service layer needed
• ✅ Fastest performance

Cons:

• ❌ Security concerns (host network access)
• ❌ Port conflicts possible
• ❌ Can't scale multiple replicas on same node
• ❌ Not production-ready

Files:

• nginx-mycelium/mycelium-website-nodeport.yaml
• nginx-mycelium/test-ipv6-website.sh

Quick Start:

cd nginx-mycelium
kubectl apply -f mycelium-website-nodeport.yaml
kubectl wait --for=condition=ready pod -l app=mycelium-website --timeout=60s
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | head -1
# Access at http://[ipv6]:8080

---

2. NodePort (nginx-nodeport) - ✅ Recommended Starting Point

Best for: Testing, development, production workloads with proper security

How it works:

• Pod runs in isolated network namespace
• Kubernetes service exposes on NodePort (30091)
• Access via worker node's Mycelium IPv6 address
• kube-proxy routes: node:30091 → service:8080 → pod:8080

Access: http://[worker-node-mycelium-ipv6]:30091

Pros:

• ✅ Enhanced security (pod isolation)
• ✅ Standard Kubernetes patterns
• ✅ Can scale to multiple replicas
• ✅ Production-ready
• ✅ Network policies supported
• ✅ Standard monitoring/debugging tools

Cons:

• ⚠️ Slightly more complex than hostNetwork
• ⚠️ Need to use worker node IPs (not pod IPs)
• ⚠️ NodePort range limited (30000-32767)

Files:

• nginx-nodeport/nginx-nodeport-deployment.yaml
• nginx-nodeport/nginx-nodeport-service.yaml
• nginx-nodeport/nginx-nodeport-configmaps.yaml
• nginx-nodeport/test-nodeport-ipv6.sh
• nginx-nodeport/update-content.sh

Quick Start:

cd nginx-nodeport
kubectl apply -f nginx-nodeport-configmaps.yaml
kubectl apply -f nginx-nodeport-deployment.yaml
kubectl apply -f nginx-nodeport-service.yaml
kubectl wait --for=condition=ready pod -l app=nginx-nodeport --timeout=60s

# Get worker node IPv6
NODE_IPV6=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
echo "Access at: http://[$NODE_IPV6]:30091"

Testing:

# Run comprehensive tests
./test-nodeport-ipv6.sh

# Update content dynamically
./update-content.sh

---

3. LoadBalancer (Coming Soon) - 🚧 In Development

Best for: Production deployments needing external IP addresses

How it works:

• Similar to NodePort but with cloud load balancer
• Gets external IP address from cloud provider
• Standard ports (80, 443)

Access: http://[external-lb-ip]:80

Pros:

• ✅ Standard ports (80/443)
• ✅ External IP address
• ✅ Cloud-native load balancing
• ✅ Production-ready

Status: Documentation and examples coming soon

---

4. Ingress (Coming Soon) - 🚧 In Development

Best for: Production web applications with custom domains and SSL

How it works:

• Uses Ingress controller (nginx-ingress, traefik, etc.)
• Provides HTTP routing rules
• SSL/TLS termination
• Domain-based routing

Access: https://yourdomain.com

Pros:

• ✅ Custom domain support
• ✅ SSL/TLS certificates
• ✅ Path-based routing
• ✅ Most production-ready

Status: Documentation and examples coming soon

---

🔄 Migration Path

From hostNetwork to NodePort

Why migrate:

• Better security
• Standard Kubernetes patterns
• Ability to scale
• Production readiness

Steps:

1. Deploy NodePort version alongside hostNetwork
2. Test functionality with NodePort
3. Update any automation to use node IPs instead of pod IPs
4. Remove hostNetwork deployment

Example:

# Deploy both versions
kubectl apply -f nginx-mycelium/mycelium-website-nodeport.yaml
kubectl apply -f nginx-nodeport/nginx-nodeport-deployment.yaml
kubectl apply -f nginx-nodeport/nginx-nodeport-service.yaml

# Test both work
curl -6 http://[pod-ip]:8080        # hostNetwork
curl -6 http://[node-ip]:30091      # NodePort

# Once validated, remove hostNetwork
kubectl delete -f nginx-mycelium/mycelium-website-nodeport.yaml

---

🛠️ Common Operations

Discovery Scripts

Get all Mycelium IPv6 addresses:

../../scripts/fetch-ip.sh

Test IPv6 connectivity:

# hostNetwork
cd nginx-mycelium && ./test-ipv6-website.sh

# NodePort
cd nginx-nodeport && ./test-nodeport-ipv6.sh

Content Updates

hostNetwork:

cd nginx-mycelium
./update-content.sh

NodePort:

cd nginx-nodeport
./update-content.sh
kubectl rollout restart deployment/nginx-nodeport

Scaling

NodePort only (hostNetwork can't scale on same node):

kubectl scale deployment nginx-nodeport --replicas=3
kubectl get pods -l app=nginx-nodeport -o wide

---

📊 Technical Specifications

Network Flow Comparison

hostNetwork:

User → Mycelium Network → Pod's Mycelium IP:8080 → nginx

NodePort:

User → Mycelium Network → Node's Mycelium IP:30091 → 
kube-proxy → Service:8080 → Pod:8080 → nginx

LoadBalancer (future):

User → Mycelium Network → External LB:80 → 
Node → Service:8080 → Pod:8080 → nginx

Ingress (future):

User → DNS → Mycelium Network → Ingress Controller:443 → 
Service:8080 → Pod:8080 → nginx

Port Allocation

Variant	External Port	Service Port	Pod Port	Notes
hostNetwork	8080	30090 (optional)	8080	Direct host port
NodePort	30091	8080	8080	NodePort range
LoadBalancer	80	8080	8080	Standard HTTP
Ingress	80/443	8080	8080	With SSL

---

🎓 Learning Path

Beginner (Week 1)

1. Start with hostNetwork to understand Mycelium networking basics
2. Learn how pods get IPv6 addresses
3. Understand Kubernetes pod deployment

Intermediate (Week 2)

1. Move to NodePort to learn Kubernetes services
2. Understand network isolation and security
3. Practice scaling and load balancing

Advanced (Week 3+)

1. Study LoadBalancer concepts and cloud integration
2. Learn Ingress controllers and SSL/TLS
3. Implement production monitoring and logging

---

🔗 Additional Resources

• Main Repository: ../../README.md
• Mycelium Cloud Docs: https://myceliumcloud.tf
• fetch-ip.sh Script: ../../scripts/fetch-ip.sh
• Compare Approaches: nginx-nodeport/compare-approaches.md

---

🤝 Contributing

Want to add the LoadBalancer or Ingress examples?

1. Follow the established pattern (separate directory, comprehensive docs)
2. Include deployment YAML, service configuration, and test scripts
3. Add appropriate security considerations
4. Update this comparison document

---

📝 Quick Reference

Common Commands

# Discovery
../../scripts/fetch-ip.sh

# Deploy hostNetwork
kubectl apply -f nginx-mycelium/mycelium-website-nodeport.yaml

# Deploy NodePort
kubectl apply -f nginx-nodeport/*.yaml

# Test
cd nginx-nodeport && ./test-nodeport-ipv6.sh

# Scale (NodePort only)
kubectl scale deployment nginx-nodeport --replicas=3

# Update content
cd nginx-nodeport && ./update-content.sh

# Cleanup
kubectl delete -f nginx-nodeport/*.yaml
kubectl delete -f nginx-mycelium/*.yaml

---

Last Updated: 2025-01-07 Status: hostNetwork ✅ | NodePort ✅ | LoadBalancer 🚧 | Ingress 🚧