Files

mik-tf 1a902b3178 feat: Add complete Python Flask API example with deployment, service, and comprehensive documentation

2025-11-04 12:37:12 -05:00

14 KiB

Raw Blame History

Mycelium Cloud - Python Flask API Example

A complete, production-ready Python Flask API for deploying dynamic web services on Mycelium Cloud Kubernetes cluster.

📁 What This Contains

This directory contains everything you need to deploy a practical Flask API:

python-flask.md - This comprehensive guide
python-flask-deployment.yaml - Flask application deployment
python-flask-service.yaml - Service configuration
app.py - The Flask application source code

🚀 Quick Start (2 minutes)

# 1. Deploy the application
kubectl apply -f python-flask-deployment.yaml

# 2. Create ConfigMap with the Flask app
kubectl create configmap python-flask-app --from-file=app.py

# 3. Create the service
kubectl apply -f python-flask-service.yaml

# 4. Access your API via port-forward

**Option 1: Simple (Recommended)**
```bash
# Keep terminal open, see connection logs (Ctrl+C to stop)
kubectl port-forward service/python-flask-service 5000:5000

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/python-flask-service 5000:5000 > /dev/null 2>&1 &

# Kill when done
lsof -ti:5000 | xargs kill -9

5. Test the API

curl http://localhost:5000 curl http://localhost:5000/time curl http://localhost:5000/health curl http://localhost:5000/random curl "http://localhost:5000/calc?operation=add&a=5&b=3"


**Expected Result:** You'll see a complete API with multiple useful endpoints.

## 📋 What You'll Learn

- ✅ Flask web framework deployment
- ✅ Python application containerization
- ✅ API development and JSON responses
- ✅ RESTful endpoints with parameters
- ✅ Error handling and status codes
- ✅ Container management with ConfigMaps
- ✅ Service creation and networking
- ✅ Port-forwarding for external access (Mycelium Cloud method)
- ✅ Advanced Flask patterns and best practices

## 🏗️ Architecture

This example demonstrates:

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ User │ │ Port-Forward │ │ Flask API │ │ Python │ │ (cURL/HTTP) │────│ localhost:5000 │────│ Service │────│ Container │ │ │ │ │ │ :5000 │ │ (Python 3.11) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ┌───────────────┐ │ ConfigMap │ │ (app.py) │ └───────────────┘


**Components:**
- **Flask Pod**: Python web application serving multiple endpoints
- **ConfigMap**: Stores the Flask application code (app.py)
- **Service**: LoadBalancer exposing the Flask API
- **Port-Forward**: Mycelium Cloud method for external access
- **Endpoints**: 6 useful API endpoints for testing and development

## 🔥 API Endpoints

### 1. Root Information
```bash
GET /

Response:

{
  "api": "Python Flask Tools API",
  "version": "1.0.0",
  "description": "A practical API with useful endpoints for testing and development",
  "endpoints": {
    "/": "API information",
    "/time": "Current timestamp",
    "/random": "Random data and quotes",
    "/health": "Health check",
    "/calc": "Mathematical calculations",
    "/info": "System information"
  },
  "examples": {
    "time": "/time",
    "random": "/random",
    "calc": "/calc?operation=add&a=5&b=3",
    "health": "/health"
  }
}

2. Current Time

GET /time

Response:

{
  "current_time": "2025-11-04T17:31:40.387484",
  "date": "2025-11-04 17:31:40",
  "timestamp": 1762277500.387502,
  "timezone": "UTC"
}

3. Random Data

GET /random

Response:

{
  "boolean": false,
  "color": "#FF6B6B",
  "list_item": "banana",
  "number": 91,
  "quote": "The way to get started is to quit talking and begin doing. - Walt Disney",
  "uuid": "8351-328"
}

4. Health Check

GET /health

Response:

{
  "service": "Python Flask Tools API",
  "status": "healthy",
  "timestamp": "2025-11-04T17:31:48.464063",
  "uptime": "running"
}

5. Mathematical Calculations

GET /calc?operation=add&a=5&b=3

Operations supported: add, subtract, multiply, divide, power, sqrt, modulo

Response:

{
  "operation": "add",
  "a": 5,
  "b": 3,
  "result": 8,
  "calculation": "5 add 3 = 8"
}

6. System Information

GET /info

Response:

{
  "python_version": "3.11.14",
  "platform": "Linux-6.1.21-x86_64-with-musl",
  "processor": "",
  "hostname": "python-flask-55fdbf5cb4-cnxrc",
  "machine": "x86_64",
  "current_directory": "/",
  "environment": {
    "HOSTNAME": "python-flask-55fdbf5cb4-cnxrc",
    "POD_NAME": "N/A"
  }
}

📊 Resource Details

# Expected output
kubectl get pods
NAME                            READY   STATUS    RESTARTS   AGE
python-flask-xxxxxx-xxxxx       1/1     Running   0          2m

kubectl get svc
NAME                  TYPE           CLUSTER-IP      EXTERNAL-IP              PORT(S)
python-flask-service  LoadBalancer   10.43.xx.x      10.20.x.x,10.20.x.x      5000:xxxxx/TCP

kubectl get configmap
NAME                DATA   AGE
python-flask-app    1      1m

🛠️ API Testing Examples

Test All Endpoints

# Test root endpoint
curl http://localhost:5000

# Test time endpoint
curl http://localhost:5000/time

# Test random data
curl http://localhost:5000/random

# Test health check
curl http://localhost:5000/health

# Test calculations
curl "http://localhost:5000/calc?operation=add&a=10&b=5"
curl "http://localhost:5000/calc?operation=multiply&a=7&b=8"
curl "http://localhost:5000/calc?operation=divide&a=20&b=4"
curl "http://localhost:5000/calc?operation=power&a=2&b=3"

# Test system info
curl http://localhost:5000/info

Advanced Testing

# Test with JSON response formatting
curl -s http://localhost:5000 | jq '.'
curl -s http://localhost:5000/time | jq '.current_time'

# Test error handling
curl "http://localhost:5000/calc?operation=unknown&a=5&b=3"
curl "http://localhost:5000/calc?operation=add&a=invalid&b=3"

# Test multiple random calls
for i in {1..5}; do
  curl -s http://localhost:5000/random | jq -r '.quote'
done

🔧 Customization Guide

Add New Endpoints

Edit app.py to add custom endpoints:

@app.route('/custom')
def custom_endpoint():
    return jsonify({
        'message': 'This is a custom endpoint',
        'data': {'key': 'value'},
        'timestamp': datetime.datetime.now().isoformat()
    })

Modify Existing Endpoints

@app.route('/random')
def get_random():
    # Add your own quotes or data
    quotes = [
        'Your custom quote here',
        'Another custom quote'
    ]
    # ... rest of the function

Update Container Image

To use a different Python version or add packages:

# In python-flask-deployment.yaml
- name: python-flask
  image: python:3.12-alpine  # Use different version

# In python-flask-deployment.yaml
args:
- |
  pip install flask requests &&  # Add more packages
  python /app/app.py

Environment Variables

Add environment-specific configuration:

# In python-flask-deployment.yaml
env:
- name: FLASK_ENV
  value: "production"
- name: DEBUG
  value: "False"

🚪 Access Methods

Method 1: Port-Forward (Recommended for Mycelium Cloud)

Option 1: Simple (Recommended)

# Keep terminal open, see connection logs (Ctrl+C to stop)
kubectl port-forward service/python-flask-service 5000:5000

# Access via browser or curl
curl http://localhost:5000

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/python-flask-service 5000:5000 > /dev/null 2>&1 &

# Access via browser or curl
curl http://localhost:5000

Why this works in Mycelium Cloud:

LoadBalancer external IPs are internal cluster addresses
Port-forward creates local tunnel to cluster service
Reliable and consistent access method

Method 2: LoadBalancer (For Reference)

Note: In Mycelium Cloud, LoadBalancer external IPs (like 10.20.x.x) are internal cluster IPs and not externally accessible. Use port-forward for external access.

Method 3: Direct API Testing

Create a test script:

import requests
import json

# Test all endpoints
base_url = "http://localhost:5000"

endpoints = ['/', '/time', '/random', '/health', '/calc?operation=add&a=5&b=3', '/info']

for endpoint in endpoints:
    response = requests.get(f"{base_url}{endpoint}")
    print(f"GET {endpoint}")
    print(json.dumps(response.json(), indent=2))
    print("-" * 50)

🗑️ Resource Cleanup

# Remove all resources
kubectl delete -f python-flask-deployment.yaml -f python-flask-service.yaml

# Remove the ConfigMap
kubectl delete configmap python-flask-app

# Verify cleanup
kubectl get all -l app=python-flask  # Should return nothing

🔍 Troubleshooting

Pod Won't Start

# Check pod status
kubectl get pods -l app=python-flask

# Check pod logs
kubectl logs deployment/python-flask

# Check pod events
kubectl describe pod -l app=python-flask

# Common issues:
# - ConfigMap not found
# - Python package installation failed
# - Port binding errors

API Not Responding

# Check service endpoints
kubectl get endpoints python-flask-service

# Check if port-forward is working
kubectl port-forward service/python-flask-service 5001:5000 &
curl -v http://localhost:5001

# Test from within cluster
kubectl run test-flask --rm -it --image=curlimages/curl:8.7.1 -- \
  sh -lc 'curl http://python-flask-service:5000'

ConfigMap Issues

# Verify ConfigMap exists
kubectl get configmap python-flask-app

# Check ConfigMap content
kubectl get configmap python-flask-app -o yaml

# Recreate ConfigMap
kubectl delete configmap python-flask-app
kubectl create configmap python-flask-app --from-file=app.py

Flask App Errors

# Check Flask app logs
kubectl logs deployment/python-flask

# Test Flask app locally
python app.py  # Test locally first

# Check for syntax errors
python -m py_compile app.py

Port Forward Fails

# Check if port is in use
lsof -i :5000

# Try different port
kubectl port-forward service/python-flask-service 5002:5000
curl http://localhost:5002

📚 More Examples

This is currently one of the complete examples. Future examples will include:

python-flask/ - This example (COMPLETED)
redis-cache/ - In-memory data caching
postgresql/ - Persistent database services
wordpress/ - Multi-container CMS deployment
nodejs-api/ - Modern JavaScript applications
jenkins-cicd/ - Infrastructure automation
nextcloud/ - Enterprise file sharing

💡 Pro Tips

Start Simple: Begin with foreground port-forward (kubectl port-forward)
Background Optional: Use nohup only when you need persistent access
Port Management: Use lsof -ti:PORT to find and kill processes
Resource Monitoring: kubectl get pods -o wide shows pod distribution
Quick Testing: Use curl for all API testing
Flask Logs: kubectl logs deployment/python-flask for debugging
Config Updates: Update ConfigMap then restart deployment: kubectl rollout restart deployment/python-flask
API Documentation: The root endpoint (/) provides complete API documentation
Error Handling: Test error cases like invalid operations or missing parameters
Environment Testing: Test in both development and production modes

🎉 Success Indicators

You'll know everything is working when:

✅ kubectl get pods shows python-flask pod in "Running" status
✅ kubectl get svc shows python-flask-service created
✅ curl http://localhost:5000 returns API information
✅ All endpoints (/time, /random, /health, /calc, /info) return proper JSON
✅ kubectl logs deployment/python-flask shows Flask starting without errors
✅ ConfigMap python-flask-app exists and contains app.py

🏆 Next Steps

After completing this example, you can:

Customize Endpoints: Add your own API endpoints
Database Integration: Connect to persistent databases
Add More Examples: Try the Redis cache example
Scale Up: Learn about load balancing with multiple replicas
Advanced Patterns: Learn about secrets, config maps, and persistent volumes

🚀 API Testing Tools

Postman/Insomnia

Import the API into API testing tools:

http://localhost:5000/
http://localhost:5000/time
http://localhost:5000/random
http://localhost:5000/health
http://localhost:5000/calc?operation=add&a=5&b=3
http://localhost:5000/info

Command Line Tools

# Install jq for JSON formatting
curl http://localhost:5000 | jq '.'

# Create an API test script
cat > test-api.sh << 'EOF'
#!/bin/bash
echo "Testing Python Flask API..."
curl -s http://localhost:5000 | jq '.api'
curl -s http://localhost:5000/time | jq '.current_time'
curl -s http://localhost:5000/random | jq '.quote'
echo "All tests completed!"
EOF
chmod +x test-api.sh
./test-api.sh

📞 Getting Help

Troubleshooting: Check the troubleshooting section above
Mycelium Cloud Docs: See main repository README
Flask Documentation: https://flask.palletsprojects.com/
Kubectl Help: kubectl get pods --help for command reference
API Testing: Use Postman, Insomnia, or curl for testing
Support: Contact Mycelium Cloud support team

For more help, visit our documentation or contact support.

14 KiB Raw Blame History

Mycelium Cloud - Python Flask API Example

📁 What This Contains

🚀 Quick Start (2 minutes)

5. Test the API

2. Current Time

3. Random Data

4. Health Check

5. Mathematical Calculations

6. System Information

📊 Resource Details

🛠️ API Testing Examples

Test All Endpoints

Advanced Testing

🔧 Customization Guide

Add New Endpoints

Modify Existing Endpoints

Update Container Image

Environment Variables

🚪 Access Methods

Method 1: Port-Forward (Recommended for Mycelium Cloud)

Method 2: LoadBalancer (For Reference)

Method 3: Direct API Testing

🗑️ Resource Cleanup

🔍 Troubleshooting

Pod Won't Start

API Not Responding

ConfigMap Issues

Flask App Errors

Port Forward Fails

📚 More Examples

💡 Pro Tips

🎉 Success Indicators

🏆 Next Steps

🚀 API Testing Tools

Postman/Insomnia

Command Line Tools

📞 Getting Help

14 KiB

Raw Blame History