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