feat: Add comprehensive README and deploy script for nginx-nodeport example
This commit is contained in:
mik-tf
235
examples/nginx-nodeport/README.md
Normal file
235
examples/nginx-nodeport/README.md
Normal file
@@ -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! 🚀**
|
||||
187
examples/nginx-nodeport/deploy-and-test.sh
Executable file
187
examples/nginx-nodeport/deploy-and-test.sh
Executable file
@@ -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 ""
|
||||
Reference in New Issue
Block a user