feat: Add comprehensive README and deploy script for nginx-nodeport example

examples/nginx-nodeport/README.md

@@ -0,0 +1,235 @@
+# nginx-nodeport - Mycelium Cloud NodePort Website Example
+
+Complete, production-ready example for deploying a secure, globally accessible website on Mycelium Cloud using **NodePort** services.
+
+## 🚀 Quick Start (One Command!)
+
+**Start here if you want EVERYTHING done automatically:**
+
+```bash
+cd myceliumcloud-examples/examples/nginx-nodeport
+./deploy-and-test.sh
+```
+
+That's it! This script will:
+1. ✅ Deploy all resources (ConfigMaps, Deployment, Service)
+2. ✅ Wait for pods to be ready
+3. ✅ Verify service configuration
+4. ✅ Update website content with current node information
+5. ✅ Apply changes
+6. ✅ Run comprehensive tests
+7. ✅ Show you the access URL
+
+**Output example:**
+```
+🎉 Deploy and Test Complete!
+==================================
+
+🌐 Access Information:
+  • URL: http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:30091
+  • Node: kc22haven612worker1
+
+To access from a machine with Mycelium installed:
+  curl -6 "http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:30091/"
+Or open in browser:
+  http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:30091
+```
+
+---
+
+## 📚 Available Scripts
+
+### 1. `deploy-and-test.sh` - **RECOMMENDED** ⭐
+**The ONE script to do everything from scratch**
+
+```bash
+./deploy-and-test.sh
+```
+
+Does everything: deploy, test, configure, and show results.
+
+### 2. `test-nodeport-ipv6.sh` - Testing Only
+**If you already have nginx-nodeport deployed and want to test it**
+
+```bash
+./test-nodeport-ipv6.sh
+```
+
+Runs comprehensive tests and shows access URLs.
+
+### 3. `update-content.sh` - Content Update
+**Updates website content with current cluster state**
+
+```bash
+./update-content.sh
+kubectl rollout restart deployment/nginx-nodeport
+```
+
+Updates the ConfigMap and restarts pods to apply changes.
+
+---
+
+## 🔧 Manual Deployment (If You Prefer)
+
+If you want to do it step-by-step yourself:
+
+```bash
+# 1. Deploy resources
+kubectl apply -f nginx-nodeport-configmaps.yaml
+kubectl apply -f nginx-nodeport-deployment.yaml
+kubectl apply -f nginx-nodeport-service.yaml
+
+# 2. Wait for ready
+kubectl wait --for=condition=ready pod -l app=nginx-nodeport --timeout=60s
+
+# 3. Update content
+./update-content.sh
+kubectl rollout restart deployment/nginx-nodeport
+
+# 4. Test
+./test-nodeport-ipv6.sh
+```
+
+---
+
+## 🎯 What This Example Teaches
+
+- **NodePort Services** - Standard Kubernetes service exposure
+- **IPv6 Support** - Critical dual-stack configuration for Mycelium
+- **Pod Isolation** - Security without hostNetwork
+- **externalTrafficPolicy: Local** - Preserves source IP
+- **Mycelium Integration** - IPv6 address discovery and access
+
+---
+
+## 📊 Architecture
+
+```
+User (with Mycelium)
+    ↓
+http://[worker-node-mycelium-ipv6]:30091
+    ↓
+kube-proxy (dual-stack enabled)
+    ↓
+Kubernetes Service (IPv4 + IPv6)
+    ↓
+Pod (container port 8080)
+    ↓
+nginx → HTML
+```
+
+**Key Points:**
+- Service type: **NodePort** (not LoadBalancer)
+- IP families: **Dual-stack (IPv4 + IPv6)** ⭐ Critical
+- Pod network: **Isolated** (no hostNetwork)
+- Traffic policy: **Local** (preserves source IP)
+- Port: **30091** (NodePort)
+
+---
+
+## 🌐 Access URLs
+
+**Current deployment (1 pod replica):**
+- **Only accessible on the node where pod is running**
+- Example: `http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:30091`
+
+**To make accessible on all nodes:**
+```bash
+kubectl scale deployment nginx-nodeport --replicas=3
+./update-content.sh
+```
+
+---
+
+## 📁 Files in This Directory
+
+### Configuration
+- `nginx-nodeport-deployment.yaml` - Pod configuration
+- `nginx-nodeport-service.yaml` - NodePort service (dual-stack)
+- `nginx-nodeport-configmaps.yaml` - HTML content + nginx config
+
+### Scripts
+- `deploy-and-test.sh` - ⭐ **Main script** (deploy + test)
+- `test-nodeport-ipv6.sh` - Testing and validation
+- `update-content.sh` - Content updates
+- `debug-nodeport.sh` - Diagnostics
+
+### Documentation
+- `nginx-nodeport.md` - Complete guide
+- `IPV6_FIX.md` - Critical dual-stack configuration
+- `TROUBLESHOOTING.md` - Common issues & solutions
+- `compare-approaches.md` - Security comparison
+- `FINAL_STATUS.md` - Complete implementation status
+
+---
+
+## ✅ Success Indicators
+
+**When working, you'll see:**
+- ✅ Service type: `NodePort`
+- ✅ NodePort: `30091`
+- ✅ IP families: `["IPv4","IPv6"]`
+- ✅ Pod status: `Running`
+- ✅ Test output: `✅ External Mycelium IPv6 connectivity is working!`
+
+---
+
+## 🚨 Prerequisites
+
+1. **kubectl** installed and configured
+2. **Mycelium Cloud cluster** with at least 1 worker node
+3. **Mycelium installed** on your local machine (for testing)
+4. **IPv6 connectivity** (Mycelium provides this)
+
+---
+
+## 🆘 Getting Help
+
+**Common Issues:**
+
+1. **"Failed to connect" error**
+   - Check if Mycelium is running on your local machine
+   - Verify IPv6 connectivity: `ping -6 [ipv6-address]`
+
+2. **"External IPv6 connectivity test failed"**
+   - This is normal if you don't have Mycelium on your machine
+   - The service is still working from within the cluster
+
+3. **Service only accessible on one node**
+   - This is CORRECT with `externalTrafficPolicy: Local` and 1 pod replica
+   - To make accessible on all nodes, scale to 3 replicas
+
+**Troubleshooting:**
+- Run: `./debug-nodeport.sh`
+- Check logs: `kubectl logs -l app=nginx-nodeport --tail=50`
+- Check service: `kubectl describe svc nginx-nodeport-service`
+
+---
+
+## 🔄 Next Steps
+
+1. **Test scaling:**
+   ```bash
+   kubectl scale deployment nginx-nodeport --replicas=3
+   ```
+
+2. **Try other nginx variants:**
+   - [`../nginx-mycelium/`](../nginx-mycelium/) - hostNetwork approach
+   - [`../nginx-static/`](../nginx-static/) - Simple static site
+   - LoadBalancer and Ingress variants (coming soon)
+
+3. **Learn more:**
+   - [Compare all variants](../nginx-variants.md)
+   - [Security comparison](compare-approaches.md)
+
+---
+
+## 🎉 Success!
+
+Once deployed and tested, you'll have a **fully functional website accessible via Mycelium IPv6** with:
+- ✅ Production-ready security (pod isolation)
+- ✅ Standard Kubernetes patterns
+- ✅ Dual-stack IPv4/IPv6 support
+- ✅ Comprehensive testing and monitoring
+
+**Happy deploying! 🚀**

examples/nginx-nodeport/deploy-and-test.sh

@@ -0,0 +1,187 @@
+#!/bin/bash
+
+# Complete Deploy and Test Script for nginx-nodeport
+# This script does EVERYTHING from scratch in the correct order
+
+set -e
+
+echo "🚀 nginx-nodeport Deploy and Test"
+echo "=================================="
+echo ""
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Step 1: Check if kubectl is available
+echo "🔍 Step 1: Checking prerequisites..."
+if ! command -v kubectl &> /dev/null; then
+    echo "❌ kubectl is not installed or not in PATH"
+    echo "   Please install kubectl and configure it to connect to your Mycelium Cloud cluster"
+    exit 1
+fi
+
+# Test cluster connectivity
+if ! kubectl cluster-info &> /dev/null; then
+    echo "❌ Cannot connect to Kubernetes cluster"
+    echo "   Please check your kubeconfig configuration"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ kubectl is available and connected to cluster${NC}"
+echo ""
+
+# Step 2: Deploy all resources
+echo "🔍 Step 2: Deploying nginx-nodeport resources..."
+echo ""
+
+echo "  📦 Deploying ConfigMaps..."
+kubectl apply -f nginx-nodeport-configmaps.yaml
+echo -e "    ${GREEN}✅ ConfigMaps deployed${NC}"
+echo ""
+
+echo "  📦 Deploying nginx application..."
+kubectl apply -f nginx-nodeport-deployment.yaml
+echo -e "    ${GREEN}✅ nginx deployment created${NC}"
+echo ""
+
+echo "  📦 Creating NodePort service..."
+kubectl apply -f nginx-nodeport-service.yaml
+echo -e "    ${GREEN}✅ NodePort service created${NC}"
+echo ""
+
+# Step 3: Wait for deployment to be ready
+echo "🔍 Step 3: Waiting for deployment to be ready..."
+echo ""
+echo "  This may take up to 60 seconds..."
+
+if kubectl wait --for=condition=ready pod -l app=nginx-nodeport --timeout=60s 2>/dev/null; then
+    echo -e "  ${GREEN}✅ nginx-nodeport pods are ready${NC}"
+else
+    echo -e "  ${YELLOW}⚠️  Pods taking longer than expected, continuing anyway...${NC}"
+fi
+echo ""
+
+# Step 4: Check pod status
+echo "🔍 Step 4: Checking pod status..."
+POD_STATUS=$(kubectl get pods -l app=nginx-nodeport -o jsonpath='{.items[0].status.phase}' 2>/dev/null || echo "Unknown")
+echo "  Pod status: $POD_STATUS"
+
+if [ "$POD_STATUS" != "Running" ]; then
+    echo -e "  ${YELLOW}⚠️  Pod is not in Running state. Check with:${NC}"
+    echo "     kubectl get pods -l app=nginx-nodeport"
+    echo "     kubectl describe pod -l app=nginx-nodeport"
+    echo "     kubectl logs -l app=nginx-nodeport"
+fi
+echo ""
+
+# Step 5: Check service configuration
+echo "🔍 Step 5: Verifying service configuration..."
+SERVICE_TYPE=$(kubectl get svc nginx-nodeport-service -o jsonpath='{.spec.type}' 2>/dev/null || echo "NotFound")
+NODEPORT=$(kubectl get svc nginx-nodeport-service -o jsonpath='{.spec.ports[0].nodePort}' 2>/dev/null || echo "NotFound")
+IP_FAMILIES=$(kubectl get svc nginx-nodeport-service -o jsonpath='{.spec.ipFamilies}' 2>/dev/null || echo "NotFound")
+
+echo "  Service type: $SERVICE_TYPE"
+echo "  NodePort: $NODEPORT"
+echo "  IP families: $IP_FAMILIES"
+
+if [ "$SERVICE_TYPE" != "NodePort" ]; then
+    echo -e "  ${YELLOW}⚠️  Service type is not NodePort! Expected: NodePort, Got: $SERVICE_TYPE${NC}"
+fi
+
+if [ "$NODEPORT" != "30091" ]; then
+    echo -e "  ${YELLOW}⚠️  NodePort is not 30091! Expected: 30091, Got: $NODEPORT${NC}"
+fi
+
+if [[ "$IP_FAMILIES" == *"IPv6"* ]]; then
+    echo -e "  ${GREEN}✅ Dual-stack configured (includes IPv6)${NC}"
+else
+    echo -e "  ${YELLOW}⚠️  IPv6 not configured! Service will not be accessible via Mycelium IPv6${NC}"
+    echo "     This is a critical requirement for Mycelium Cloud!"
+fi
+echo ""
+
+# Step 6: Update content with current node information
+echo "🔍 Step 6: Updating website content with current node information..."
+echo ""
+
+./update-content.sh
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✅ Content updated successfully${NC}"
+else
+    echo -e "${YELLOW}⚠️  Content update failed, continuing anyway...${NC}"
+fi
+echo ""
+
+# Step 7: Restart deployment to apply content changes
+echo "🔍 Step 7: Restarting deployment to apply content changes..."
+echo ""
+
+kubectl rollout restart deployment/nginx-nodeport
+
+if kubectl rollout status deployment/nginx-nodeport --timeout=60s 2>/dev/null; then
+    echo -e "${GREEN}✅ Deployment rolled out successfully${NC}"
+else
+    echo -e "${YELLOW}⚠️  Rollout taking longer than expected, continuing...${NC}"
+fi
+echo ""
+
+# Step 8: Run comprehensive tests
+echo "🔍 Step 8: Running comprehensive tests..."
+echo ""
+
+./test-nodeport-ipv6.sh
+
+echo ""
+echo "=================================="
+echo "🎉 Deploy and Test Complete!"
+echo "=================================="
+echo ""
+echo "📊 Summary:"
+echo "  • Resources deployed: ConfigMaps, Deployment, Service"
+echo "  • Service type: NodePort with dual-stack (IPv4 + IPv6)"
+echo "  • NodePort: 30091"
+echo "  • Content updated: Yes"
+echo "  • Tests run: Yes"
+echo ""
+echo "🌐 Access Information:"
+POD_NAME=$(kubectl get pods -l app=nginx-nodeport -o name | head -1 2>/dev/null || echo "")
+if [ -n "$POD_NAME" ]; then
+    POD_NODE=$(kubectl get pods -l app=nginx-nodeport -o jsonpath='{.items[0].spec.nodeName}' 2>/dev/null || echo "Unknown")
+    NODE_IPV6=$(kubectl get node "$POD_NODE" -o jsonpath='{range .status.addresses[?(@.type=="InternalIP")]}{.address}{"\n"}{end}' 2>/dev/null | grep -E '^[0-9a-f]+:[0-9a-f]+:[0-9a-f]+:[0-9a-f]+:[0-9a-f]+:[0-9a-f]+:[0-9a-f]+:[0-9a-f]+$' | head -1 || echo "Unknown")
+    
+    if [ "$NODE_IPV6" != "Unknown" ]; then
+        echo "  • URL: http://[$NODE_IPV6]:30091"
+        echo "  • Node: $POD_NODE"
+        echo ""
+        echo "  To access from a machine with Mycelium installed:"
+        echo "    curl -6 \"http://[$NODE_IPV6]:30091/\""
+        echo "  Or open in browser:"
+        echo "    http://[$NODE_IPV6]:30091"
+    else
+        echo "  • Could not determine node IPv6 address automatically"
+        echo "  • Check manually with:"
+        echo "    kubectl get nodes -o wide"
+    fi
+else
+    echo "  • Could not find nginx-nodeport pod"
+    echo "  • Check status with:"
+    echo "    kubectl get pods -l app=nginx-nodeport"
+fi
+echo ""
+echo "📋 Next Steps:"
+echo "  • Open the URL in a browser to see your website"
+echo "  • Check logs: kubectl logs -f deployment/nginx-nodeport"
+echo "  • Scale replicas: kubectl scale deployment nginx-nodeport --replicas=3"
+echo "  • Update content: ./update-content.sh"
+echo "  • Run tests: ./test-nodeport-ipv6.sh"
+echo ""
+echo "📚 Documentation:"
+echo "  • Guide: nginx-nodeport.md"
+echo "  • IPv6 Fix: IPV6_FIX.md"
+echo "  • Troubleshooting: TROUBLESHOOTING.md"
+echo "  • All variants: ../nginx-variants.md"
+echo ""