190 lines
3.9 KiB
Markdown
190 lines
3.9 KiB
Markdown
# Notes Application on Kubernetes
|
||
|
||
## 📌 Description
|
||
|
||
This project is a simple full-stack **Notes Application** deployed on Kubernetes.
|
||
It allows users to create and view notes through a web interface. The application demonstrates a complete **3-tier architecture**:
|
||
|
||
* Frontend (User Interface)
|
||
* Backend (API Server)
|
||
* Database (PostgreSQL)
|
||
|
||
The application is containerized using Docker and deployed using Kubernetes.
|
||
|
||
---
|
||
|
||
## 🧱 Application Architecture
|
||
|
||
The system consists of three main components:
|
||
|
||
### 1. Frontend
|
||
|
||
* Built using HTML and JavaScript
|
||
* Served via Nginx
|
||
* Provides UI for adding and viewing notes
|
||
* Communicates with backend using HTTP requests
|
||
|
||
### 2. Backend
|
||
|
||
* Built using FastAPI (Python)
|
||
* Provides REST API endpoints:
|
||
|
||
* `GET /notes`
|
||
* `POST /notes`
|
||
* Handles business logic and database interaction
|
||
|
||
### 3. Database
|
||
|
||
* PostgreSQL database
|
||
* Stores notes persistently
|
||
* Managed using Kubernetes StatefulSet
|
||
|
||
---
|
||
|
||
## 📦 Containers Used
|
||
|
||
| Container | Description |
|
||
| --------- | --------------------------------------------- |
|
||
| frontend | Nginx container serving static frontend files |
|
||
| backend | FastAPI application handling API requests |
|
||
| postgres | PostgreSQL database for storing notes |
|
||
|
||
---
|
||
|
||
## ☸️ Kubernetes Objects
|
||
|
||
| Object | Description |
|
||
| --------------------------- | -------------------------------------------- |
|
||
| Namespace | `notes-app` – isolates application resources |
|
||
| Deployment | Manages frontend and backend pods |
|
||
| StatefulSet | Manages PostgreSQL with persistent storage |
|
||
| Service | Enables communication between components |
|
||
| PersistentVolume (PV) | Provides storage for database |
|
||
| PersistentVolumeClaim (PVC) | Requests storage for PostgreSQL |
|
||
|
||
---
|
||
|
||
## 🌐 Networking
|
||
|
||
* Communication is handled using Kubernetes **Services**
|
||
* Backend is accessible via:
|
||
|
||
```
|
||
http://backend-service
|
||
```
|
||
* PostgreSQL is accessible via:
|
||
|
||
```
|
||
postgres
|
||
```
|
||
* Frontend is exposed externally using **NodePort**
|
||
|
||
---
|
||
|
||
## 💾 Storage
|
||
|
||
* PostgreSQL uses persistent storage via:
|
||
|
||
* PersistentVolume (PV)
|
||
* PersistentVolumeClaim (PVC)
|
||
* Ensures data is retained even if pods restart
|
||
|
||
---
|
||
|
||
## ⚙️ Container Configuration
|
||
|
||
### Backend Configuration
|
||
|
||
```text
|
||
DATABASE_URL=postgresql://user:password@postgres:5432/notesdb
|
||
```
|
||
|
||
### Frontend Configuration
|
||
|
||
```text
|
||
const API_URL = "http://backend-service";
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 How to Run the Application
|
||
|
||
### 1. Prepare the Application
|
||
|
||
```bash
|
||
./scripts/prepare-app.sh
|
||
```
|
||
|
||
Builds Docker images and prepares environment.
|
||
|
||
---
|
||
|
||
### 2. Start the Application
|
||
|
||
```bash
|
||
./scripts/start-app.sh
|
||
```
|
||
|
||
Deploys all Kubernetes resources.
|
||
|
||
---
|
||
|
||
### 3. Access the Application
|
||
|
||
#### Option 1: NodePort
|
||
|
||
```
|
||
http://localhost:30007
|
||
```
|
||
|
||
#### Option 2: Port Forward (recommended for Docker Desktop)
|
||
|
||
```bash
|
||
kubectl port-forward service/frontend-service 8080:80 -n notes-app
|
||
```
|
||
|
||
Then open:
|
||
|
||
```
|
||
http://localhost:8080
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Stop the Application
|
||
|
||
```bash
|
||
./scripts/stop-app.sh
|
||
```
|
||
|
||
Deletes all Kubernetes resources.
|
||
|
||
---
|
||
|
||
## 🧪 Functionality
|
||
|
||
* Users can add notes via UI
|
||
* Notes are stored in PostgreSQL
|
||
* Data persists across restarts
|
||
|
||
---
|
||
|
||
## 📝 Notes
|
||
|
||
* Docker images are hosted on Docker Hub
|
||
* Kubernetes cluster used: Docker Desktop Kubernetes
|
||
* Application demonstrates real-world container orchestration
|
||
|
||
---
|
||
|
||
## 📚 References
|
||
|
||
* OpenAI. (2026). ChatGPT (GPT-5.5). https://chat.openai.com
|
||
Used for guidance on Kubernetes deployment, debugging, and structuring the application.
|
||
|
||
---
|
||
|
||
## 👨💻 Author
|
||
|
||
Nihal Ahmed
|