tfgrid/myceliumcloud-examples
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
77e054cdea67665338a40cc24d1cd04c8ecb6570
myceliumcloud-examples/examples/nginx-nodeport/nginx-nodeport.md

7.2 KiB
Raw Blame History

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)

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!)

# 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

./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

# 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

./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:

# 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! 🚀