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. test-nodeport-ipv6.sh - Testing Only

If you already have nginx-nodeport deployed and want to test it

./test-nodeport-ipv6.sh

Runs comprehensive tests and shows access URLs.

3. 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

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

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)

3. Learn more:

   • Compare all variants
   • Security comparison

---

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