feat: Complete nginx-nodeport implementation with comprehensive documentation and security improvements
This commit is contained in:
mik-tf
365
examples/nginx-variants.md
Normal file
365
examples/nginx-variants.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# 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 🚧
|
||||
Reference in New Issue
Block a user