# k3s Health Dashboard

A Streamlit dashboard for monitoring a k3s (or any Kubernetes) cluster — nodes, pods, deployments, and metrics in one place.

## Architecture

```
app/
  main.py          FastAPI backend (REST API)
  cache.py         Streamlit cache wrappers (TTL-based)
  k8s_client.py    Kubernetes API client & data helpers
  config.py        Config loaded from environment variables
  routers/         FastAPI route handlers
app.py             Streamlit frontend entry point
k3s-dashboard.yaml Kubernetes deployment manifest
```

## Prerequisites

- Python 3.10+
- A running Kubernetes cluster with a valid kubeconfig at `~/.kube/config`
- (Optional) `metrics-server` installed on the cluster for CPU/memory usage

## Local setup

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Copy the example environment file and edit as needed:

```bash
cp .env .env.local
```

Key environment variables:

| Variable          | Default               | Description                          |
|-------------------|-----------------------|--------------------------------------|
| `KUBECONFIG`      | `~/.kube/config`      | Path to kubeconfig                   |
| `IN_CLUSTER`      | (unset)               | Set to `true` when running as a pod  |
| `CACHE_TTL`       | `15`                  | Seconds between Kubernetes API calls |
| `METRICS_ENABLED` | `true`                | Set `false` if metrics-server absent |

## Running locally

**Streamlit dashboard:**

```bash
streamlit run app.py
```

Opens at `http://localhost:8501`.

**FastAPI backend only:**

```bash
uvicorn app.main:app --reload
```

API docs at `http://localhost:8000/docs`.

## Running tests

```bash
pytest
```

## Deploying to Kubernetes

1. Build and push the Docker image:

```bash
docker build -t your-registry/k3s-dashboard:latest .
docker push your-registry/k3s-dashboard:latest
```

2. Update the image name in `k3s-dashboard.yaml`, then apply:

```bash
kubectl apply -f k3s-dashboard.yaml
```

The manifest creates a `ServiceAccount` with read-only `ClusterRole` access to nodes, pods, namespaces, and metrics.