myceliumcloud-examples/examples/nginx-nodeport/nginx-nodeport.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 with **worker node preference**.

## 🚀 Learn by Doing (Recommended!)

**This example is designed to teach you NodePort scaling step-by-step:**

### Step 1: Start with 1 Replica (Worker Node Only)
```bash
cd myceliumcloud-examples/examples/nginx-nodeport
./deploy-and-test.sh
```

**What happens:**
- ✅ Deploys 1 pod replica on a **worker node** (not master)
- ✅ Service accessible on 1 worker node only
- ✅ Easy to understand and test
- ✅ Shows you the single access URL

### Step 2: Scale to 3 Worker Replicas (Production Ready!)
```bash
# Scale to 3 replicas (all on worker nodes)
kubectl scale deployment nginx-nodeport --replicas=3

# Update content to show ALL accessible worker nodes
./update-content-many.sh

# Apply the changes
kubectl rollout restart deployment/nginx-nodeport
```

**What happens:**
- ✅ Service now accessible on 3 worker nodes
- ✅ Automatic load distribution across workers
- ✅ Shows you all 3 working URLs
- ✅ Perfect for production use

**Example 3-worker output:**
```
🌐 Access Information:
  • URL 1: http://[437:9faf:1f1a:e2b1:ff0f:1fd9:7fd5:1095]:30091 (Worker Node)
  • URL 2: http://[552:5984:2d97:72dc:ff0f:39ef:6ec:a48c]:30091 (Worker Node) 
  • URL 3: http://[5c3:a162:45ab:6c53:ff0f:8c55:36b0:24af]:30091 (Worker Node)

✅ All 3 worker replicas working! Anyone can access from anywhere with Mycelium!
```

---

## 🎯 Learning Journey

1. **Start Simple**: Deploy 1 worker replica to understand the basics
2. **Scale Up**: Add 2 more worker replicas to see load distribution
3. **Production Ready**: Learn how externalTrafficPolicy: Local works on workers
4. **Global Access**: Understand Mycelium IPv6 networking from worker nodes

---

## 📚 Available Scripts

### 1. `deploy-and-test.sh` - **Start Here** ⭐
**Deploys 1 replica and shows you the basics**

```bash
./deploy-and-test.sh
```

Does everything: deploy 1 worker replica, test, configure, and show results.

### 2. `update-content-many.sh` - **For Multiple Worker Replicas** 🚀
**Updates content to show all worker replica URLs**

```bash
# After scaling to 3 worker replicas
./update-content-many.sh
kubectl rollout restart deployment/nginx-nodeport
```

This script properly handles multiple worker replicas and shows all accessible URLs.

### 3. `update-content-single.sh` - **For Single Worker Replica** 📝
**For single worker replica deployments** - updates content for 1 worker pod

### 4. `debug-networking.sh` - **Troubleshooting** 🔧
**Diagnose networking issues and verify all URLs are working**

```bash
./debug-networking.sh
```

Tests connectivity to all nodes and shows which URLs are working.

---

## 🔧 Manual Step-by-Step (Alternative)

If you want to do everything manually to learn the details:

```bash
# Step 1: Deploy resources
kubectl apply -f nginx-nodeport-configmaps.yaml
kubectl apply -f nginx-nodeport-deployment.yaml
kubectl apply -f nginx-nodeport-service.yaml

# Step 2: Wait for ready
kubectl wait --for=condition=ready pod -l app=nginx-nodeport --timeout=60s

# Step 3: Test 1 worker replica
curl -6 "http://[your-worker-node-ipv6]:30091/"

# Step 4: Scale to 3 worker replicas
kubectl scale deployment nginx-nodeport --replicas=3

# Step 5: Update content for all worker replicas
./update-content-many.sh
kubectl rollout restart deployment/nginx-nodeport

# Step 6: Verify all URLs work
./debug-networking.sh
```

---

## 📊 Architecture

```
User (with Mycelium)
    ↓
http://[worker-node-mycelium-ipv6]:30091
    ↓
kube-proxy (dual-stack enabled)
    ↓
Kubernetes Service (IPv4 + IPv6)
    ↓
Pod (container port 8080) ← 1-3 pods on worker nodes only
    ↓
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)
- Node preference: **Worker nodes only** (not master nodes)
- Replicas: **Start with 1, scale to 3 for production**

---

## 🌐 Understanding the Worker-Only Scaling

### 1 Worker Replica (Learning Phase)
- **Service accessible on**: 1 worker node (where pod runs)
- **URLs shown**: 1 URL
- **Use case**: Learning, testing, development

### 3 Worker Replicas (Production Phase)
- **Service accessible on**: 3 worker nodes (where pods run)
- **URLs shown**: 3 URLs
- **Use case**: Production, high availability, global access
- **Benefit**: Anyone can access from any of the 3 worker URLs
- **Architecture**: Keeps master nodes free for control plane operations

---

## 📁 Files in This Directory

### Configuration
- `nginx-nodeport-deployment.yaml` - Pod configuration (starts with 1 replica, worker-friendly)
- `nginx-nodeport-service.yaml` - NodePort service (dual-stack)
- `nginx-nodeport-configmaps.yaml` - HTML content + nginx config

### Scripts
- `deploy-and-test.sh` - ⭐ **Start here** (deploy 1 worker replica + test)
- `update-content-many.sh` - 🚀 **For scaling** (shows all worker replica URLs)
- `update-content-single.sh` - For single worker replica deployments

### Documentation
- `nginx-nodeport.md` - Complete technical guide

---

## ✅ Success Indicators

**1 Worker Replica (Working):**
- ✅ Service type: `NodePort`
- ✅ NodePort: `30091`
- ✅ IP families: `["IPv4","IPv6"]`
- ✅ Pod status: `Running`
- ✅ Node type: `Worker` (not Master)
- ✅ Test output: `✅ External Mycelium IPv6 connectivity is working!`
- ✅ Shows 1 accessible URL

**3 Worker Replicas (Production Ready):**
- ✅ All above indicators
- ✅ 3 pods running across 3 **worker nodes**
- ✅ Shows 3 accessible URLs
- ✅ All 3 worker URLs respond successfully
- ✅ Debug script confirms: `✅ HTTP connectivity: WORKING` for all

---

## 🚨 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)

---

## 🆘 Common Questions

**Q: Why start with 1 worker replica?**
A: It's easier to understand and debug. You can see exactly which worker node is serving the content.

**Q: Why only worker nodes?**
A: Production best practice - keep master nodes free for Kubernetes control plane operations.

**Q: Why scale to 3 worker replicas?**
A: This makes the service accessible from all 3 worker nodes, providing global availability and load distribution.

**Q: What does "externalTrafficPolicy: Local" do on workers?**
A: It ensures the service is only accessible on worker nodes where pods are running, preserving the source IP and improving performance.

**Q: How do I know if scaling worked?**
A: Use `update-content-many.sh` - it will show you all 3 accessible worker URLs.
---


## 🎉 Success!

Once you complete both steps, you'll have:
- ✅ **Learned** how NodePort scaling works on worker nodes
- ✅ **Deployed** a production-ready, multi-worker replica service
- ✅ **Understood** Mycelium IPv6 networking from workers
- ✅ **Tested** global accessibility from all worker nodes
- ✅ **Followed** production best practices (workers vs masters)

**You're now ready for production workloads on Mycelium Cloud!** 🚀