zkt25/z2

📘 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

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

   ./prepare-app.sh
   

   • Builds and tags Docker image locally
   • Prepares persistent volume (PVC) for PostgreSQL

2. Deploy the Application

   ./start-app.sh
   

   • Creates namespace, StatefulSet, Deployments, Services

3. Access the Web App

   minikube service flask-service -n webapp-namespace
   

   • Opens the app in your browser (NodePort)

4. Stop and Clean Everything

   ./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

---

<EFBFBD>ힺ Health Checks

To ensure resilience and uptime, Kubernetes probes can be added:

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:

@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

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