diff --git a/examples/nginx-mycelium/nginx-mycelium.md b/examples/nginx-mycelium/nginx-mycelium.md index 18799e3..61485d9 100644 --- a/examples/nginx-mycelium/nginx-mycelium.md +++ b/examples/nginx-mycelium/nginx-mycelium.md @@ -1,459 +1,434 @@ -# ๐ŸŒ Nginx-Mycelium: Global Web Hosting with IPv6 Direct Access +# Mycelium Cloud - Nginx with IPv6 Website Hosting -A **complete and proven** example of hosting a professional website globally using Mycelium Cloud Kubernetes. This demonstrates **real-world web hosting** with custom content and confirmed global accessibility. - -## ๐ŸŽฏ What's This About? - -This example shows how to: -- โœ… **Host a professional website globally** via Mycelium IPv6 addresses -- โœ… **Use hostNetwork deployment** for direct IPv6 interface binding -- โœ… **Serve custom content** with ConfigMap-based content management -- โœ… **Demonstrate confirmed global access** with working IPv6 connectivity +A complete, production-ready example for deploying a globally accessible website on Mycelium Cloud using IPv6 networking. This demonstrates **peer-to-peer web hosting** without traditional hosting infrastructure. ## ๐Ÿ“ What This Contains -``` -nginx-mycelium/ -โ”œโ”€โ”€ nginx-mycelium.md # This comprehensive guide with testing info -โ”œโ”€โ”€ mycelium-website-hostnetwork.yaml # Production deployment with custom website -โ””โ”€โ”€ update-content.sh # Dynamic IPv6 discovery script -``` +This directory contains everything you need to deploy a professional website with global IPv6 accessibility: -## ๐Ÿš€ Quick Start - Global Website (3 minutes) +- **nginx-mycelium.md** - This comprehensive guide +- **mycelium-website-nodeport.yaml** - Complete deployment configuration +- **test-ipv6-website.sh** - IPv6 testing and verification script +- **update-content.sh** - Content update script (for future use) + +## ๐Ÿš€ Quick Start (3 minutes) ```bash -# 1. Deploy the website with hostNetwork for direct IPv6 access -kubectl apply -f mycelium-website-hostnetwork.yaml +# 1. Deploy the website +kubectl apply -f mycelium-website-nodeport.yaml -# 2. Wait for pod to be ready +# 2. Wait for deployment to be ready kubectl wait --for=condition=ready pod -l app=mycelium-website --timeout=60s -# 3. Get the IPv6 address of the pod -NODE_NAME=$(kubectl get pod -l app=mycelium-website -o jsonpath='{.items[0].spec.nodeName}') -MYCELIUM_IP=$(kubectl get node $NODE_NAME -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}') +# 3. Get your IPv6 address +POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1) +kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | head -1 -echo "Website accessible at: http://[$MYCELIUM_IP]:80" - -# 4. Test global access from ANY Mycelium IPv6 address! -curl http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80 -curl http://[476:c4f:b4cb:7205:ff0f:f56e:abea:6905]:80 -curl http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 +# 4. Access your website globally +# Use the IPv6 address from step 3, replace [YOUR-IPV6] below: +curl -6 "http://[YOUR-IPV6]:8080/" ``` -**๐Ÿ”„ Optional: Update Content with Dynamic IPv6 Discovery** +**Expected Result:** You'll see a professional website with gradient styling and IPv6 address detection. -The `update-content.sh` script can be used to regenerate content with current IPv6 addresses: +## ๐Ÿ“‹ What You'll Learn -```bash -# Run to update content with current cluster IPv6 addresses -./update-content.sh - -# This will: -# 1. Discover current Mycelium IPv6 addresses -# 2. Regenerate website content with IPv6 information -# 3. Update the ConfigMap with new content -# 4. Trigger pod update with new content -``` - -## ๐ŸŒ Global Access URLs - -Once deployed, your website is **globally accessible** at all Mycelium IPv6 addresses on port 80: - -``` -๐ŸŒ Master Nodes: -http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80 -http://[476:c4f:b4cb:7205:ff0f:f56e:abea:6905]:80 -http://[538:964a:a1e1:4057:ff0f:63c7:960b:7c27]:80 - -๐ŸŒ Worker Nodes: -http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 -http://[437:9faf:1f1a:e2b1:ff0f:1fd9:7fd5:1095]:80 -http://[5c3:a162:45ab:6c53:ff0f:8c55:36b0:24af]:80 -``` - -**โœ… CONFIRMED WORKING**: Direct IPv6 connectivity has been tested and verified! - -**๐Ÿ”„ Dynamic Discovery**: IPv6 addresses are automatically discovered from your cluster using the `update-content.sh` script, ensuring the URLs always match your current infrastructure. +- โœ… IPv6-only web hosting on Mycelium Cloud +- โœ… Production nginx configuration with dual-stack support +- โœ… ConfigMap-based content management +- โœ… Global accessibility via peer-to-peer networking +- โœ… hostNetwork deployment patterns +- โœ… IPv6 troubleshooting and verification ## ๐Ÿ—๏ธ Architecture -### hostNetwork Direct Access Design +This example uses a **single-file approach** with integrated components: -``` -๐ŸŒ Internet (Mycelium Clients) - โ†“ -๐ŸŒ Mycelium IPv6 Network (Port 80) - โ†“ -๐Ÿ–ฅ๏ธ hostNetwork Pod (direct IPv6 interface binding) - โ†“ -๐Ÿ“Š Custom Website Content (ConfigMap-managed) - โ†“ -๐Ÿ”„ nginx Web Server (custom content, health endpoints) -``` +1. **Deployment** - Pod with nginx and custom content +2. **ConfigMaps** - HTML content and nginx configuration +3. **Service** - NodePort for external accessibility -### Key Features +**Network Flow:** `Direct IPv6 โ†’ nginx:8080 โ†’ Custom HTML` -#### **Kubernetes Deployment with hostNetwork** +**Key Innovation:** Uses `hostNetwork: true` for direct access to Mycelium IPv6 interfaces. + +## ๐Ÿ”ง Files Explanation + +### mycelium-website-nodeport.yaml ```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: mycelium-website spec: + replicas: 1 template: spec: - hostNetwork: true # Direct IPv6 interface binding + hostNetwork: true # Direct IPv6 access containers: - name: nginx image: nginx:alpine ports: - - containerPort: 80 # Standard web port - hostPort: 80 # Direct host binding + - containerPort: 8080 + hostPort: 8080 + volumeMounts: + - name: html-content + mountPath: /usr/share/nginx/html + - name: nginx-config + mountPath: /etc/nginx/conf.d + volumes: + - name: html-content + configMap: + name: mycelium-website-content + - name: nginx-config + configMap: + name: mycelium-nginx-config ``` -#### **Dynamic IPv6 Discovery** -The `update-content.sh` script automatically discovers Mycelium IPv6 addresses from your cluster: +**What it does:** +- Creates 1 pod with nginx and custom website content +- Uses `hostNetwork: true` for direct IPv6 interface access +- Includes ConfigMaps for dynamic content management +- Dual-stack nginx (IPv4 + IPv6) configuration + +## ๐ŸŒ Access Methods + +### Method 1: Direct IPv6 (Primary - Recommended) ```bash -# Run the script to update content with current IPv6 addresses -./update-content.sh +# Get your pod's IPv6 address +POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1) +IPV6=$(kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | head -1 | awk '{print $2}' | cut -d'/' -f1) -# The script will: -# 1. Query kubectl for cluster node IPv6 addresses -# 2. Generate HTML with dynamic address discovery -# 3. Update the ConfigMap automatically -# 4. Show website content with current cluster state +# Access your website +curl -6 "http://[$IPV6]:8080/" +curl -6 "http://[$IPV6]:8080/health" + +# Or in browser: http://[YOUR-IPV6]:8080/ ``` -#### **Custom Website Content** -The deployment includes a professional website with: -- Modern HTML design with Mycelium Cloud branding -- Responsive layout with gradient backgrounds -- Interactive IPv6 address detection -- Real-time timestamp updates -- Professional web interface +**Why this works:** +- `hostNetwork: true` gives direct access to host IPv6 interfaces +- nginx listens on both IPv4 and IPv6 +- Mycelium provides globally routable IPv6 addresses +- No port translation or proxy needed -#### **Content Management** -```yaml -volumes: -- name: html-content - configMap: - name: mycelium-website-content # Custom website content -- name: nginx-config - configMap: - name: mycelium-nginx-config # nginx configuration -``` +### Method 2: Health Check Verification -## ๐ŸŒŸ Direct IPv6 Access Benefits - -### **Direct Interface Binding** -- **hostNetwork: true**: Pod directly binds to host network interface -- **IPv6 Address Access**: Gets Mycelium IPv6 address from host node -- **Simplified Architecture**: No service layer needed for IPv6 access -- **Direct Connectivity**: External clients connect directly to pod - -### **Performance Advantages** -- **Zero Latency**: Direct interface binding, no service proxy overhead -- **Full IPv6 Support**: Direct access to Mycelium IPv6 addresses -- **Simple Deployment**: Single pod with hostNetwork configuration -- **Production Ready**: Standard nginx configuration with health endpoints - -### **Global Accessibility** ```bash -# Access directly via any Mycelium IPv6 address -curl http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 +# Test health endpoint +curl -6 "http://[YOUR-IPV6]:8080/health" +# Expected: "healthy" + +# Test main page (should return 3975+ bytes) +curl -6 "http://[YOUR-IPV6]:8080/" | wc -c +# Expected: 3975 (or similar large number) ``` -## ๐Ÿ”ง Testing & Verification +### Method 3: Interactive Testing -### **โœ… CONFIRMED: IPv6 Connectivity Test** ```bash -# โœ… VERIFIED: Direct IPv6 connectivity working! -curl -v http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 - -# Expected output shows successful connection: -# * Connected to 552:5984:2d97:72dc:ff0f:39ef:6ec:a48c (552:5984:2d97:72dc:ff0f:39ef:6ec:a48c) port 80 (#0) -# < HTTP/1.1 200 OK (or 404 if serving default content) -``` - -### **๐ŸŽฏ Pod Status Verification** -```bash -# Check pod status and location -kubectl get pods -l app=mycelium-website -o wide - -# Expected output shows: -# NAME READY STATUS NODE -# mycelium-website-xxxx-xxxx 1/1 Running kc22haven612worker1 - -# Get the IPv6 address of the pod's node -NODE_NAME=$(kubectl get pod -l app=mycelium-website -o jsonpath='{.items[0].spec.nodeName}') -MYCELIUM_IP=$(kubectl get node $NODE_NAME -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}') -echo "Pod running on: $NODE_NAME with IPv6: $MYCELIUM_IP" -``` - -### **๐ŸŒ Direct IPv6 Access Test** -```bash -# Test from multiple IPv6 addresses (all should work): -curl http://[51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c]:80 -curl http://[476:c4f:b4cb:7205:ff0f:f56e:abea:6905]:80 -curl http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 -curl http://[437:9faf:1f1a:e2b1:ff0f:1fd9:7fd5:1095]:80 -curl http://[5c3:a162:45ab:6c53:ff0f:8c55:36b0:24af]:80 -curl http://[538:964a:a1e1:4057:ff0f:63c7:960b:7c27]:80 - -# All should return the custom Mycelium Cloud website HTML -``` - -### **๐Ÿฅ Health Endpoint Test** -```bash -# Test the health endpoint -kubectl exec pod/mycelium-website-xxxx-xxxx -- curl -s http://localhost:8080/health - -# Expected output: "healthy" -``` - -### **๐Ÿ“Š Content Verification** -```bash -# Check that custom content is being served -curl -s http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 | head -10 - -# Should show the custom Mycelium Cloud website HTML with: -# - Mycelium Cloud - Globally Accessible Website -# - Professional styling and branding -``` - -### **๐Ÿ” Network Interface Verification** -```bash -# Verify hostNetwork binding -kubectl exec pod/mycelium-website-xxxx-xxxx -- ip addr show | grep inet6 - -# Should show the Mycelium IPv6 address bound to the pod -# Example: inet6 552:5984:2d97:72dc:ff0f:39ef:6ec:a48c/64 scope global -``` - -### **๐Ÿ“ˆ Load Testing** -```bash -# Test concurrent requests -for i in {1..5}; do - curl -s http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:80 > /dev/null & -done -wait - -# Monitor nginx logs -kubectl logs -l app=mycelium-website --tail=10 -``` - -## ๐ŸŒ Global Use Cases - -### **Perfect For:** -- โœ… **Static Website Hosting**: Company sites, portfolios, blogs -- โœ… **Application Frontends**: Web UIs for your applications -- โœ… **Documentation Sites**: API docs, user guides -- โœ… **Proof of Concepts**: Demonstrate global infrastructure -- โœ… **Multi-Region Access**: Users worldwide access the same site - -### **Technical Benefits:** -- โœ… **Global CDN**: No centralized server, distributed across nodes -- โœ… **Low Latency**: Users connect to nearest healthy pod -- โœ… **No Bandwidth Limits**: Uses Mycelium's peer-to-peer network -- โœ… **Automatic Scaling**: Kubernetes handles pod creation/deletion - -## ๐Ÿ“‹ Monitoring & Management - -### **Real-Time Status** -```bash -# Check deployment status -kubectl get deployment nginx-mycelium - -# View service configuration -kubectl get svc nginx-mycelium-service -o yaml - -# Check external IPs are configured -kubectl get svc nginx-mycelium-service -``` - -### **Performance Monitoring** -```bash -# Check resource usage -kubectl top pods -l app=nginx-mycelium - -# Monitor nginx access logs -kubectl logs -l app=nginx-mycelium -f - -# Check pod distribution -kubectl get pods -l app=nginx-mycelium -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,IP:.status.podIP -``` - -### **Scaling Operations** -```bash -# Current replica count -kubectl get deployment nginx-mycelium - -# Scale up for more capacity -kubectl scale deployment nginx-mycelium --replicas=5 - -# Check load distribution after scaling -kubectl get pods -l app=nginx-mycelium -o wide +# Keep testing connection +watch -n 2 'curl -6 -s "http://[YOUR-IPV6]:8080/health" && echo " - $(date)"' ``` ## ๐Ÿ” Troubleshooting -### **Common Issues** +### Check Deployment Status +```bash +# Check if pods are running +kubectl get pods -l app=mycelium-website -#### **Pod Won't Start** +# Check service details +kubectl get svc mycelium-website-service + +# Check what's deployed +kubectl get all -l app=mycelium-website + +# Verify nginx is listening on both IPv4 and IPv6 +POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1) +kubectl exec $POD_NAME -- netstat -tuln | grep 8080 +``` + +### Common Issues + +#### IPv6 Binding Problems +```bash +# Problem: nginx only listening on IPv4 +# Check current binding: +kubectl exec $POD_NAME -- netstat -tuln | grep 8080 + +# Should show: +# tcp 0 0 0.0.0.0:8080 0.0.0.0:* LISTEN +# tcp 0 0 :::8080 :::* LISTEN (IPv6) + +# If missing IPv6, restart the deployment: +kubectl delete pod $POD_NAME +``` + +#### Pod Not Starting ```bash # Check pod status and events -kubectl describe pod -l app=nginx-mycelium +kubectl describe pod -l app=mycelium-website -# Check node resource availability -kubectl get nodes +# Check pod logs +kubectl logs -l app=mycelium-website -# Look for scheduling issues -kubectl get events --sort-by='.lastTimestamp' +# Check nginx configuration +kubectl exec $POD_NAME -- cat /etc/nginx/conf.d/default.conf ``` -#### **IPv6 Access Not Working** +#### IPv6 Not Accessible ```bash +# Verify IPv6 address exists +kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" + # Test IPv6 connectivity -ping 51d:3596:6cc3:81e7:ff0f:d546:3737:4c8c +ping6 [YOUR-IPV6] -# Check if pods are running -kubectl get pods -l app=nginx-mycelium - -# Verify service configuration -kubectl get svc nginx-mycelium-service -o wide +# Test nginx inside pod +kubectl exec $POD_NAME -- curl -s http://localhost:8080/health ``` -#### **Load Balancing Issues** +#### Content Not Loading ```bash -# Check all pods are ready -kubectl get pods -l app=nginx-mycelium +# Verify ConfigMaps are mounted +kubectl exec $POD_NAME -- ls -la /usr/share/nginx/html/ -# Verify endpoints are healthy -kubectl get endpoints nginx-mycelium-service +# Check actual content +kubectl exec $POD_NAME -- cat /usr/share/nginx/html/index.html | head -10 -# Check pod logs for errors -kubectl logs -l app=nginx-mycelium +# Verify nginx config is loaded +kubectl exec $POD_NAME -- nginx -t ``` -## ๐ŸŽฏ Best Practices +## ๐Ÿ› ๏ธ Common Operations -### **Deployment Strategy** -1. **Start Small**: Deploy 1 replica initially -2. **Test Connectivity**: Verify IPv6 access works -3. **Scale Gradually**: Increase replicas based on traffic -4. **Monitor Performance**: Watch resource usage and response times - -### **Content Management** -- **Static Files**: Update `index.html` for content changes -- **Volume Mounts**: Use ConfigMaps for dynamic content -- **Health Checks**: Implement proper liveness/readiness probes - -### **Security Considerations** -- **No Authentication**: Open access for demonstration purposes -- **Rate Limiting**: Consider adding nginx rate limiting for production -- **HTTPS**: Use TF Gateway CRDs for SSL certificates - -## ๐Ÿš€ Advanced Features - -### **Custom Content** -Replace the `index.html` with your own content: +### Updating Website Content ```bash -# Update content -kubectl create configmap nginx-content --from-file=index.html=custom.html +# Update the ConfigMap with new HTML content +kubectl create configmap mycelium-website-content \ + --from-file=index.html=./new-website.html \ + --dry-run=client -o yaml | kubectl apply -f - -# Rollout update -kubectl rollout restart deployment/nginx-mycelium +# Restart pod to pick up changes +POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1) +kubectl delete pod $POD_NAME ``` -### **Additional Services** -Add more services following the same pattern: +### Scaling ```bash -# Apply additional nginx services -kubectl apply -f additional-services.yaml +# Scale to 2 replicas (each gets different IPv6) +kubectl scale deployment mycelium-website --replicas=2 -# Each service gets its own LoadBalancer with IPv6 +# Check distribution across nodes +kubectl get pods -o wide -l app=mycelium-website ``` -### **TF Gateway Integration** -For custom domains and HTTPS: -```yaml -# Use TF Gateway CRD for public domain -apiVersion: ingress.grid.tf/v1 -kind: TFGW +### Monitoring +```bash +# View nginx logs +kubectl logs -f deployment/mycelium-website + +# Check resource usage +kubectl top pod -l app=mycelium-website + +# Monitor IPv6 addresses +watch 'kubectl get pods -o wide -l app=mycelium-website' +``` + +### IPv6 Address Discovery +```bash +# Get all IPv6 addresses for the website pod +POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1) +kubectl exec $POD_NAME -- ip addr show | grep "inet6" | grep "scope global" + +# Test multiple IPv6 addresses +for ipv6 in $(kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | awk '{print $2}' | cut -d'/' -f1); do + echo "Testing IPv6: $ipv6" + curl -6 -m 2 "http://[$ipv6]:8080/health" && echo " - SUCCESS" || echo " - FAILED" +done +``` + +## ๐Ÿงน Cleanup + +When you're done testing: + +```bash +# Delete the entire deployment +kubectl delete -f mycelium-website-nodeport.yaml + +# Verify cleanup +kubectl get all -l app=mycelium-website + +# Remove any lingering ConfigMaps (optional) +kubectl delete configmap mycelium-website-content mycelium-nginx-config +``` + +## ๐ŸŽฏ What This Demonstrates + +This example shows: +- **IPv6-Only Web Hosting** - Complete website delivery via peer-to-peer networking +- **Production nginx Configuration** - Dual-stack (IPv4/IPv6) web server +- **Dynamic Content Management** - ConfigMaps for easy updates +- **Global Accessibility** - Direct IPv6 URL access worldwide +- **Kubernetes Best Practices** - Proper separation of concerns + +## ๐Ÿ”— Next Steps + +Once you understand this example, try: + +1. **SSL/HTTPS** - Add TLS termination for secure communications +2. **Custom Domains** - Integrate with Mycelium DNS services +3. **Multiple Applications** - Deploy several websites with load balancing +4. **Monitoring** - Add Prometheus/Grafana for observability +5. **CDN Integration** - Leverage Mycelium's distributed nature + +## ๐Ÿ“š Advanced Features + +### Custom nginx Configuration +```bash +# Edit nginx config +kubectl create configmap mycelium-nginx-config \ + --from-file=default.conf=./custom-nginx.conf \ + --dry-run=client -o yaml | kubectl apply -f - + +# Restart to apply +kubectl rollout restart deployment/mycelium-website +``` + +### Multiple Website Support +```bash +# Deploy multiple websites (each gets unique IPv6) +kubectl apply -f - <