What is Klances?

A read-only WebUI dashboard for Kubernetes cluster monitoring. Designed for end-users unfamiliar with Kubernetes and for cluster admins who want a quick status overview. Also exposes a fully functional REST API for integration with other tools.

What's displayed by Klances:

• Cluster status (overall health, version)
• Node list (roles, version, CPU, Memory)
• Namespace list (status, CPU, Memory, Pod count)
• Pod list for each namespace (status, CPU, Memory with current/requested/limit)
• Pod details — services/ingress, events, logs

Installation

With Helm (recommended)

helm repo add klances https://nicolargo.github.io/klances
helm repo update
helm install klances klances/klances

To install in a specific namespace:

helm install klances klances/klances --namespace monitoring --create-namespace

Port forwarding

kubectl port-forward service/klances 8080:8080 -n monitoring

or with minikube:

minikube kubectl -- port-forward service/klances 8080:8080 -n monitoring

Then open http://localhost:8080/frontend/ in your browser.

Exposing Klances outside the cluster

Create a my-values.yaml file to enable Ingress:

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: klances.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: klances-tls
      hosts:
        - klances.example.com

Then install (or upgrade) with:

helm install klances klances/klances -f my-values.yaml

For additional options, consult the chart documentation.

With Docker

docker run --rm -p 8000:8000 \
  -v ~/.kube/config:/root/.kube/config:ro \
  ghcr.io/nicolargo/klances

Then open http://localhost:8000/frontend/ in your browser.

Locally

Requirements: Python >= 3.10, Node.js >= 18, a Kubernetes cluster reachable via ~/.kube/config.

make install   # install all dependencies (first time only)
make build     # compile the frontend
klances        # start the server

The klances command accepts options:

klances                      # defaults: 0.0.0.0:8000, 1 worker
klances --port 9000          # custom port
klances --workers 4          # multi-process
klances --host 127.0.0.1     # bind to localhost only

If no cluster configuration is available, Klances starts gracefully and displays a "cluster unreachable" message in the WebUI until a connection is established.

Development corner

Setting up the dev environment

Requirements: Python >= 3.10, Node.js >= 18.

# 1. Install all dependencies (backend + frontend)
make install

# 2. Start the development server
make run

This single command:

• Builds the Vue.js frontend once
• Watches src/frontend/src/ for changes and rebuilds automatically
• Starts the FastAPI server with auto-reload on port 8000

Open http://localhost:8000/frontend/ in your browser.

Makefile commands

make install    Install all dependencies (backend + frontend)
make update     Update all dependencies (backend + frontend)
make audit      Check dependencies for known security vulnerabilities
make run        Start the development server on port 8000
make build      Build the frontend for production + generate OpenAPI spec
make test       Run all backend tests (pytest)
make test-one   Run a single test file (TEST=tests/test_cluster.py)
make lint       Lint with ruff
make format     Format with ruff
make docker     Build the Docker image
make docker-run Run Klances in Docker (needs ~/.kube/config)
make clean      Remove virtualenv, caches and frontend build

API documentation

Interactive API docs are available at http://localhost:8000/api/1/docs when the server is running.

The OpenAPI specification is also available as a static file in docs/openapi.json (regenerated by make build).

Path	Description
/frontend/	Vue.js WebUI dashboard
/api/1/docs	Interactive REST API documentation
/api/1/status	API health check
/api/1/cluster	Cluster info and status
/api/1/nodes	Node list with resources
/api/1/namespaces	Namespace list with aggregated resources
/api/1/namespaces/{ns}/pods	Pod list for a namespace
/api/1/namespaces/{ns}/pods/{pod}	Pod details (services, ingresses, events, logs)

License

Klances is licensed under the MIT License. See the LICENSE file for more details.