139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# Flask + PostgreSQL Kubernetes WebApp
|
||
|
||
A lightweight full-stack web application powered by **Flask** and **PostgreSQL**, containerized with **Docker**, and deployed on **Kubernetes (Minikube)** using custom `Namespace`, `Deployment`, `StatefulSet`, and `Services`. Designed to demonstrate a production-like cloud-native architecture.
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```bash
|
||
z2/
|
||
├── app/
|
||
│ ├── main.py # Flask application logic
|
||
│ └── requirements.txt # Python dependencies
|
||
├── k8s/
|
||
│ ├── namespace.yaml # Custom namespace
|
||
│ ├── deployment.yaml # Flask app deployment
|
||
│ ├── postgres-deployment.yaml # PostgreSQL StatefulSet + PVC + Service
|
||
│ ├── migrate-job.yaml # Migration job (optional)
|
||
│ ├── service.yaml # Flask NodePort Service
|
||
├── Dockerfile # For building Flask app image
|
||
├── prepare-app.sh # Script: Build & tag Docker image
|
||
├── start-app.sh # Script: Apply all Kubernetes configs
|
||
├── stop-app.sh # Script: Delete all resources
|
||
└── README.md # Project documentation
|
||
```
|
||
|
||
---
|
||
|
||
## How It Works
|
||
|
||
1. **Prepare the Environment**
|
||
```bash
|
||
./prepare-app.sh
|
||
```
|
||
- Builds and tags Docker image locally
|
||
- Prepares persistent volume (PVC) for PostgreSQL
|
||
|
||
2. **Deploy the Application**
|
||
```bash
|
||
./start-app.sh
|
||
```
|
||
- Creates namespace, StatefulSet, Deployments, Services
|
||
|
||
3. **Access the Web App**
|
||
```bash
|
||
minikube service flask-service -n webapp-namespace
|
||
```
|
||
- Opens the app in your browser (NodePort)
|
||
|
||
4. **Stop and Clean Everything**
|
||
```bash
|
||
./stop-app.sh
|
||
```
|
||
- Deletes all created Kubernetes resources
|
||
|
||
---
|
||
|
||
## Technologies Used
|
||
|
||
| Tool | Purpose |
|
||
|----------------|------------------------------|
|
||
| Flask | Web framework (Python) |
|
||
| PostgreSQL | Relational database |
|
||
| Docker | Containerization |
|
||
| Kubernetes | Container orchestration |
|
||
| Minikube | Local Kubernetes environment |
|
||
|
||
---
|
||
|
||
## Health Checks
|
||
|
||
To ensure resilience and uptime, Kubernetes probes can be added:
|
||
|
||
```yaml
|
||
livenessProbe:
|
||
httpGet:
|
||
path: /health
|
||
port: 8000
|
||
initialDelaySeconds: 5
|
||
periodSeconds: 10
|
||
|
||
readinessProbe:
|
||
httpGet:
|
||
path: /health
|
||
port: 8000
|
||
initialDelaySeconds: 5
|
||
periodSeconds: 10
|
||
```
|
||
|
||
Add a `/health` route to your `main.py`:
|
||
```python
|
||
@app.route('/health')
|
||
def health():
|
||
return "OK", 200
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Problem | Solution |
|
||
|-------------------------------------|--------------------------------------------------------------------------|
|
||
| ❌ `ImagePullBackOff` or `ErrImagePull` | Make sure image is built locally with `docker build -t flask-app .` and you're using `imagePullPolicy: Never` |
|
||
| ❌ App not accessible | Check service type is `NodePort`, port 30080 is exposed, and run `minikube service flask-service -n webapp-namespace` |
|
||
| ❌ Database errors | Ensure PostgreSQL pod is running (`kubectl get pods -n webapp-namespace`), check PVC and env vars |
|
||
| ❌ "command not found: kubectl" | Install `kubectl` and make sure it’s configured with `minikube` context |
|
||
| ❌ Connection refused errors | Check that `POSTGRES_HOST` matches the service name (`postgres`) and app waits until DB is ready |
|
||
|
||
---
|
||
|
||
## Future Enhancements
|
||
|
||
- Use Helm for templated deployments
|
||
- Add database migrations (Alembic / Flask-Migrate)
|
||
- CI/CD integration with GitLab or GitHub Actions
|
||
- Add Redis or caching layer
|
||
- Auto-scaling and HorizontalPodAutoscaler
|
||
|
||
|
||
|
||
## Author
|
||
|
||
**Hafzal Ahamed Hasan Mohamed**
|
||
TUKE, Faculty of Electrical Engineering and Informatics
|
||
Git: [git.kemt.fei.tuke.sk/hh304ug/zkt25](https://git.kemt.fei.tuke.sk/hh304ug/zkt25)
|
||
|
||
|
||
hafzal03@LAPTOP-ELUS3HGM:~/mypro/z2$ kubectl get pods -n webapp-namespace
|
||
NAME READY STATUS RESTARTS AGE
|
||
flask-app-6b844bf6-cq9t6 1/1 Running 0 8m37s
|
||
postgres-644fc4c86d-l9h4f 1/1 Running 0 14m
|
||
hafzal03@LAPTOP-ELUS3HGM:~/mypro/z2$ minikube service flask-service -n webapp-namespace
|
||
|
||
minikube service flask-service -n webapp-namespace
|
||
|
||
kubectl get pods -n webapp-namespace
|
||
|
||
kubectl rollout restart deployment flask-app -n webapp-namespace
|