myceliumcloud-examples/examples/python-flask/python-flask.md

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

```bash
# 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)**
```bash
# 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:**
```json
{
  "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
```bash
GET /time
```
**Response:**
```json
{
  "current_time": "2025-11-04T17:31:40.387484",
  "date": "2025-11-04 17:31:40",
  "timestamp": 1762277500.387502,
  "timezone": "UTC"
}
```

### 3. Random Data
```bash
GET /random
```
**Response:**
```json
{
  "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
```bash
GET /health
```
**Response:**
```json
{
  "service": "Python Flask Tools API",
  "status": "healthy",
  "timestamp": "2025-11-04T17:31:48.464063",
  "uptime": "running"
}
```

### 5. Mathematical Calculations
```bash
GET /calc?operation=add&a=5&b=3
```
**Operations supported:** `add`, `subtract`, `multiply`, `divide`, `power`, `sqrt`, `modulo`

**Response:**
```json
{
  "operation": "add",
  "a": 5,
  "b": 3,
  "result": 8,
  "calculation": "5 add 3 = 8"
}
```

### 6. System Information
```bash
GET /info
```
**Response:**
```json
{
  "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

```bash
# 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
```bash
# 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
```bash
# 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:

```python
@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

```python
@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:

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

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

### Environment Variables

Add environment-specific configuration:

```yaml
# 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)**
```bash
# 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)**
```bash
# 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:

```python
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

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

1. **Start Simple**: Begin with foreground port-forward (`kubectl port-forward`)
2. **Background Optional**: Use `nohup` only when you need persistent access
3. **Port Management**: Use `lsof -ti:PORT` to find and kill processes
4. **Resource Monitoring**: `kubectl get pods -o wide` shows pod distribution
5. **Quick Testing**: Use `curl` for all API testing
6. **Flask Logs**: `kubectl logs deployment/python-flask` for debugging
7. **Config Updates**: Update ConfigMap then restart deployment: `kubectl rollout restart deployment/python-flask`
8. **API Documentation**: The root endpoint (`/`) provides complete API documentation
9. **Error Handling**: Test error cases like invalid operations or missing parameters
10. **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:
1. **Customize Endpoints**: Add your own API endpoints
2. **Database Integration**: Connect to persistent databases
3. **Add More Examples**: Try the Redis cache example
4. **Scale Up**: Learn about load balancing with multiple replicas
5. **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
```bash
# 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](../../README.md) or contact support.