Docs
Running in one command, reading in one glance.
Install, point it at a context, and read. Everything below assumes a working kubeconfig and nothing else.
01 — Quickstart
Three lines from nothing to a dashboard.
The container mounts your kubeconfig read-only and serves the UI on port 3000. Stop it and nothing remains.
02 — Reference
01
Configuration
Environment variables, ports, context selection and caching.
02
Authentication
kubeconfig, exec plugins, EKS / GKE / AKS, in-cluster service accounts.
03
RBAC & permissions
The minimal read-only ClusterRole, and what degrades without it.
04
Metrics & cost
metrics-server requirements and the optional AWS cost integration.
05
Troubleshooting
Empty dashboards, TLS errors, timeouts and expired credentials.
06
Architecture
How a page request becomes an API-server read. No agents involved.
03 — Configuration
Environment variables, all optional.
KUBECONFIG~/.kube/configPath (or colon-separated paths) to the config to read
K8LENS_CONTEXTcurrent-contextStart on a specific context instead of the active one
K8LENS_NAMESPACESallRestrict reads to a comma-separated allowlist
K8LENS_CACHE_TTL5sHow long a list response is reused across page loads
K8LENS_DEV_MODEfalseShow the kubectl equivalent of every read in the UI
04 — RBAC
get, list, watch. Nothing more.
Bind this ClusterRole to the identity K8Lens runs as. Anything it cannot read is hidden, not broken.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: k8lens-read-only
rules:
- apiGroups: ["", "apps", "batch", "networking.k8s.io", "rbac.authorization.k8s.io"]
resources: ["*"]
verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
resources: ["pods", "nodes"]
verbs: ["get", "list"]
05 — Troubleshooting
Dashboard loads, everything is emptyThe identity can reach the API server but has no list permission. Bind the read-only ClusterRole above.
x509: certificate signed by unknown authorityThe cluster CA isn't in the mounted kubeconfig. Mount the referenced CA file too, or embed it with --embed-certs.
CPU and memory panels show no datametrics-server isn't installed or isn't ready. Everything else keeps working without it.
Credentials expire after an hourYour context uses an exec plugin whose binary isn't in the container. Run K8Lens in-cluster, or mount the CLI it needs.
Still stuck? Open an issue.
Include your Kubernetes version and distribution.