{"id":44590972,"url":"https://github.com/realopslabs/kubeledger","last_synced_at":"2026-02-20T20:03:27.917Z","repository":{"id":39544707,"uuid":"165441156","full_name":"realopslabs/kubeledger","owner":"realopslabs","description":"The System of Record for Kubernetes accounting. Tracks CPU/RAM/GPU usage \u0026 costs per namespace, revealing hidden overhead. (Formerly Kube-Opex-Analytics).","archived":false,"fork":false,"pushed_at":"2026-02-14T07:48:57.000Z","size":20620,"stargazers_count":473,"open_issues_count":5,"forks_count":54,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-02-14T13:17:27.916Z","etag":null,"topics":["accounting","cost-optimization","finops","gpu","greenops","kubernetes","monitoring","observability","rrdtool"],"latest_commit_sha":null,"homepage":"https://kubeledger.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/realopslabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-01-12T22:14:46.000Z","updated_at":"2026-02-14T10:17:41.000Z","dependencies_parsed_at":"2026-01-08T19:02:22.821Z","dependency_job_id":null,"html_url":"https://github.com/realopslabs/kubeledger","commit_stats":null,"previous_names":["realopslabs/kubeledger"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/realopslabs/kubeledger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realopslabs%2Fkubeledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realopslabs%2Fkubeledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realopslabs%2Fkubeledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realopslabs%2Fkubeledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realopslabs","download_url":"https://codeload.github.com/realopslabs/kubeledger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realopslabs%2Fkubeledger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29662591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T19:49:36.704Z","status":"ssl_error","status_checked_at":"2026-02-20T19:44:05.372Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","cost-optimization","finops","gpu","greenops","kubernetes","monitoring","observability","rrdtool"],"created_at":"2026-02-14T07:06:24.127Z","updated_at":"2026-02-20T20:03:27.912Z","avatar_url":"https://github.com/realopslabs.png","language":"JavaScript","funding_links":[],"categories":["Python","AI for *Ops","JavaScript"],"sub_categories":["Automation \u0026 Self-Healing"],"readme":"# KubeLedger\n\n![logo-thumbnail](screenshots/thumbnail-header.png)\n\n[![Release](https://img.shields.io/github/v/release/realopslabs/kubeledger?label=Latest%20Release\u0026style=for-the-badge)](https://github.com/realopslabs/kubeledger/releases)\n![Docker Hub pulls](https://img.shields.io/docker/pulls/rchakode/kube-opex-analytics.svg?label=Docker%20Pulls\u0026style=for-the-badge)\n[![GHCR Pulls](https://img.shields.io/badge/docker-ghcr.io%2Frealopslabs%2Fkubeledger-blue?style=for-the-badge)](https://github.com/realopslabs/kubeledger/pkgs/container/kubeledger)\n\n---\n**KubeLedger** is the System of Record that tracks the full picture of Kubernetes costs — revealing the 30% hidden in non-allocatable overhead for precise, per-namespace accounting.\n\n\n\u003e **Note:** KubeLedger was formerly known as **Kubernetes Opex Analytics** aka `kube-opex-analytics`.\n\u003e Read more about this change in our [announcement blog post](https://kubeledger.io/blog/2025/01/01/kubeledger-announcement/). To handle the migration in a straightforward way, we have provided a [migration procedure](https://kubeledger.io/docs/migration-from-kube-opex-analytics-to-kubeledger/).\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Quick Start](#quick-start)\n- [Architecture](#architecture)\n- [Documentation](#documentation)\n- [Configuration](#configuration)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n- [Support \u0026 Contributions](#support--contributions)\n\n## Overview\n\n**KubeLedger** is a usage accounting tool that helps organizations track, analyze, and optimize **CPU, Memory, and GPU** resources on Kubernetes clusters over time (hourly, daily, monthly).\n\nIt acts as a **System of Record** for your cluster resources, providing insightful usage analytics and charts that engineering and financial teams can use as key indicators for cost optimization decisions.\n\n### Tracked Resources\n\n- **CPU** - Core usage and requests per namespace\n- **Memory** - RAM consumption and requests per namespace\n- **GPU** - NVIDIA GPU utilization via DCGM integration\n\n![kubeledger-overview](screenshots/kubeledger-demo.gif)\n\n\u003e **Multi-cluster Integration:** KubeLedger tracks usage for a single Kubernetes cluster. For centralized multi-cluster analytics, see [Krossboard Kubernetes Operator](https://github.com/2-alchemists/krossboard) ([demo video](https://youtu.be/lfkUIREDYDY)).\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Hourly/Daily/Monthly Trends** | Tracks actual usage and requested capacities per namespace, collected every 5 minutes and consolidated hourly |\n| **Non-allocatable Capacity Tracking** | Highlights system overhead (OS, kubelets) vs. usable application capacity at node and cluster levels |\n| **Cluster Capacity Planning** | Visualize consumed capacity globally, instantly, and over time |\n| **Usage Efficiency Analysis** | Compare resource requests against actual usage to identify over/under-provisioning |\n| **Cost Allocation \u0026 Chargeback** | Automatic resource usage accounting per namespace for billing and showback |\n| **Prometheus Integration** | Native exporter at `/metrics` for Grafana dashboards and alerting |\n\n## Quick Start\n\n### Prerequisites\n\n- Kubernetes cluster v1.19+ (or OpenShift 4.x+)\n- `kubectl` configured with cluster access\n- Helm 3.x (fine-tuned installation) or `kubectl` for a basic opinionated deployment\n- Cluster permissions: read access to pods, nodes, and namespaces\n- **[Kubernetes Metrics Server](https://github.com/kubernetes-sigs/metrics-server)** deployed in your cluster (required for CPU and memory metrics)\n- **[NVIDIA DCGM Exporter](https://github.com/NVIDIA/dcgm-exporter)** deployed in your cluster (required for GPU metrics, optional if no GPUs)\n\n### Verify Metrics Server\n\nBefore installing, ensure metrics-server is running in your cluster:\n\n```bash\n# Check if metrics-server is deployed\nkubectl -n kube-system get deploy | grep metrics-server\n\n# Verify it's working\nkubectl top nodes\n\n# If not installed, deploy with kubectl\nkubectl apply -f [https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml](https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml)\n```\n\n### Verify DCGM Exporter (GPU metrics)\n\nIf your cluster has NVIDIA GPUs and you want GPU metrics, ensure DCGM Exporter is running:\n\n```bash\n# Check if DCGM Exporter is deployed\nkubectl get daemonset -A | grep dcgm\n\n# If not installed, deploy with Helm (requires NVIDIA GPU Operator or drivers)\nhelm repo add gpu-helm-charts https://nvidia.github.io/dcgm-exporter/helm-charts\nhelm install dcgm-exporter gpu-helm-charts/dcgm-exporter \\\n  --namespace gpu-operator \\\n  --create-namespace\n```\n\n### Clone the Repository\n\n```bash\ngit clone https://github.com/realopslabs/kubeledger.git --depth=1\ncd kubeledger\n```\n\n## Installation on Kubernetes/OpenShift Cluster\n\n### Install with Kustomize (Fast Path)\n\n\u003e **OpenShift users:** Skip this section and use [Helm installation](#install-with-helm-advanced) with OpenShift-specific settings.\n\n```bash\n# Create namespace\nkubectl create namespace kubeledger\n\n# Deploy using Kustomize\nkubectl apply -k ./manifests/kubeledger/kustomize -n kubeledger\n\n# Watch pod status\nkubectl get pods -n kubeledger -w\n```\n\n### Install with Helm (Advanced)\n\nThe following steps covers the following scenarios of advanced customization (see `manifests/kubeledger/helm/values.yaml` for more options):\n\n- **OpenShift:** Set `securityContext.openshift: true`\n- **Custom storage:** Set `dataVolume.storageClass` and `dataVolume.capacity`\n- **DCGM Integration:** Set `dcgm.enable: true` and `dcgm.endpoint`\n\n```bash\n# Create namespace\nkubectl create namespace kubeledger\n\n# Install with Helm on Kubernetes\nhelm upgrade --install kubeledger ./manifests/kubeledger/helm -n kubeledger\n\n# Install with Helm on Kubernetes with GPU support\nhelm upgrade --install kubeledger ./manifests/kubeledger/helm -n kubeledger \\\n  --set dcgm.enable=true \\\n  --set dcgm.endpoint=\"dcgm-exporter.monotiring.svc.cluster.local:9400\"\n\n# Install with Helm on OpenShift\nhelm upgrade --install kubeledger ./manifests/kubeledger/helm -n kubeledger --set securityContext.openshift=true\n\n# Install with Helm on OpenShift with GPU support\nhelm upgrade --install kubeledger ./manifests/kubeledger/helm -n kubeledger \\\n  --set securityContext.openshift=true \\\n  --set dcgm.enable=true \\\n  --set dcgm.endpoint=\"dcgm-exporter.monotiring.svc.cluster.local:9400\"\n\n# Watch pod status\nkubectl get pods -n kubeledger -w\n```\n\n### Access the Dashboard on Kubernetes/OpenShift Cluster\n\n```bash\n# Port-forward to access the UI\nkubectl port-forward svc/kubeledger 5483:80 -n kubeledger\n\n# Open http://localhost:5483 in your browser\n```\n\n## Installation on Local Machine\n\n### Install with Docker\n\nRequires `kubectl proxy` running locally to provide API access:\n\n```bash\n# Start kubectl proxy in background\nkubectl proxy \u0026\n\n# Run KubeLedger\ndocker run -d \\\n  --net=\"host\" \\\n  --name kubeledger \\\n  -v /var/lib/kubeledger:/data \\\n  -e KL_DB_LOCATION=/data/db \\\n  -e KL_K8S_API_ENDPOINT=http://127.0.0.1:8001 \\\n  ghcr.io/realopslabs/kubeledger\n```\n\n### Access the Dashboard on Local Machine\n\nThe dashboard is available at http://localhost:5483.\n\n\n## Architecture\n\n```\n┌───────────────────┐\n│  Metrics Server   │──┐\n│  (CPU/Memory)     │  │    ┌───────────────────────────────────────┐\n└───────────────────┘  ├───\u003e│         KubeLedger                    │\n┌───────────────────┐  │    │  ┌─────────┐  ┌────────┐  ┌─────────┐ │\n│  DCGM Exporter    │──┘    │  │ Poller  │─\u003e│RRD DBs │─\u003e│ API     │ │\n│  (GPU metrics)    │       │  │ (5 min) │  │        │  │         │ │\n└───────────────────┘       │  └─────────┘  └────────┘  └────┬────┘ │\n                            └────────────────────────────────┼──────┘\n                                                             │\n                            ┌────────────────────────────────┼───────┐\n                            │                                v       │\n                            │  ┌────────────┐    ┌──────────────┐    │\n                            │  │  Web UI    │    │  /metrics    │    │\n                            │  │  (D3.js)   │    │ (Prometheus) │    │\n                            │  └────────────┘    └──────────────┘    │\n                            └────────────────────────────────────────┘\n                                     │                  │\n                                     v                  v\n                              Built-in Dashboards   Grafana/Alerting\n```\n\n**Data Flow:**\n1. Metrics polled every 5 minutes (configurable):\n   - CPU/Memory from Kubernetes Metrics Server\n   - GPU from NVIDIA DCGM Exporter\n2. Metrics are processed and stored in internal lightweight time-series databases (round-robin DBs)\n3. Data is consolidated into hourly, daily, and monthly aggregates\n4. API serves data to the built-in web UI and Prometheus scraper\n\n## Documentation\n\n| Topic | Link |\n|-------|------|\n| Installation on Kubernetes and OpenShift | https://kubeledger.io/docs/installation-on-kubernetes-and-openshift/ |\n| Installation on Docker | https://kubeledger.io/docs/installation-on-docker/ |\n| Built-in Dashboards and Charts of KubeLedger | https://kubeledger.io/docs/built-in-dashboards-and-charts/ |\n| Prometheus Exporter and Grafana dashboards | https://kubeledger.io/docs/prometheus-exporter-grafana-dashboard/ |\n| KubeLedger Configuration Settings | https://kubeledger.io/docs/configuration-settings/ |\n| Design Fundamentals | https://kubeledger.io/docs/design-fundamentals/ |\n\n## Configuration\n\n\u003e **Migration Note:** All environment variables now use the `KL_` prefix. Old `KOA_` variables are deprecated but will be supported for backward compatibility for 6 months.\n\nKey environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `KL_K8S_API_ENDPOINT` | Kubernetes API server URL | Required |\n| `KL_K8S_AUTH_TOKEN` | Service account token | Auto-detected in-cluster |\n| `KL_DB_LOCATION` | Path for RRDtool databases | `/data` |\n| `KL_POLLING_INTERVAL_SEC` | Metrics collection interval | `300` |\n| `KL_COST_MODEL` | Billing model (`CUMULATIVE_RATIO`, `RATIO`, `CHARGE_BACK`) | `CUMULATIVE_RATIO` |\n| `KL_BILLING_HOURLY_RATE` | Hourly cost for chargeback model | `-1.0` |\n| `KL_BILLING_CURRENCY_SYMBOL` | Currency symbol for cost display | `$` |\n| `KL_NVIDIA_DCGM_ENDPOINT` | NVIDIA DCGM Exporter endpoint for GPU metrics | Not set (GPU disabled) |\n\n### GPU Metrics (NVIDIA DCGM)\n\nTo enable GPU metrics collection, set the DCGM Exporter endpoint:\n\n```bash\n# Environment variable\nexport KL_NVIDIA_DCGM_ENDPOINT=http://dcgm-exporter.gpu-operator:9400/metrics\n\n# Or with Helm\nhelm upgrade --install kubeledger ./manifests/kubeledger/helm \\\n  --set dcgm.enabled=true \\\n  --set dcgm.endpoint=http://dcgm-exporter.gpu-operator:9400/metrics\n```\n\nSee [Configuration Settings](./docs/configuration-settings.md) for the complete reference.\n\n## Troubleshooting\n\n### Common Issues\n\n**Pod stuck in CrashLoopBackOff**\n- Check logs: `kubectl logs -f deployment/kubeledger -n kubeledger`\n- Verify RBAC permissions are correctly applied\n- Ensure the service account has read access to pods and nodes\n\n**No data appearing in dashboard**\n- Wait at least 5-10 minutes for initial data collection\n- Verify the pod can reach the Kubernetes API: check for connection errors in logs\n- Confirm `KL_K8S_API_ENDPOINT` is correctly set\n\n**Metrics not appearing in Prometheus**\n- Ensure the `/metrics` endpoint is accessible\n- Check ServiceMonitor/PodMonitor configuration if using Prometheus Operator\n- Verify network policies allow Prometheus to scrape the pod\n\n**Pooling interval**\n- By default, the polling interval to collect raw metrics from Kubernetes API or NVIDIA DCGM is 300 seconds (5 minutes).\n- You can increase this limit using the variable `KL_POLLING_INTERVAL_SEC`. Always use a multiple  300 seconds, as the backend RRD database is based on a 5-minutes resolution.\n\n\n## Support \u0026 Feedback\n\nWe welcome feedback and contributions!\n\n- **Submit an issue:** [GitHub Issues](https://github.com/realopslabs/kubeledger/issues)\n- **Contribute Code:** [Pull Requests](https://github.com/realopslabs/kubeledger/pulls)\n\nAll contributions must be released under Apache 2.0 License terms.\n\n## License\n\nKubeLedger is licensed under the [Business Source License 1.1](LICENSE.md).\n\n**Permitted:** Non-commercial use, internal business use, development, testing, and personal projects.\n\n**Not Permitted:** Offering KubeLedger as a commercial hosted service or managed offering.\n\nThe license converts to Apache 2.0 on [DATE + 4 years].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealopslabs%2Fkubeledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealopslabs%2Fkubeledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealopslabs%2Fkubeledger/lists"}