tfgrid/myceliumcloud-examples
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Complete nginx-nodeport implementation with comprehensive documentation and security improvements

Browse Source
This commit is contained in:
mik-tf
2025-11-06 20:36:59 -05:00
parent d293c00794
commit 2028fc87ff
6 changed files with 948 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
examples/nginx-nodeport/nginx-nodeport.md
View File

@@ -1,6 +1,18 @@
# Mycelium Cloud - Nginx NodePort Secure Website Hosting
A complete, production-ready example for deploying a secure, globally accessible website on Mycelium Cloud using Kubernetes NodePort services with enhanced network isolation. This demonstrates **security-first IPv6 web hosting** with standard Kubernetes patterns.
A complete, production-ready example for deploying a secure, globally accessible website on Mycelium Cloud using Kubernetes **NodePort** services with enhanced network isolation. This demonstrates **security-first IPv6 web hosting** with standard Kubernetes patterns.
## 🔑 Key Concept: NodePort Access Pattern
**Important:** With NodePort, you access the service via:
- **Worker Node's Mycelium IPv6 address** + **NodePort 30091**
- Example: `http://[worker-node-mycelium-ipv6]:30091/`
**This is different from hostNetwork** where pods get direct Mycelium IPs:
- **hostNetwork**: Pod has Mycelium IP → Access: `http://[pod-mycelium-ip]:8080`
- **NodePort**: Pod isolated network → Access: `http://[node-mycelium-ip]:30091`
The traffic flow is: `User → Node:30091 → Service:8080 → Pod:8080`
## 📁 What This Contains
@@ -87,20 +99,43 @@ This example uses **separate configuration files** for better organization and s
└──────────────────┘
```
### Network Flow
`IPv6 Client → NodePort:30091 → Service:8080 → Pod:8080 → nginx → HTML Content`
### Network Flow (NodePort Pattern)
```
User with Mycelium
↓
http://[worker-node-mycelium-ipv6]:30091
↓
Worker Node (kube-proxy forwards)
↓
NodePort 30091 → Service port 8080
↓
Kubernetes Service (load balances)
↓
Pod container port 8080
↓
nginx → HTML Content
```
### 🚨 Critical: Worker Node vs Master Node Access
**Unlike hostNetwork (accessible from any node), NodePort services are ONLY accessible from the specific worker node where your pod is running.**
### 🚨 Critical: NodePort Access Pattern
- **hostNetwork**: Pod has direct host access → accessible from ANY node's IPv6
- **NodePort**: Pod isolated network → accessible ONLY from pod's host node
**With NodePort:**
- Pods run in **isolated network** (no `hostNetwork`)
- Pods do **NOT** have direct Mycelium IPv6 addresses
- Access via **worker node's Mycelium IPv6** + NodePort
- Service is accessible on **all worker nodes** at port 30091
- kube-proxy forwards traffic: `node:30091 → service:8080 → pod:8080`
**Always check pod location first:**
**Comparison:**
- **hostNetwork (nginx-mycelium)**: Pod gets host's Mycelium IP → Access: `http://[pod-ip]:8080`
- **NodePort (nginx-nodeport)**: Pod isolated → Access: `http://[node-ip]:30091`
**Getting the right IPv6:**
```bash
# Check where your pod is running
kubectl get pods -l app=nginx-nodeport -o wide
# Look for the NODE column - this is where you can access your service
# Get worker node Mycelium IPv6 addresses
kubectl get nodes -o wide
# OR use the fetch-ip.sh script
../../scripts/fetch-ip.sh
```
### Key Security Improvements
@@ -152,20 +187,23 @@ spec:
```yaml
spec:
type: NodePort
type: NodePort # ← Service type is NodePort
externalTrafficPolicy: Local # Preserves IPv6 source IP
ports:
- port: 8080
targetPort: 8080
nodePort: 30091 # External port (avoiding conflict with nginx-mycelium)
nodePort: 30091 # ← Explicitly set to 30091 (avoiding conflict with nginx-mycelium's 30090)
protocol: TCP
```
**What it does:**
- Exposes nginx on **NodePort 30091** (external, avoiding conflicts)
- Exposes nginx on **NodePort 30091** on all worker nodes
- **Preserves IPv6 source IP** for logging and security
- Uses **standard Kubernetes service** patterns
- Uses **standard Kubernetes service** patterns (not LoadBalancer)
- Provides **load balancing** across pod replicas (when scaled)
- Access via: `http://[worker-node-mycelium-ipv6]:30091/`
**NodePort Range:** Kubernetes NodePorts use range 30000-32767 by default
### 3. nginx-nodeport-configmaps.yaml
**Content and nginx configuration:**
@@ -364,7 +402,26 @@ kubectl delete configmap nginx-nodeport-content nginx-nodeport-nginx-config
kubectl get all -l app=nginx-nodeport # Should return nothing
```
## 📊 Key Differences from hostNetwork Approach
## 📊 Nginx Deployment Variants Comparison
### Complete Overview: 4 Ways to Deploy Nginx on Mycelium Cloud
| Feature | hostNetwork | NodePort | LoadBalancer | Ingress |
|---------|-------------|----------|--------------|---------|
| **Example** | nginx-mycelium | nginx-nodeport | (Future) | (Future) |
| **Pod Network** | ❌ Host | ✅ Isolated | ✅ Isolated | ✅ Isolated |
| **Security** | ⚠️ Low | ✅ Medium | ✅ Medium | ✅ High |
| **Access Pattern** | `[pod-ip]:8080` | `[node-ip]:30091` | `[lb-ip]:80` | `domain.com` |
| **Port Range** | Any | 30000-32767 | 80, 443 | 80, 443 |
| **Mycelium Access** | Direct pod | Via node | Via LB | Via ingress |
| **Use Case** | Demo/POC | Testing/Dev | Production | Web apps |
| **Scalability** | ❌ Limited | ✅ Good | ✅ Excellent | ✅ Excellent |
| **Load Balancing** | Manual | K8s Service | Cloud LB | Ingress controller |
| **SSL/TLS** | Manual | Manual | Possible | Native |
| **DNS Support** | No | No | Possible | Yes |
| **Production Ready** | ⚠️ No | ✅ Yes | ✅ Yes | ✅ Yes |
### Key Differences: hostNetwork vs NodePort
| Feature | hostNetwork (nginx-mycelium) | NodePort (nginx-nodeport) |
|---------|------------------------------|---------------------------|
@@ -373,8 +430,10 @@ kubectl get all -l app=nginx-nodeport # Should return nothing
| **Port Conflicts** | ❌ Limited by host ports | ✅ No port conflicts |
| **Debugging** | 🔄 Host-level tools | ✅ Standard K8s patterns |
| **Monitoring** | 🔄 Host monitoring | ✅ Pod-level monitoring |
| **Scalability** | ❌ Single instance | ✅ Multiple replicas |
| **Production Ready** | ⚠️ Demo/POC | ✅ Production patterns |
| **Scalability** | ❌ Single instance per node | ✅ Multiple replicas |
| **Production Ready** | ⚠️ Demo/POC only | ✅ Production patterns |
| **Access URL** | `http://[pod-mycelium-ip]:8080` | `http://[node-mycelium-ip]:30091` |
| **Port Used** | 8080 (+ NodePort 30090) | NodePort 30091 |
## 📈 Scaling and High Availability
@@ -414,7 +473,77 @@ resources:
5. **Updates**: Use rolling updates for zero-downtime deployments
6. **Configuration**: Store configuration in ConfigMaps for flexibility
## 📚 Learning Outcomes
## 🔄 Complete NodePort Flow Explained
### Understanding the Full Request Path
```
┌─────────────────────────────────────────────────────────────────┐
│ Step 1: User with Mycelium Network │
│ • Has Mycelium client running │
│ • Can reach Mycelium IPv6 addresses globally │
│ • Accesses: http://[worker-node-mycelium-ipv6]:30091 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 2: Mycelium Network Routes to Worker Node │
│ • Peer-to-peer IPv6 routing │
│ • No traditional DNS needed │
│ • Direct encrypted connection │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 3: Worker Node Receives Request on Port 30091 │
│ • kube-proxy listens on NodePort 30091 │
│ • Forwards to Service cluster IP │
│ • Preserves source IPv6 (externalTrafficPolicy: Local) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 4: Kubernetes Service Load Balances │
│ • Service receives on port 8080 │
│ • Selects backend pod (app=nginx-nodeport) │
│ • Routes to targetPort 8080 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 5: nginx Pod Processes Request │
│ • Pod in isolated network namespace │
│ • nginx listens on container port 8080 │
│ • Serves HTML from ConfigMap │
│ • Returns response │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 6: Response Returns to User │
│ • Same path in reverse │
│ • User sees website in browser │
│ • Access logs show original IPv6 (source IP preserved) │
└─────────────────────────────────────────────────────────────────┘
```
### Why NodePort is Better for Production
**Security Benefits:**
1. Pods cannot access host network interfaces
2. Network policies can restrict pod-to-pod traffic
3. Resource limits prevent resource exhaustion
4. Health checks ensure reliability
**Operational Benefits:**
1. Standard Kubernetes debugging tools work
2. Can scale horizontally (multiple replicas)
3. Service provides automatic load balancing
4. Compatible with monitoring stacks (Prometheus, etc.)
5. Can evolve to LoadBalancer or Ingress later
**Mycelium Integration:**
- Worker nodes have Mycelium IPv6 addresses
- NodePort makes service accessible via these IPs
- No need for traditional cloud load balancers
- Perfect for decentralized web hosting
## <20> Learning Outcomes
After completing this example, you understand:
- **NodePort Services** - Kubernetes service exposure patterns