MONA is a K8s-based monitoring and analytics tool managed with Terraform and Helm. It collects and analyzes system metrics, built on Python with Celery and Redis as a task broker for metrics collection and ML workloads. FastAPI serves as the REST API/backend, React + Tailwind v4 + TypeScript handles web UI frontend, and PostgreSQL stores all metrics data.
- Ensure Docker Desktop, kind, helm and Terraform are installed.
- Set up node-exporter on the device you want to monitor with port 9100.
- Clone repo
git clone https://github.com/gwill1337/MONA.git - Configure the necessary values in "mona-chart/values"ConfigurationGuide. such as PC's IP & name or just add them via Admin panel
- Configure
config.pyfor ML and FastAPI limiter settings. - Create
terraform.tfvarsin terraform folder fromterraform.tfvars.example. - Deploy: Run the automated script:
.\deploy.ps1 -all # or .\deploy.ps1 -deployOr via makefile:
make allFor manual deployment, use terraform init && terraform apply inside the /terraform folder.
Links below are available after setup.
- Admin panel:
localhost:30081/adminDefault username: admin, password: admin123 - Dashboards:
localhost:30081/admin/dashboard - Grafana:
localhost:30300/Default username: admin, password: admin123 - Prometheus(Cluster):
localhost:30091/ - Prometheus(Monitoring devices):
localhost:30391/
Click to view detailed API endpoints
P.S. All endpoint require authentification except prometheus and probes.
- Swagger:
localhost:30080/docs - Main-metrics[Get]:
localhost:30080/db-metrics - Prometheus targets[Get]:
localhost:30080/api/prometheus/targets - Anomalies[Get]:
localhost:30080/anomalies - Model-info[Get]:
localhost:30080/model-info - Devices[Get]:
localhost:30080/devices - Devices[Post]:
localhost:30080/devicesavailable via curl - Devices[Delete]:
localhost:30080/devices/{device_id}available via curl - Train[Post]:
localhost:30080/trainavailable via curl - Model[Delete]:
localhost:30080/modelavailable via curl - Dashboard[Get]:
localhost:30080/api/dashboard
- Liveness[Get]:
localhost:30080/health/live - Readiness[Get]:
localhost:30080/health/ready
- Login[Post]:
localhost:30080/api/auth/login - Logout[Post]:
localhost:30080/api/auth/logout - Check auth[Get]:
localhost:30080/api/auth/me
The infrastructure is managed using Terraform and Helm. The Kubernetes cluster consists of a control-plane node running the following core workloads.
Helm templates for flexible and fast setup can be configured in values.
- API Engine: FastAPI endpoints for handling client requests.
- Task Queue: Celery workers with a Redis broker for background metrics collection and ML tasks.
- PostgreSQL: For storing metrics and analytics data.
- Redis: As broker for celery and as storage for sessions and limiter.
- Monitoring Stack: Prometheus for data scraping, Grafana for visualization (Recharts is also used in the web UI), Alertmanager for pod alert notifications, and Loki with Promtail for pod logs.
- ML: Mona uses Scikit-learn for anomaly detection.
- Training: The model uses Isolation Forest and builds features with deltas for more accurate anomaly detection.
- Auto: Takes between 50 and 500 of the most recent data points and trains the model on the fly. The model is not stored in the database and retrains before each detection (every 60 seconds by default).
- Manual: Uses a time range specified by the user. The trained model is stored in the database.
Postgres runs as a StatefulSet, which provides stable pod identifiers, persistent storage linked to specific pods, and ordered deployment for stateful applications.
For detailed information about the tables, see db.py.
- devices: stores devices.
- metrics: stores collected metrics from the monitored device.
- anomalies: stores detected anomalies.
- trained_models: stores trained models.
- users: stores users.
and can be opened via psql:
kubectl exec -it statefulset/postgres-statefulset -n mona -- psql -U myuser -d mydb
# ⬆ pod name ⬆ namespace ⬆ Username ⬆ DB nameMONA uses a stateful, cookie-based authentication system backed by Redis to secure the admin panel and core API endpoints.
During deployment, the seed_admin function runs automatically on startup. It reads the ADMIN_USERNAMES,ADMIN_PASSWORDS and USER_USERNAMES,USER_PASSWORDS environment variables (configured via your terraform.tfvars or Helm values) and provisions the initial user and admin accounts in the PostgreSQL database if it does not already exist.
- Session Management: Upon a successful POST request to
/api/auth/login, FastAPI generates a cryptographically secure 32-byte session token. - Redis Storage: This token is stored in the Redis broker with a 12-hour expiration time (
ex=43200), linking the session to the user's ID. - Cookies: The token is returned to the frontend as an
HttpOnly,Laxcookie nameduser_session. This ensures the token is automatically sent with subsequent requests while remaining protected from cross-site scripting (XSS) attacks. - Access Control: All protected endpoints — except health checks (
/health/live,/health/ready) and Prometheus metrics (/api/prometheus/targets) — are routed through role-awareuser_router/admin_routerdependencies that validate the session token against Redis. Users are restricted to GET requests only, giving them read-only access to dashboards and device data, while admins have full access to all methods —GET,POST,PUT,DELETE— including device management and ML training endpoints. If the session is missing or expired, the API returns401 Unauthorized; if the session is valid but the account's role doesn't permit the requested method, it returns403 Forbidden. - Logout: Endpoint
/api/auth/logoutdeletes the session key from Redis and clears the client's cookie.
P.S. Endpoints like /health/live, /health/ready, and Prometheus target metrics (/api/prometheus/targets) are intentionally excluded from authentication to allow seamless cluster monitoring.
Automated checks and docker build & push run on every push and pull request:
- Gitleaks: — leaks scan
- Checkov: — IaC scan
- Terraform — format and validation checks
- Helm — lint for helm charts
- YAML — lint for values and chart files
- Python — ruff (lint and format checks), MyPy (type checks), Pytest (Api tests)
- Docker - scan images via Trivy
Here more about architecture and how mona works.
MONA's ML model has CONTAMINATION = 0.05 which means up to 5% of data points might be classified as anomalies, even if there are none.
To reduce false positive detections, the model is equipped with a limiter SCORE_THRESHOLD = -0.05.
In other words, it discards anomalies that the model estimates at less than a 5% confidence threshold. To definitively rule out false positives, the model also ignores "combined anomalies" if CPU and RAM usage are below 80%.
Managing monitored devices in MONA can be done in two ways to ensure flexibility:
- Values.yaml: Ideal for bulk-adding devices during deployment and preventing accidental deletions. FastAPI reads these configurations and commits them to the database.
- Admin Panel / API: Allows dynamically adding or removing devices on the fly via HTTP POST/DELETE requests.
Prometheus consistently scrapes a dedicated endpoint to fetch the most up-to-date list of devices from the database, seamlessly merging both approaches.
To maintain a responsive REST API, heavy ML model training tasks are offloaded to Celery. Because these tasks are asynchronous, FastAPI implements a dedicated task-tracking endpoint using Redis to reliably monitor task status and return responses.
- Init Containers: FastAPI and Celery deployments use
busyboxinit scripts to wait for the database to be fully operational before starting the pods. - Probes: FastAPI includes two health-check endpoints for Kubernetes: one for Liveness (API health) and one for Readiness (Database connectivity).