# kube-burner: orchestrating Kubernetes scale and performance tests

> kube-burner is a Go binary that creates, deletes and patches Kubernetes resources at scale while collecting Prometheus metrics, taking measurements and firing alerts, built on client-go. It is driven by YAML workload files, ships a container image and static hardened builds, and exists to answer the question of what a cluster does under a specific load.

**kube-burner/kube-burner** — Kubernetes performance and scale test orchestration framework written in golang

- Repository: https://github.com/kube-burner/kube-burner
- Website: https://kube-burner.github.io/kube-burner/
- Stars: 802 · Forks: 188
- Language: Go
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/kube-burner-kube-burner

## What the tool does and what it is built on

kube-burner is a Kubernetes performance and scale test orchestration toolset, and the README summarises its most important capabilities in four lines.

It creates, deletes and patches Kubernetes resources at scale. It collects and indexes Prometheus metrics. It takes measurements. And it alerts.

The architecture is deliberately thin. It is a binary application written in Go that makes extensive use of the official Kubernetes client library, client-go. That matters for a tool that creates tens of thousands of objects, because client-go already contains the retry, the rate limiting and the watch handling that a hand-rolled client would get wrong.

The workload is described in YAML rather than in code, and the repository has an examples/workloads directory with example configuration files, an examples/metrics-profiles directory, and an examples/grafana-dashboards directory. So the intended workflow is that you write a workload file, point the tool at it, and read the result from the metrics and the dashboards.

The topic tags name the surrounding ecosystem: client-go, containers, elasticsearch, prometheus, scale, load-testing and performance-testing, and the Elasticsearch tag reflects that Prometheus metrics are indexed into a searchable store for later analysis rather than only left in the metric server.

The licence field on the repository says Apache-2.0, the primary language is Go, and the homepage is the project documentation site.

## Installing the binary and the container image

The quick start is a single script invocation.

```shell
curl -Ls https://raw.githubusercontent.com/kube-burner/kube-burner/refs/heads/main/hack/install.sh | sh
```

The README adds a note about where it lands. The default installation path is ${HOME}/.local/bin/, and you can change it by setting the INSTALL_DIR environment variable before running the script.

The alternative is to take a binary from the releases section of the repository, or to pull the container image from quay, where the repository is kube-burner/kube-burner with its tags listed.

The container route is the one that makes sense for a test that runs inside a cluster or in a CI job, since the tool then runs from a pre-built image rather than needing a matching binary on the machine running the test.

For the version of the tool, the release history shows v2.8.6 from 2026-09-22, v2.8.5 from 2026-09-03 and v2.8.4 from 2026-09-02, and the last push was on 2026-10-01, so the project is actively worked on and shipping patch releases frequently.

## The four build targets and why hardened builds exist

The Makefile offers four build modes, and the differences between them are about distribution and security posture rather than features.

The standard build is `make build`, described as the standard build for development. The optimised release build is `make build-release`. The security-hardened static binary is `make build-hardened`, and `make build-hardened-cgo` is the full security hardening with CGO, which the README says requires glibc.

The README explains the split. The default builds produce static binaries that work across all Linux distributions, and the CGO-hardened build offers additional security features but requires glibc to be present on the target system.

The Makefile shows what the hardening actually consists of. The static hardened build uses buildmode=pie with the netgo, osusergo and static_build tags, and a static external linker flag, while the CGO variant uses external linking with the relro and now linker flags, which is the stack that enables full RELRO. The version, build date and git commit are stamped in through ldflags.

The architecture is derived automatically, mapping aarch64 to arm64 and x86_64 to amd64, and the binary lands in a per-architecture path under bin/.

There is also a container build. The default engine is podman rather than docker, the registry is quay.io, and the manifest is built for amd64, arm64, ppc64le and s390x, which is a wider architecture spread than most Go tools bother with.

## The dependency list as a map of what it can drive

The go.mod is unusually informative about the scope of the tool, and it is worth reading as a feature list.

The Kubernetes libraries are at 0.35.2, covering api, apimachinery and client-go, with kubectl at 0.27.2 and utils. There is a KubeVirt client at 1.8.1 with the API and the containerized data importer API, so the tool can create and drive virtual machines, which is what makes it usable for scale testing a virtualisation layer rather than only pods. There is a KEDA client at 2.16.0, so autoscaling on event sources can be exercised, and the external snapshotter client, so volume snapshots can be part of a workload.

The metrics and analysis side is the prometheus/common library, the montanaflynn/stats package for statistics, gonum for the numerics, and itchyny/gojq for JSON querying, which is how the collected metrics get sliced and summarised.

The CLI and configuration are cobra, sprig for templating, yaml.v3, and gojq. The cloud-bulldozer/go-commons library appears both as a direct dependency and as the home of the version stamping, which tells you this project grew out of the same organisation as Red Hat's cluster burn tooling.

The test dependencies are ginkgo and gomega, so the test suite is written in the ginkgo style rather than as plain pytest-style unit tests, and uuid is used to name the objects the tool creates.

## Where kube-burner is the wrong tool

The first limitation is that it measures the cluster and not your application. It creates pods, virtual machines and other objects, and records what the platform did with them. It will not tell you that a particular request handler is slow, and a green kube-burner run says nothing about whether your service works. If the question is about application performance, this is the wrong instrument.

The second is the destructiveness and the coordination cost. A scale test creates and destroys large numbers of real objects in a real cluster. That means a real cluster, a real cloud provider bill, and a team that agrees on when the test runs and when the cluster is reserved for it. There is no sandbox mode.

The third is that the quality of the results depends on the metrics profile, which you have to write. The examples/metrics-profiles directory exists to be copied, and a profile that does not measure what you care about produces a report that measures nothing. The measurement step is where the expertise has to come from, and it is not in the tool.

The fourth is the dependency on the ecosystem moving. The Kubernetes client libraries are pinned to 0.35.2 while kubectl sits at 0.27.2, a gap that is presumably deliberate, and a cluster running a newer API version than the client knows about will produce behaviour the tool does not model.

The fifth is that a small cluster does not need it. If the question is how a hundred pods behave, a loop with kubectl and a Prometheus query is an afternoon's work and produces a result you understand completely, because you wrote it.

## How it compares with cluster-api-provider and with a plain kubectl loop

The comparison with a hand-written loop is the one that decides whether you need this at all, and the difference in approach is the workload file. A kubectl loop encodes the sequence of commands you want to run, and it is short, transparent and yours. A kube-burner workload file encodes the same intent declaratively, and the tool does the pacing, the collection, the measurement and the alerting around it.

That framing is what makes the tool worth its configuration effort at scale. When the workload is a few hundred pods, a loop is fine. When the workload is tens of thousands of objects across several kinds, with virtual machines, with autoscaling reacting, with metrics to correlate, the orchestration is the hard part and that is what the tool provides.

The comparison with other cluster test tooling is more awkward, because the README does not name competitors and this article should not invent a comparison it cannot support. What can be said from the repository is that the KEDA, KubeVirt and external snapshotter dependencies put kube-burner in the same category as cluster autoscaling and platform conformance suites rather than in the category of HTTP load generators, and that it is the Kubernetes API rather than a network endpoint that it drives.

The third comparison is with a general load-testing tool such as a JMeter style harness. The difference in approach is the object under test. A traffic generator measures an HTTP service, and kube-burner measures the platform's ability to schedule, start, scale and delete workloads. A cluster can pass a traffic test and fail a scale test, and the other way round.

## Licence, project governance and how to run the first test

The licence field on the repository says Apache-2.0, with a LICENSE file at the root, and the README carries a badge for the same licence. The project also has an OpenSSF Best Practices badge and a Go Report Card badge.

The governance files are worth noticing, because they say something about the project's maturity. There is a GOVERNANCE.md, a MAINTAINERS.md, a CONTRIBUTOR_LADDER.md, a ROADMAP.md, a SECURITY.md, a CODE_OF_CONDUCT.md, an ADOPTERS.md and a CITATIONS.md alongside a CITATION.cff. An ADOPTERS file usually lists who is running the tool in production, and a CITATION file exists so that a paper written using the results can cite the tool. The project is not a single maintainer's script.

The README asks contributors to read the Contributing section of the documentation before contributing, and says it explains how to set up an environment and the guidelines for a CI check to be done before committing code. The CI pipeline automatically builds, tests and verifies the project on each commit and pull request. There is a .pre-commit-config.yaml, a .golangci.yml, a .markdownlint.json and a .lycheeignore, so the linting covers Go, Markdown and links.

Four things to do before the first run. Install the binary or pull the image, and remember that the default install path is under your home directory rather than on the system path. Copy an example workload from examples/workloads and read it rather than writing one from scratch, since the file format is the main thing you have to learn. Choose a metrics profile from examples/metrics-profiles, because that is what determines which numbers you end up with. And make sure you have a Prometheus to scrape and somewhere for the metrics to be indexed, since the README lists metric collection and indexing as a core capability rather than an optional extra.

## Conclusion

kube-burner suits a performance engineer who needs a repeatable cluster test rather than a one-off script, especially when the workload involves virtual machines through KubeVirt, autoscaling or an operator such as KEDA that has to be exercised under load. It is the wrong tool for testing application logic, since it measures the cluster rather than your service, and the wrong choice for a small cluster where a hand-written kubectl loop would be quicker. Before running a test, read the example workload files in examples/workloads and pick a metrics profile from examples/metrics-profiles, because the measurements you get are only as good as the profile you choose.

## FAQ

### What is kube-burner?

It is a Kubernetes performance and scale test orchestration toolset, a Go binary that makes extensive use of client-go. It creates, deletes and patches Kubernetes resources at scale, collects and indexes Prometheus metrics, takes measurements and fires alerts.

### How do I install kube-burner?

Run the install script with `curl -Ls https://raw.githubusercontent.com/kube-burner/kube-burner/refs/heads/main/hack/install.sh | sh`. The default installation path is ${HOME}/.local/bin/ and you can change it by setting the INSTALL_DIR environment variable first. Binaries are also in the releases section, and there is a container image on quay.

### What build options does kube-burner offer?

Four: `make build` for a standard development build, `make build-release` for an optimised release build, `make build-hardened` for a security-hardened static binary, and `make build-hardened-cgo` for full hardening with CGO, which requires glibc on the target. The default builds produce static binaries that work across all Linux distributions.

### Can kube-burner test virtual machines and autoscaling?

The dependency list shows a KubeVirt client at 1.8.1 with the containerized data importer API, and a KEDA client at 2.16.0, alongside the Kubernetes client libraries and the external snapshotter client. That is what lets a workload include virtual machines, event-driven autoscaling and volume snapshots rather than only pods.

### Where do I find example workload configurations for kube-burner?

The examples directory in the repository holds three sets: the workloads themselves, metrics profiles, and Grafana dashboards. The README points at the workloads directory for example configuration files.

### What licence is kube-burner released under?

Apache-2.0, with the terms in the LICENSE file at the root of the repository.

## Sources

- [kube-burner/kube-burner on GitHub](https://github.com/kube-burner/kube-burner)
- [License: Apache-2.0](https://github.com/kube-burner/kube-burner/blob/main/LICENSE)
- [Project website](https://kube-burner.github.io/kube-burner/)
- [README](https://github.com/kube-burner/kube-burner/blob/main/README.md)
- [Releases](https://github.com/kube-burner/kube-burner/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kube-burner-kube-burner