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/`](nginx-mycelium/) |
| **NodePort** | ✅ Complete | Testing/Dev | `[node-ip]:30091` | [`nginx-nodeport/`](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/mycelium-website-nodeport.yaml)
- [`nginx-mycelium/test-ipv6-website.sh`](nginx-mycelium/test-ipv6-website.sh)

**Quick Start:**
```bash
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-deployment.yaml)
- [`nginx-nodeport/nginx-nodeport-service.yaml`](nginx-nodeport/nginx-nodeport-service.yaml)
- [`nginx-nodeport/nginx-nodeport-configmaps.yaml`](nginx-nodeport/nginx-nodeport-configmaps.yaml)
- [`nginx-nodeport/test-nodeport-ipv6.sh`](nginx-nodeport/test-nodeport-ipv6.sh)
- [`nginx-nodeport/update-content.sh`](nginx-nodeport/update-content.sh)

**Quick Start:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
../../scripts/fetch-ip.sh
```

**Test IPv6 connectivity:**
```bash
# hostNetwork
cd nginx-mycelium && ./test-ipv6-website.sh

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

### Content Updates

**hostNetwork:**
```bash
cd nginx-mycelium
./update-content.sh
```

**NodePort:**
```bash
cd nginx-nodeport
./update-content.sh
kubectl rollout restart deployment/nginx-nodeport
```

### Scaling

**NodePort only** (hostNetwork can't scale on same node):
```bash
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](../../README.md)
- **Mycelium Cloud Docs:** https://myceliumcloud.tf
- **fetch-ip.sh Script:** [../../scripts/fetch-ip.sh](../../scripts/fetch-ip.sh)
- **Compare Approaches:** [nginx-nodeport/compare-approaches.md](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

```bash
# 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 🚧