Quick Start

Get KubeGraf running and see value in under 5 minutes.

Prerequisites: You need a working kubectl configuration with access to a Kubernetes cluster. If you haven't installed KubeGraf yet, see the Installation guide first.

1

Launch KubeGraf

Start the terminal UI (recommended for first-time users):

kubegraf

KubeGraf automatically reads your ~/.kube/config and connects to the current context.

Or launch the web dashboard:

kubegraf --web

Then open http://localhost:3000 in your browser.

2

Explore Your Cluster

Once KubeGraf is running, you'll see:

  • Resource Overview - Pods, deployments, services in your cluster
  • Incident Detection - Automatic alerts for CrashLoopBackOff, OOMKilled, probe failures
  • Real-time Events - Live updates as your cluster changes

Navigate using Tab to switch views, j/k to move up/down, and Enter to view details.

3

Try Incident Diagnosis

Press d on any failing pod to see KubeGraf's intelligent diagnosis:

  • Correlated events and logs explaining the failure
  • Recent changes (deployments, configs, secrets)
  • Suggested fixes with dry-run preview

This is where KubeGraf's value becomes clear—it explains why things failed, not just what failed.

What You'll See

KubeGraf automatically monitors your cluster and highlights issues:

🔴 Incident Detection

Automatically detects and highlights:

  • CrashLoopBackOff
  • OOMKilled
  • ImagePullBackOff
  • Probe failures
  • Pending pods
  • Restart storms

💡 Intelligent Diagnosis

Press d on any failing pod to see:

  • Correlated events timeline
  • Relevant log excerpts
  • Recent configuration changes
  • Suggested fixes

Basic Navigation (Terminal UI)

The terminal UI uses vim-style keybindings for fast, keyboard-driven operations:

Navigation & Viewing

  • j / k - Move up/down
  • Tab - Switch between tabs
  • Enter - View resource details
  • n - Change namespace
  • c - Change context/cluster
  • / - Search/filter resources

Actions & Debugging

  • l - View logs (pod)
  • d - Diagnose incident NEW
  • s - Shell into container
  • r - Refresh resources
  • ? - Show all keybindings
  • q - Quit

Pro tip: Press d on any failing pod to see KubeGraf's incident diagnosis with correlated events, logs, and suggested fixes.

Quick Tips

Switch Clusters

Use different contexts or kubeconfig files:

kubegraf --context my-cluster
kubegraf --kubeconfig /path/to/config

Filter by Namespace

Focus on specific namespaces:

kubegraf -n kube-system
kubegraf -A  # All namespaces

Next Steps

You're ready to use KubeGraf! Here's what to explore next:

📚 Learn More

🔧 Troubleshooting

💾 Local-first: All incident history is stored locally in ~/.kubegraf/knowledge-bank.db. No data leaves your machine.

Previous
Overview
Next
Installation