myceliumcloud-examples/examples/nginx-nodeport/README.md

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:

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

./deploy-and-test.sh

Does everything: deploy, test, configure, and show results.

2. update-content.sh - Content Update

Updates website content with current cluster state

./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:

# 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

---

## 🎯 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:

   kubectl scale deployment nginx-nodeport --replicas=3
   

2. Try other nginx variants:

   • ../nginx-mycelium/ - hostNetwork approach
   • ../nginx-static/ - Simple static site
   • LoadBalancer and Ingress variants (coming soon)

🎉 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! 🚀