Getting Started with KubeLedger

Quick start guide to install and run KubeLedger on your cluster.

Prerequisites

Before getting started, ensure you have:

  • Kubernetes cluster v1.19+ (or OpenShift 4.x+)
  • kubectl configured with cluster access
  • Helm 3.x (fine-tuned installation) or kubectl for a basic opinionated deployment
  • Cluster permissions: read access to pods, nodes, and namespaces
  • Kubernetes Metrics Server deployed in your cluster (required for CPU and memory metrics)
  • NVIDIA DCGM Exporter deployed in your cluster (required for GPU metrics, optional if no GPUs)

Verify Metrics Server

Before installing, ensure metrics-server is running in your cluster:

# Check if metrics-server is deployed
kubectl -n kube-system get deploy | grep metrics-server

# Verify it's working
kubectl top nodes

# If not installed, deploy with kubectl
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Verify DCGM Exporter (GPU metrics)

If your cluster has NVIDIA GPUs and you want GPU metrics, ensure DCGM Exporter is running:

# Check if DCGM Exporter is deployed
kubectl get daemonset -A | grep dcgm

# If not installed, deploy with Helm (requires NVIDIA GPU Operator or drivers)
helm repo add gpu-helm-charts https://nvidia.github.io/dcgm-exporter/helm-charts
helm install dcgm-exporter gpu-helm-charts/dcgm-exporter \
  --namespace gpu-operator \
  --create-namespace

Clone the Repository

git clone https://github.com/realopslabs/kubeledger.git --depth=1
cd kubeledger

Installation on Kubernetes/OpenShift Cluster

Install with Kustomize (Fast Path)

OpenShift users: Skip this section and use Helm installation with OpenShift-specific settings.

# Create namespace
kubectl create namespace kubeledger

# Deploy using Kustomize
kubectl apply -k ./manifests/kubeledger/kustomize -n kubeledger

# Watch pod status
kubectl get pods -n kubeledger -w

Install with Helm (Advanced)

For advanced customization (OpenShift, custom storage, etc.), edit manifests/kubeledger/helm/values.yaml:

  • OpenShift: Set securityContext.openshift: true
  • Custom storage: Set dataVolume.storageClass and dataVolume.capacity
  • DCGM Integration: Set dcgm.enable: true and dcgm.endpoint

Then run:

# Create namespace
kubectl create namespace kubeledger

# Install with Helm
helm upgrade --install kubeledger ./manifests/kubeledger/helm -n kubeledger

# Watch pod status
kubectl get pods -n kubeledger -w

Access the Dashboard on Kubernetes/OpenShift Cluster

# Port-forward to access the UI
kubectl port-forward svc/kubeledger 5483:80 -n kubeledger

# Open http://localhost:5483 in your browser

Installation on Local Machine

Install with Docker

Requires kubectl proxy running locally to provide API access:

# Start kubectl proxy in background
kubectl proxy &

# Run KubeLedger
docker run -d \
  --net="host" \
  --name kubeledger \
  -v /var/lib/kubeledger:/data \
  -e KL_DB_LOCATION=/data/db \
  -e KL_K8S_API_ENDPOINT=http://127.0.0.1:8001 \
  ghcr.io/realopslabs/kubeledger

Access the Dashboard on Local Machine

The dashboard is available at http://localhost:5483.