diff --git a/docs/nginx-multi-service-implementation-plan.md b/docs/nginx-multi-service-implementation-plan.md index 6c5068b..f79882b 100644 --- a/docs/nginx-multi-service-implementation-plan.md +++ b/docs/nginx-multi-service-implementation-plan.md @@ -6,8 +6,8 @@ This document outlines the complete design and implementation plan for creating ## ๐ฏ Objectives -1. **Create nginx-nodeport/** - Standard NodePort service approach -2. **Create nginx-load-balancer/** - LoadBalancer service approach +1. **Create nginx-nodeport/** - Standard NodePort service approach โ **COMPLETED** +2. **Create nginx-load-balancer/** - LoadBalancer service approach 3. **Create nginx-ingress/** - Ingress controller approach 4. **Maintain nginx-mycelium/** - Original hostNetwork approach 5. **Provide comprehensive comparison** - Help users choose best approach @@ -390,10 +390,17 @@ nginx-ingress/ ## ๐ Next Actions -### Immediate (This Week) -1. **Implement nginx-nodeport/** - Security improvement -2. **Deploy and test** on clean Mycelium cluster -3. **Document results** and validate approach +### Immediate (This Week) โ COMPLETED +1. **โ Implement nginx-nodeport/** - Security improvement + - โ Standard NodePort service approach with IPv6 support + - โ Worker node preferences for production deployments + - โ Multi-replica scaling with proper content management + - โ Network debugging tools and comprehensive documentation +2. **โ Deploy and test** on clean Mycelium cluster +3. **โ Document results** and validate approach + - โ Fixed scaling issues and added debugging capabilities + - โ Created production-ready deployment patterns + - โ Updated roadmap and implementation plans ### Short-term (Next Sprint) 1. **Implement nginx-load-balancer/** - Production readiness diff --git a/docs/roadmap.md b/docs/roadmap.md index cb561cc..44eab50 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -41,44 +41,44 @@ Comprehensive progression of Kubernetes examples designed to teach MyceliumCloud - **Template**: Same efficient pattern with `redis-cache.md` + `redis-cache-deployment.yaml` + `redis-cache-service.yaml` + `web-interface.py` - **Key Concepts**: Redis deployment, data persistence, cache strategies, web interface +#### 6. Nginx NodePort Website โ +- **Difficulty**: โญโญ Medium +- **Status**: โ **COMPLETED** +- **Learning Focus**: Standard Kubernetes NodePort services, multi-replica scaling, worker node preferences +- **Template**: Enhanced pattern with `nginx-nodeport.md` + `nginx-nodeport-deployment.yaml` + `nginx-nodeport-service.yaml` + `nginx-nodeport-configmaps.yaml` + supporting scripts (`update-content-single.sh`, `update-content-many.sh`, `debug-networking.sh`) +- **Key Concepts**: NodePort services, IPv6 global access, multi-replica scaling, worker-only deployments, network debugging, production-ready scaling + ### Planned Examples (Future) -#### 6. PostgreSQL Database +#### 7. PostgreSQL Database - **Difficulty**: โญโญ Medium - **Status**: ๐ Planned - **Learning Focus**: Stateful applications, database deployment - **Template**: Same efficient pattern - **Key Concepts**: Persistent volumes, databases, data persistence -#### 6. PostgreSQL Database -- **Difficulty**: โญโญ Medium -- **Status**: ๐ Planned -- **Learning Focus**: Stateful applications, database deployment -- **Template**: Same efficient pattern -- **Key Concepts**: Persistent volumes, databases, data persistence - -#### 7. WordPress +#### 8. WordPress - **Difficulty**: โญโญโญ Hard - **Status**: ๐ Planned - **Learning Focus**: Multi-container applications, CMS deployment - **Template**: Same efficient pattern - **Key Concepts**: Multi-container apps, database integration, CMS deployment -#### 8. Node.js API +#### 9. Node.js API - **Difficulty**: โญโญโญ Hard - **Status**: ๐ Planned - **Learning Focus**: Modern web development, API services - **Template**: Same efficient pattern - **Key Concepts**: JavaScript/Node.js, API development, modern frameworks -#### 9. Jenkins CI/CD +#### 10. Jenkins CI/CD - **Difficulty**: โญโญโญ Hard - **Status**: ๐ Planned - **Learning Focus**: Infrastructure automation, CI/CD pipelines - **Template**: Same efficient pattern - **Key Concepts**: DevOps tools, automation, infrastructure as code -#### 10. Nextcloud +#### 11. Nextcloud - **Difficulty**: โญโญโญ Very Hard - **Status**: ๐ Planned - **Learning Focus**: Enterprise applications, file sharing, high availability @@ -103,6 +103,7 @@ Comprehensive progression of Kubernetes examples designed to teach MyceliumCloud **Focus**: Advanced networking and data services - Nginx Mycelium IPv6 Hosting: Peer-to-peer IPv6 web hosting - Redis Cache: In-memory data and caching +- Nginx NodePort Website: Standard K8s NodePort services - PostgreSQL Database: Persistent data **Skills Taught**: @@ -112,6 +113,8 @@ Comprehensive progression of Kubernetes examples designed to teach MyceliumCloud - Database deployment patterns - Service discovery - Global accessibility via IPv6 +- Multi-replica scaling +- Production-ready deployments ### Hard Level (โญโญโญ) **Focus**: Complex applications and enterprise patterns @@ -173,18 +176,19 @@ Each example includes: ## ๐ Skills Matrix -| Example | Containers | Persistence | Multi-Container | Load Balancing | Databases | APIs | DevOps | Enterprise | IPv6 | Peer-to-Peer | -|---------|------------|-------------|-----------------|----------------|-----------|------|--------|------------|-----|--------------| -| Hello World | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Nginx Static | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Python Flask | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Nginx Mycelium IPv6 | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Redis Cache | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| PostgreSQL | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| WordPress | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Node.js API | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Jenkins CI/CD | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | -| Nextcloud | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Example | Containers | Persistence | Multi-Container | Load Balancing | Databases | APIs | DevOps | Enterprise | IPv6 | Peer-to-Peer | NodePort | Multi-Replica | +|---------|------------|-------------|-----------------|----------------|-----------|------|--------|------------|-----|--------------|----------|---------------| +| Hello World | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Nginx Static | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Python Flask | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Nginx Mycelium IPv6 | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Redis Cache | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Nginx NodePort Website | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| PostgreSQL | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| WordPress | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Node.js API | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Jenkins CI/CD | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Nextcloud | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | ## ๐ Current Status & Next Steps @@ -194,10 +198,11 @@ Each example includes: - **Python Flask API** - Web service development (Completed) - **Nginx Mycelium IPv6** - Peer-to-peer IPv6 web hosting (Completed) - **Redis Cache** - Data caching services (Completed) +- **Nginx NodePort Website** - Standard K8s NodePort services with multi-replica scaling (Completed) ### Next Planned Example 1. **PostgreSQL Database** - Stateful database deployment - - Copy nginx-mycelium template structure + - Copy nginx-nodeport template structure - Adapt for PostgreSQL database needs - Include persistent volume management - Test database connectivity and data persistence @@ -216,6 +221,12 @@ Each example includes: - All examples must be **copy-paste ready** - All examples must include **cleanup instructions** +### Special Focus Areas +- **IPv6 Networking**: Mycelium's unique capability for global IPv6 access +- **Multi-Replica Scaling**: Production-ready scaling patterns +- **Worker Node Preferences**: Best practices for separating control plane and worker workloads +- **Network Debugging**: Tools and techniques for troubleshooting connectivity issues + --- -**Goal**: Provide MyceliumCloud users with a complete learning path from basic Kubernetes deployment to enterprise application management, using proven patterns and consistent documentation. \ No newline at end of file +**Goal**: Provide MyceliumCloud users with a complete learning path from basic Kubernetes deployment to enterprise application management, using proven patterns and consistent documentation, with special emphasis on IPv6 networking and production-ready scaling. \ No newline at end of file diff --git a/examples/nginx-nodeport/README.md b/examples/nginx-nodeport/README.md deleted file mode 100644 index 64875cb..0000000 --- a/examples/nginx-nodeport/README.md +++ /dev/null @@ -1,216 +0,0 @@ -# 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. `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 - ---- - -## ๐ฏ 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) - -## ๐ 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! ๐** \ No newline at end of file diff --git a/examples/nginx-nodeport/debug-networking.sh b/examples/nginx-nodeport/debug-networking.sh new file mode 100755 index 0000000..07fffce --- /dev/null +++ b/examples/nginx-nodeport/debug-networking.sh @@ -0,0 +1,71 @@ +#!/bin/bash + +# Diagnostic script to debug NodePort networking issues +# This helps identify why some URLs work and others don't + +echo "๐ NodePort Networking Diagnostics" +echo "==================================" +echo "" + +# Check pod locations +echo "๐ Current Pod Locations:" +kubectl get pods -l app=nginx-nodeport -o wide +echo "" + +# Check node information +echo "๐ Node Information:" +kubectl get nodes -o wide +echo "" + +# Check service status +echo "๐ง Service Status:" +kubectl get svc nginx-nodeport-service +echo "" + +# Test connectivity to each node +echo "๐งช Connectivity Tests:" +echo "" + +PODS=$(kubectl get pods -l app=nginx-nodeport -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}') + +while IFS=$'\t' read -r pod_name node_name; do + echo "Testing pod: $pod_name on node: $node_name" + + # Get IPv6 for this specific node + IPV6=$(kubectl get node "$node_name" -o jsonpath='{range .status.addresses[?(@.type=="InternalIP")]}{.address}{"\n"}{end}' | 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) + + if [ ! -z "$IPV6" ]; then + echo " Node IPv6: $IPV6" + echo " Testing connectivity: curl -6 --connect-timeout 5 http://[$IPV6]:30091/health" + + # Test HTTP connectivity + if curl -6 --connect-timeout 5 -s "http://[$IPV6]:30091/health" >/dev/null 2>&1; then + echo " โ HTTP connectivity: WORKING" + else + echo " โ HTTP connectivity: FAILED" + fi + + # Test ICMP connectivity + echo " Testing ping: ping -6 -c 2 -W 3 $IPV6" + if ping -6 -c 2 -W 3 "$IPV6" >/dev/null 2>&1; then + echo " โ ICMP connectivity: WORKING" + else + echo " โ ICMP connectivity: FAILED" + fi + else + echo " โ No IPv6 found for node: $node_name" + fi + echo "" +done <<< "$PODS" + +echo "๐ Summary:" +echo "This shows which nodes actually have pods and whether they're accessible" +echo "" +echo "If some URLs work and others don't, it means:" +echo " โ Working URLs: Nodes with good Mycelium connectivity" +echo " โ Failed URLs: Nodes with poor Mycelium connectivity or network issues" +echo "" +echo "To fix connectivity issues:" +echo " 1. Check Mycelium status on affected nodes" +echo " 2. Restart Mycelium on nodes with failed connectivity" +echo " 3. Scale to replicas only on nodes with good connectivity" \ No newline at end of file diff --git a/examples/nginx-nodeport/update-content-fixed.sh b/examples/nginx-nodeport/update-content-many.sh similarity index 100% rename from examples/nginx-nodeport/update-content-fixed.sh rename to examples/nginx-nodeport/update-content-many.sh diff --git a/examples/nginx-nodeport/update-content-multi.sh b/examples/nginx-nodeport/update-content-multi.sh deleted file mode 100755 index 1188b62..0000000 --- a/examples/nginx-nodeport/update-content-multi.sh +++ /dev/null @@ -1,312 +0,0 @@ -#!/bin/bash - -# Dynamic Mycelium IPv6 Address Discovery Script for Multi-Replica NodePort -# This script fetches Mycelium IPv6 addresses from ALL nodes where pods are running -# Works correctly with externalTrafficPolicy: Local and multiple replicas - -set -e - -echo "๐ Discovering Mycelium IPv6 addresses for ALL pod nodes..." - -# Get ALL nginx-nodeport pods -POD_COUNT=$(kubectl get pods -l app=nginx-nodeport --no-headers | wc -l) -echo "Found $POD_COUNT pods running" - -if [ "$POD_COUNT" -eq 0 ]; then - echo "โ No nginx-nodeport pod found!" - echo "Please deploy the nginx-nodeport example first:" - echo " kubectl apply -f nginx-nodeport-deployment.yaml" - exit 1 -fi - -# Collect all node information -declare -A NODE_IPV6_MAP -declare -a NODES_WITH_PODS -declare -a IPV6_ADDRESSES - -echo "Collecting node information for all pods..." - -# Read pod data into array first to avoid subshell issues -mapfile -t POD_DATA < <(kubectl get pods -l app=nginx-nodeport -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}') - -for line in "${POD_DATA[@]}"; do - IFS=$'\t' read -r pod_name node_name <<< "$line" - if [ ! -z "$node_name" ] && [ "${NODE_IPV6_MAP[$node_name]+isset}" = "" ]; then - echo "Pod $pod_name is on node $node_name" - # Get IPv6 address for this node - IPV6=$(kubectl get node "$node_name" -o jsonpath='{range .status.addresses[?(@.type=="InternalIP")]}{.address}{"\n"}{end}' | 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) - if [ ! -z "$IPV6" ]; then - NODE_IPV6_MAP[$node_name]=$IPV6 - NODES_WITH_PODS+=("$node_name") - IPV6_ADDRESSES+=("$IPV6") - echo " โ Node $node_name has IPv6: $IPV6" - else - echo " โ No IPv6 found for node $node_name" - fi - fi -done - -# Build the IPv6 addresses string -IPV6_LIST="" -FIRST=true -for ipv6 in "${IPV6_ADDRESSES[@]}"; do - if [ "$FIRST" = true ]; then - IPV6_LIST="$ipv6" - FIRST=false - else - IPV6_LIST="$IPV6_LIST $ipv6" - fi -done - -if [ ${#IPV6_ADDRESSES[@]} -eq 0 ]; then - echo "โ No IPv6 addresses found for any pod nodes!" - exit 1 -fi - -echo "โ Found ${#IPV6_ADDRESSES[@]} accessible nodes with pods:" -for i in "${!NODES_WITH_PODS[@]}"; do - echo " ${NODES_WITH_PODS[$i]}: ${IPV6_ADDRESSES[$i]}" -done - -# Generate HTML content with all accessible addresses -cat > /tmp/index.html << 'HTML_EOF' - - -
- - -Your website is accessible via these Mycelium worker node IPv6 addresses:
-http://[$ipv6]:30091 โ
WORKINGREPLICA_COUNT replicas are accessible with externalTrafficPolicy: LocalREPLICA_COUNT nodes where pods are running.
- Anyone with Mycelium installed can access your website from any of these URLs from anywhere in the world!
-