End-to-End Deployment of a Heart Disease Risk Prediction API

Summary

This project demonstrates the complete end-to-end deployment of a machine learning microservice for heart disease risk prediction using a modern, cloud-native stack. A logistic regression model is wrapped in a high-performance FastAPI REST endpoint, containerized with Docker, and orchestrated locally using Kubernetes via Minikube. The resulting pipeline serves as a reproducible blueprint for deploying, managing, and scaling AI-driven healthcare APIs within a robust container orchestration environment.

Using FastAPI, Docker, and Kubernetes (Minikube)

View Project on GitHub

1. Overview

This project demonstrates the full lifecycle of a machine-learning microservice for healthcare, built and deployed using modern cloud-native tools — FastAPI, Docker, and Kubernetes — entirely locally on Windows 11.

The service predicts the probability of heart disease from patient data using a logistic regression model trained on the UCI Heart Disease dataset.

☸️ Note: It simulates a real-world production scenario where an AI model is containerized, orchestrated, and scaled automatically inside a Kubernetes cluster.

2. Project Objectives

Build a simple but clinically relevant ML model.
Wrap it in a FastAPI service exposing a REST API.
Containerize the service using Docker.
Deploy and manage it using Kubernetes (Minikube).
Test, document, and prepare it for portfolio and GitHub presentation.

## 3. Tools & Frameworks

Component	Purpose
Python 3.11	Core language
FastAPI + Uvicorn	REST API framework
scikit-learn + pandas + numpy + joblib	Model training and serialization
Docker	Containerization
Kubernetes + kubectl + Minikube	Container orchestration
Windows 11 + PowerShell	Development environment

4. Folder Structure

heart_disease_api/
│
├── app/
│   ├── main.py                ← FastAPI application
│   ├── model.pkl              ← Trained model (auto-generated)
│   └── columns.json           ← Feature metadata (auto-generated)
│
├── heart.csv                  ← Local dataset
├── train_model.py             ← Model training script
├── requirements.txt           ← Python dependencies
├── Dockerfile                 ← Docker build instructions
├── deployment.yaml            ← Kubernetes deployment descriptor
└── service.yaml               ← Kubernetes service descriptor

5. Model Training (`train_model.py`)

import os, json, joblib, pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler
from sklearn.pipeline import Pipeline

SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
CSV_PATH   = os.path.join(SCRIPT_DIR, "heart.csv")
APP_DIR    = os.path.join(SCRIPT_DIR, "app")
MODEL_PATH = os.path.join(APP_DIR, "model.pkl")
COLS_PATH  = os.path.join(APP_DIR, "columns.json")

FEATURE_COLUMNS = [
    "age","sex","cp","trestbps","chol","fbs","restecg",
    "thalach","exang","oldpeak","slope","ca","thal"
]
TARGET_COLUMN = "target"

def load_and_clean():
    df = pd.read_csv(CSV_PATH)
    df.columns = [c.strip().lower() for c in df.columns]
    for c in FEATURE_COLUMNS + [TARGET_COLUMN]:
        df[c] = pd.to_numeric(df[c], errors="coerce")
    df = df.dropna(subset=FEATURE_COLUMNS + [TARGET_COLUMN])
    return df

def main():
    os.makedirs(APP_DIR, exist_ok=True)
    for f in [MODEL_PATH, COLS_PATH]:
        if os.path.exists(f): os.remove(f)

    df = load_and_clean()
    X, y = df[FEATURE_COLUMNS], df[TARGET_COLUMN].astype(int)
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42, stratify=y
    )

    pipeline = Pipeline([
        ("scaler", StandardScaler()),
        ("model", LogisticRegression(max_iter=5000, solver="lbfgs"))
    ])
    pipeline.fit(X_train, y_train)

    joblib.dump(pipeline, MODEL_PATH)
    json.dump({"feature_columns": FEATURE_COLUMNS}, open(COLS_PATH, "w"), indent=2)

    print(f"✅ Model saved: {MODEL_PATH}")
    print(f"✅ Columns saved: {COLS_PATH}")

if __name__ == "__main__":
    main()

⚡ Note: Running this script trains a scaled logistic regression model and saves model.pkl and columns.json under app/.

6. FastAPI Service (`app/main.py`)

from fastapi import FastAPI
from pydantic import BaseModel
import joblib, json, os, numpy as np

APP_DIR = os.path.dirname(os.path.abspath(__file__))
MODEL_PATH = os.path.join(APP_DIR, "model.pkl")
COLS_PATH  = os.path.join(APP_DIR, "columns.json")

app = FastAPI(title="Heart Disease Risk API")

model = joblib.load(MODEL_PATH)
FEATURE_COLUMNS = json.load(open(COLS_PATH))["feature_columns"]

class PatientData(BaseModel):
    age:int; sex:int; cp:int; trestbps:int; chol:int; fbs:int
    restecg:int; thalach:int; exang:int; oldpeak:float
    slope:int; ca:int; thal:int

@app.post("/predict")
def predict(data: PatientData):
    payload = data.dict()
    X = np.array([[payload[c] for c in FEATURE_COLUMNS]], dtype=float)
    prob = float(model.predict_proba(X)[0,1])
    risk = "High" if prob>0.6 else "Moderate" if prob>0.3 else "Low"
    return {"risk_probability": round(prob,2), "risk_category": risk}

Test locally with:

python -m uvicorn app.main:app --reload

and browse to http://127.0.0.1:8000/docs.

7. Python Requirements (`requirements.txt`)

fastapi
uvicorn
scikit-learn
pandas
numpy
joblib

8. Docker Containerization

Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY ./app /app
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r /app/requirements.txt
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build & Run Locally

docker build -t heart-api .
docker run -p 8000:8000 heart-api

Access at http://localhost:8000/docs.

9. Kubernetes Deployment (Minikube)

Start cluster:

minikube start --driver=docker

Load image:

minikube image load heart-api:latest

`deployment.yaml`

apiVersion: apps/v1
kind: Deployment
metadata:
  name: heart-api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: heart-api
  template:
    metadata:
      labels:
        app: heart-api
    spec:
      containers:
        - name: heart-api
          image: heart-api:latest
          imagePullPolicy: Never
          ports:
            - containerPort: 8000

`service.yaml`

apiVersion: v1
kind: Service
metadata:
  name: heart-api-service
spec:
  selector:
    app: heart-api
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
  type: NodePort

Apply:

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

Check:

kubectl get pods
kubectl get svc

Access the API:

minikube service heart-api-service

🌐 Note: Your browser opens to something like http://127.0.0.1:31535/docs.

10. Validation

Send a JSON POST:

{
  "age": 52, "sex": 1, "cp": 0, "trestbps": 125, "chol": 212,
  "fbs": 0, "restecg": 1, "thalach": 168, "exang": 0,
  "oldpeak": 1.0, "slope": 2, "ca": 2, "thal": 3
}

Response:

{"risk_probability": 0.67, "risk_category": "High"}

11. Verification & Monitoring

View logs:

kubectl logs -l app=heart-api

Open dashboard:

minikube dashboard

12. Clean-Up

minikube stop
kubectl delete -f deployment.yaml
kubectl delete -f service.yaml

13. Key Outcomes

✅ Achievements:

Fully operational healthcare microservice for heart disease risk prediction.

Containerized and orchestrated ML workflow on local Kubernetes cluster.

Reusable pattern for any other AI/ML healthcare API.

No cloud cost — completely free on local hardware.

Using FastAPI, Docker, and Kubernetes (Minikube)

End-to-End Deployment of a Heart Disease Risk Prediction API

1. Overview

2. Project Objectives

4. Folder Structure

View Source Code

5. Model Training (`train_model.py`)

View Source Code

6. FastAPI Service (`app/main.py`)

View Source Code

View Source Code

7. Python Requirements (`requirements.txt`)

View Source Code

8. Docker Containerization

Dockerfile

View Source Code

Build & Run Locally

View Source Code

9. Kubernetes Deployment (Minikube)

View Source Code

View Source Code

`deployment.yaml`

View Source Code

`service.yaml`

View Source Code

Apply:

View Source Code

View Source Code

Access the API:

View Source Code

10. Validation

View Source Code

View Source Code

11. Verification & Monitoring

View Source Code

View Source Code

12. Clean-Up

View Source Code

13. Key Outcomes

Using FastAPI, Docker, and Kubernetes (Minikube)

End-to-End Deployment of a Heart Disease Risk Prediction API

1. Overview

2. Project Objectives

4. Folder Structure

View Source Code

5. Model Training (train_model.py)

View Source Code

6. FastAPI Service (app/main.py)

View Source Code

View Source Code

7. Python Requirements (requirements.txt)

View Source Code

8. Docker Containerization

Dockerfile

View Source Code

Build & Run Locally

View Source Code

9. Kubernetes Deployment (Minikube)

View Source Code

View Source Code

deployment.yaml

View Source Code

service.yaml

View Source Code

Apply:

View Source Code

View Source Code

Access the API:

View Source Code

10. Validation

View Source Code

View Source Code

11. Verification & Monitoring

View Source Code

View Source Code

12. Clean-Up

View Source Code

13. Key Outcomes

5. Model Training (`train_model.py`)

6. FastAPI Service (`app/main.py`)

7. Python Requirements (`requirements.txt`)

`deployment.yaml`

`service.yaml`