feat: Add complete Python Flask API example with deployment, service, and comprehensive documentation
This commit is contained in:
mik-tf
533
examples/python-flask/python-flask.md
Normal file
533
examples/python-flask/python-flask.md
Normal file
@@ -0,0 +1,533 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user