154 lines
5.1 KiB
Markdown
154 lines
5.1 KiB
Markdown
# TaskFlow — Kubernetes Assignment (Z2)
|
|
|
|
> A task management web application deployed on Kubernetes.
|
|
|
|
---
|
|
|
|
## 1. What the Application Does
|
|
|
|
TaskFlow is a simple web-based task manager. Users can:
|
|
|
|
- **Create** tasks with a title, description, and status
|
|
- **Advance** tasks through stages: `Todo → In Progress → Done`
|
|
- **Delete** tasks they no longer need
|
|
|
|
All data is stored in PostgreSQL and persists across pod restarts.
|
|
|
|
---
|
|
|
|
## 2. Containers Used
|
|
|
|
| Container | Image | Description |
|
|
|---|---|---|
|
|
| `taskflow-web` | `taskflow-web:latest` | Python 3.11 / Flask app served by Gunicorn on port 5000. Provides the HTML UI and REST API. |
|
|
| `postgres` | `postgres:15-alpine` | PostgreSQL 15 database. Stores all tasks in the `taskdb` database. |
|
|
| `wait-for-db` (init) | `busybox:1.36` | Init container that waits until PostgreSQL is ready before the web app starts. |
|
|
|
|
---
|
|
|
|
## 3. Kubernetes Objects
|
|
|
|
| Object | Kind | Description |
|
|
|---|---|---|
|
|
| `taskflow` | Namespace | Isolates all TaskFlow resources from other apps on the cluster. |
|
|
| `postgres-pv` | PersistentVolume | 1 GiB hostPath volume — real folder on the node's disk. |
|
|
| `postgres-pvc` | PersistentVolumeClaim | Requests the PV above. Referenced by the StatefulSet. |
|
|
| `postgres` | StatefulSet | Manages the PostgreSQL pod with stable name (`postgres-0`) and persistent storage. |
|
|
| `taskflow-web` | Deployment | Runs 2 replicas of the Flask web app with liveness and readiness probes. |
|
|
| `taskflow-web-service` | Service (NodePort) | Exposes the website on port `30080`. Entry point for the browser. |
|
|
| `postgres-service` | Service (ClusterIP) | Internal DNS name for PostgreSQL. Not reachable from outside the cluster. |
|
|
| `postgres-secret` | Secret | Stores the database username and password as base64-encoded values. |
|
|
| `postgres-init` | ConfigMap | Contains the SQL init script that creates the `tasks` table on first run. |
|
|
|
|
---
|
|
|
|
## 4. How Storage Works
|
|
|
|
Three objects work together:
|
|
|
|
**PersistentVolume (PV)**
|
|
A real directory `/mnt/data/taskflow-postgres` on the node's filesystem. Cluster-scoped, 1 GiB, `Retain` policy — data stays on disk even if the app is deleted.
|
|
|
|
**PersistentVolumeClaim (PVC)**
|
|
A request for that storage. Kubernetes matches it to the PV via `storageClassName: manual`.
|
|
|
|
**StatefulSet Volume Mount**
|
|
The PostgreSQL container mounts the PVC at `/var/lib/postgresql/data`. Every write goes:
|
|
|
|
```
|
|
PostgreSQL container
|
|
→ /var/lib/postgresql/data
|
|
→ postgres-pvc
|
|
→ postgres-pv
|
|
→ /mnt/data/taskflow-postgres (real folder on disk)
|
|
```
|
|
|
|
Data survives pod restarts, crashes, and redeployments because it lives on disk.
|
|
|
|
---
|
|
|
|
## 5. Virtual Networks
|
|
|
|
| Service | Type | Purpose |
|
|
|---|---|---|
|
|
| `taskflow-web-service` | NodePort `:30080` | Exposes the website to external browsers. |
|
|
| `postgres-service` | ClusterIP `:5432` | Internal DNS for PostgreSQL. Only pods inside the cluster can reach it. |
|
|
|
|
The web pods connect to PostgreSQL using the DNS name `postgres-service:5432` — Kubernetes resolves this automatically. No IP address is needed.
|
|
|
|
---
|
|
|
|
## 6. How to Run the Application
|
|
|
|
### Prepare (run once)
|
|
```bash
|
|
chmod +x setup.sh
|
|
./setup.sh
|
|
```
|
|
Writes all files, builds the Docker image, creates the PV directory, and deploys every Kubernetes object in order.
|
|
|
|
### Start
|
|
```bash
|
|
./start-app.sh
|
|
```
|
|
|
|
### Stop / Delete
|
|
```bash
|
|
./stop-app.sh
|
|
```
|
|
|
|
### View in Browser
|
|
```bash
|
|
minikube service taskflow-web-service -n taskflow
|
|
# or manually:
|
|
echo "http://$(minikube ip):30080"
|
|
```
|
|
|
|
### Useful Commands
|
|
```bash
|
|
# Check running pods
|
|
kubectl get pods -n taskflow
|
|
|
|
# View web app logs
|
|
kubectl logs -f deployment/taskflow-web -n taskflow
|
|
|
|
# View database logs
|
|
kubectl logs -f statefulset/postgres -n taskflow
|
|
|
|
# Open a psql shell
|
|
kubectl exec -it postgres-0 -n taskflow -- psql -U taskuser -d taskdb
|
|
```
|
|
|
|
---
|
|
|
|
## 7. File Structure
|
|
|
|
```
|
|
z2/
|
|
├── app/
|
|
│ ├── app.py # Flask web application
|
|
│ ├── Dockerfile # Container image definition
|
|
│ └── requirements.txt # Python dependencies
|
|
├── db/
|
|
│ └── init.sql # Reference SQL init script
|
|
├── namespace.yaml # Namespace: taskflow
|
|
├── deployment.yaml # Deployment: taskflow-web (2 replicas)
|
|
├── statefulset.yaml # PV + PVC + StatefulSet: postgres
|
|
├── service.yaml # NodePort (web) + ClusterIP (postgres)
|
|
├── secret.yaml # Database credentials
|
|
├── configmap.yaml # SQL init script
|
|
├── setup.sh # All-in-one setup script
|
|
├── start-app.sh # Deploy all objects
|
|
├── stop-app.sh # Remove all objects
|
|
├── prepare-app.sh # Build image + create PV directory
|
|
└── README.md # This file
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Declaration of AI Usage
|
|
|
|
AI tools (Claude by Anthropic) were used to assist with generating boilerplate code, Kubernetes YAML manifests, and shell scripts. All generated content was reviewed, tested, and understood by the student. The application structure, use case, and deployment decisions were directed by the student. AI was used as a productivity tool, not as a replacement for understanding.
|
|
|
|
|