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! 🚀**
|
||||
Reference in New Issue
Block a user