Skip to content

Getting started

This guide walks you from a fresh install to your first kube-saver output on the four most common cluster types.

Requires Python 3.10+ and a reachable Kubernetes cluster with read permissions. Setup time depends on cluster access, credentials, and metrics availability.

1. Install

The PyPI kube-saver endpoint returned HTTP 404 on 2026-10-09 UTC. Install the reviewed 2.0.0 source commit below; this requires Git as well as Python. The full commit ID keeps the install independent of later branch changes.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/pooyanazad/kube-saver.git@b2f0fdfc54fb13621c602373b7a5b91a8d483c3f"

Alternatively, download a wheel from the selected GitHub release, verify it against that release's SHA256SUMS.txt, and install the downloaded file:

python -m pip install ./kube_saver-2.0.0-py3-none-any.whl
kube-saver version

The wheel command assumes the 2.0.0 release has been published and the wheel is in your current directory; it does not download an unavailable package from PyPI. Before publication, use the pinned source install above.

From source (recommended for development):

git clone https://github.com/pooyanazad/kube-saver.git
cd kube-saver
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Install metrics-server in the cluster for measured CPU and memory usage. Without it, kube-saver shows request-based estimates and does not generate actionable right-sizing recommendations. eBPF capability detection is experimental; live eBPF probes are not implemented in this release.

2. Validate your connection

Before running a full scan, verify kube-saver can reach your cluster and has the permissions it needs:

kube-saver doctor

doctor checks kubeconfig, context, cluster reachability, required RBAC, and Metrics API availability. Missing metrics are optional warnings: request-based estimates can still run. A passing check does not guarantee fresh samples for every pod. See CLI reference and Troubleshooting.

If scans use a configured context, pass that same name to doctor --context:

KUBE_SAVER_CONTEXT=staging-cluster kube-saver doctor --context staging-cluster

doctor --context overrides the configured context. Without that option, doctor uses KUBE_SAVER_CONTEXT or kubeconfig_context, then the kubeconfig current context.

3. Run by environment

Local cluster, kind / minikube / Docker Desktop

# Make sure your local cluster is running
kubectl cluster-info

# Launch the TUI
kube-saver

To try it locally, use any Kubernetes cluster with at least one workload that sets CPU and memory requests. Install metrics-server to see measured waste and right-sizing recommendations.

AWS EKS

aws eks update-kubeconfig --name my-cluster --region us-east-1
kube-saver

When launched inside a pod, kube-saver can use the mounted Kubernetes service account token. The service account needs Kubernetes RBAC read permissions; an AWS IAM role alone does not grant those permissions.

Generic kubeconfig

export KUBECONFIG=/path/to/kubeconfig
kube-saver

If your kubeconfig has multiple contexts, pass the one you want:

KUBE_SAVER_CONTEXT=staging-cluster kube-saver

Restricted / read-only RBAC

You only need list and get permissions on a small set of resources. See Safety & trust for the exact YAML.

4. Your first output

The fastest path to a real, shareable artifact:

# Self-contained HTML report (open it in any browser)
kube-saver report -o cost-report.html
# Open cost-report.html in your browser

The HTML file has no external assets, no CDN, and no JavaScript dependencies, it works offline, in an email attachment, and in a CI artifact.

If you want a TUI session:

# Key bindings:
#   1         namespace overview (default)
#   2         cost breakdown
#   3         recommendations
#   enter     drill into selected namespace
#   /         search / filter
#   r         refresh
#   q         quit
kube-saver

If metrics-server is unavailable, the cost figures represent an upper bound based on requests. They are not measured savings, and no right-sizing recommendations or spike alert is issued from those estimates.

If you want a PR-ready plan:

kube-saver pr-plan -d ./pr-files
ls ./pr-files
#   summary.md          human-readable summary
#   apply-patches.sh    ready-to-run patch script (does not auto-apply)
#   review.txt          every recommended change with reasoning

5. Daily / CI use

Add kube-saver to a cron job or CI pipeline:

# Daily Markdown summary; optional spike alert with complete measured coverage
kube-saver notify -d ./alerts --threshold 250

# JSON output for pipelines
kube-saver report -o report.html --json report.json

For a CI artifact with self-contained HTML:

- name: Generate cost report
  run: |
    python -m pip install "git+https://github.com/pooyanazad/kube-saver.git@b2f0fdfc54fb13621c602373b7a5b91a8d483c3f"
    kube-saver report -o cost-report.html
- name: Upload
  uses: actions/upload-artifact@v4
  with:
    name: cost-report
    path: cost-report.html

Next steps