Connect your first cluster
Why this matters
KubeGraf is only useful once it’s looking at a real cluster. The fastest way to build trust is to
connect it to a kubeconfig you already use every day and see familiar workloads show up.
This guide walks you from “fresh install” to “I can see my cluster, pods, and events in KubeGraf” in a few minutes.
Prerequisites
- You can reach a Kubernetes cluster with
kubectl from your machine.
kubectl config current-context points to the cluster you want to use.- KubeGraf is installed:
curl -sSL https://kubegraf.io/install.sh | bash
Tip: Keep production and non‑production contexts clearly named (prod-cluster, staging-cluster, kind-dev)
so it’s obvious which cluster you’re connecting to in KubeGraf.
Real example: connect staging-cluster
1. Confirm context
kubectl config current-context
staging-cluster
kubectl get nodes
2. Launch the Terminal UI
kubegraf
KubeGraf will read ~/.kube/config, use the current context, and show a cluster summary.
3. Verify the namespace you care about
In the Terminal UI:
- Press
n to change namespace.
- Type
payments (or another namespace that exists).
4. Launch the Web Dashboard (optional)
kubegraf --web
Then open http://localhost:3000 in your browser to see the same cluster in the web UI.
Common mistakes: running kubegraf before verifying that kubectl can talk to the cluster, or forgetting that
kubegraf respects the current context.
Screenshot placeholder
[ screenshot: overview card showing 1 cluster, 2 nodes, namespaces, and pods by status ]
Expected outcome
By the end of this guide you should:
- Have KubeGraf successfully connected to at least one cluster via your existing kubeconfig.
- Be able to see nodes, namespaces, and workloads for that cluster.
- Know how to switch clusters and namespaces from within the UI instead of editing kubeconfig by hand.