kube-prometheus: a Jsonnet library for end-to-end Kubernetes cluster monitoring

What kube-prometheus solves, and who ends up maintaining it

Running Prometheus on Kubernetes is not one deployment. It is a Prometheus server, an Alertmanager pair, the Prometheus Operator that reconciles ServiceMonitor and PodMonitor objects, node-exporter as a DaemonSet, blackbox-exporter for probe checks, kube-state-metrics for object state, prometheus-adapter to expose resource metrics through the Kubernetes metrics API, and Grafana for the dashboards. Each has its own chart, its own defaults, its own RBAC. kube-prometheus exists so that one Jsonnet library emits all of it with a consistent configuration surface, and so that the alerting rules and dashboards come from the kubernetes-mixin project rather than from whoever set the cluster up.

The audience is platform and infrastructure engineers who own clusters and want the monitoring stack versioned alongside them. The README is explicit that the project is meant to be used as a library, and that creating a modified copy of the repository is not the intent. That framing matters: you are expected to write your own Jsonnet that imports this one, not to fork the manifests directory and edit YAML by hand.

One structural consequence is easy to miss. Because the stack is generated, the checked-in manifests/ directory is a build artifact, produced from example.jsonnet. Editing those files directly works until the next regeneration, and the repository gives no mechanism to merge such edits back.

How the Jsonnet library turns into running Kubernetes objects

The repository is Jsonnet at the top and Go at the edges. example.jsonnet is the entry point that imports the library and produces the full object graph. The Makefile pins the toolchain into tmp/bin: jb for jsonnet-bundler dependency resolution, jsonnet itself, jsonnet-lint, jsonnetfmt, gojsontoyaml to convert the Jsonnet output into YAML, kubeconform for schema validation, and mdox for documentation formatting. jsonnetfile.json and jsonnetfile.lock.json record the imported dependencies, the same way a lockfile does for a package manager.

The data flow is one direction. Jsonnet evaluates to JSON, gojsontoyaml converts that JSON to YAML, and the result lands in manifests/. Kubernetes then reconciles those manifests. The Prometheus Operator takes over from there: it watches the Prometheus, Alertmanager and ServiceMonitor custom resources in the generated output and creates the actual StatefulSets and configuration. This is why the quickstart applies manifests/setup and waits for the CRDs to be Established before applying the rest. The operator has nothing to reconcile until its custom resource definitions exist.

The optional Perses addon follows the same path. The README lists it as an alternative to Grafana and points to docs/customizations/perses.md, which means the dashboard layer is a library choice rather than a hard dependency.

Installing kube-prometheus and applying the checked-in manifests

The prerequisites are a Kubernetes cluster and two kubelet settings. The README states that the kubelet must run with --authentication-token-webhook=true and --authorization-mode=Webhook, or the equivalent kubelet configuration values authentication.webhook.enabled and authorization.mode set to true and Webhook. Without those, Prometheus needs a client certificate, which the README notes gives it full access to the kubelet rather than just the metrics. Check this before anything else; it is the failure that produces confusing scrape errors later.

The fastest path uses the compiled manifests checked into the repository. The README explains that the namespace and custom resources are created first to avoid race conditions:

kubectl apply --server-side -f manifests/setup
kubectl wait \
    --for condition=Established \
    --all CustomResourceDefinition \
    --namespace=monitoring
kubectl apply -f manifests/

Server-side apply is used because some of the custom resource definitions are large. The README notes this feature is generally available since Kubernetes 1.22, and that earlier versions would need kubectl create instead. After the wait completes, the second apply creates the monitoring components in the monitoring namespace.

Removing the stack is a single command, and it is worth knowing before you start:

kubectl delete --ignore-not-found=true -f manifests/ -f manifests/setup

The README also gives a minikube path for local trials. Note that the quickstart applies the un-customized example; the moment you need different retention, storage or scrape targets, you are back in Jsonnet and the manifests directory is no longer your source of truth. Access to the Prometheus, Alertmanager and Grafana UIs is documented separately at prometheus-operator.dev/kube-prometheus/kube/access-ui/, not in the README.

The compatibility table is the real upgrade contract

kube-prometheus tracks Kubernetes releases through branch names, not through a single version that supports everything. The README's table shows release-0.16 supporting Kubernetes 1.32 through 1.34, release-0.17 supporting 1.33 through 1.35, release-0.18 supporting 1.33 through 1.36, and main supporting 1.34 through 1.36. The supported window is four minor versions wide and it shifts with each branch.

The CI note is the part to read carefully: only the last two releases and main are tested regularly. So release-0.16 is still listed as compatible with 1.32 through 1.34, but it is not in the regularly tested set. If you are on an older branch, you are relying on compatibility that the project states but does not continuously verify.

Upgrading therefore has two axes, not one. You move the stack version and you move the Kubernetes version, and the table tells you which combinations are claimed to work. The repository also carries RELEASE.md and CHANGELOG.md at the top level, so the release process and the change history are both in-tree rather than in a wiki. None of this is a substitute for reading the changelog: the README's warning that everything is experimental and may change significantly at any time applies to upgrades as much as to first installs.

What kube-prometheus does not give you

Long-term metric storage is not part of the stack. Prometheus runs with its own local storage, and there is no Thanos or similar component in the components list. If you need retention beyond what a single Prometheus can hold, or a global query view across clusters, you add that yourself. The related searches around Thanos reflect this gap; the repository does not close it.

Logs are also out of scope. The stack collects metrics. There is no Loki deployment in the component list, so a question about whether the stack includes Loki has a short answer: it does not.

High cardinality is the operational failure mode to plan for. The README states the stack is pre-configured to collect metrics from all Kubernetes components. That is the point, and it is also the risk: every component, every node-exporter instance and every kube-state-metrics series is scraped by default. The project ships recording rules from kubernetes-mixin to keep common queries cheap, but the raw series still land in Prometheus, and the default resource requests in the generated manifests are sized for a cluster the maintainers had in mind, not for yours.

Finally, the Grafana instance is a component of the stack, not a general-purpose dashboard service. If your goal is to point Grafana at a Prometheus you already run, kube-prometheus is the wrong layer entirely: it would install a second Prometheus, a second Alertmanager and a second Grafana alongside what you have.

kube-prometheus compared with the Helm chart and with the operator alone

The most common alternative in practice is the kube-prometheus-stack Helm chart, which packages a similar component set as a Helm release. The difference is the configuration model. Helm gives you a values.yaml with a fixed set of knobs and a templating layer; kube-prometheus gives you a Jsonnet library you import and compose. The Jsonnet route can express things a values schema cannot, such as generating ServiceMonitors programmatically or overriding individual mixin rules. The Helm route requires no Jsonnet toolchain and no regeneration step, and the values file is easier for a team that does not want to learn a second language to change a retention setting.

Both sit on top of the Prometheus Operator, which is the other comparison point. The operator by itself is the controller that reconciles Prometheus and Alertmanager custom resources. It ships no dashboards, no alerting rules and no opinion about which exporters to run. kube-prometheus is the opinionated layer above it. If you already have dashboards and rules you are happy with, adopting kube-prometheus means adopting the kubernetes-mixin defaults as well, and reconciling them with what you have.

A third option is to run only what you need. node-exporter and kube-state-metrics are independent deployments; if your problem is node-level visibility and nothing else, the full stack is more surface area than the problem requires.

Licence and the cost of staying current

kube-prometheus is Apache-2.0. The stack it deploys is a collection of separate projects, each with its own licence, and the generated manifests embed images from those projects. Apache-2.0 covers this repository's Jsonnet, scripts and documentation; it does not relicense Prometheus, Grafana, Alertmanager or the exporters. Grafana in particular has its own licence terms, and the optional Perses addon is a separate project under its own terms. That is a factual boundary, not legal advice; if your organisation has licence review, the component list is the thing to hand to it.

The ongoing cost is the regeneration habit. Because the manifests are generated, any change you want to keep belongs in Jsonnet, and the Makefile target that rebuilds them has to run in your pipeline. The repository pins its tooling into tmp/bin, so a CI job needs to fetch jb, jsonnet, jsonnetfmt, jsonnet-lint, gojsontoyaml and kubeconform before it can validate anything. That is a real build step, and it is the price of the library model.

On maintenance: the last push to the default branch was on 2026-09-21, and the most recent release, v0.18.0, was published on 2026-06-18. Releases have landed roughly every three to six months across v0.16.0, v0.17.0 and v0.18.0.

Editorial conclusion

Adopt kube-prometheus if you run your own Kubernetes clusters and want the kubernetes-mixin dashboards and alerting rules wired to the Prometheus Operator without assembling them yourself. Skip it if you only want Grafana dashboards on top of an existing Prometheus, or if you need a supported, versioned product: the README calls everything experimental and may change significantly at any time. Before committing, check that your kubelet runs with --authentication-token-webhook=true and --authorization-mode=Webhook, and confirm which release branch matches your Kubernetes version in the compatibility table, since release-0.18 supports 1.33 through 1.36 and main only 1.34 and later.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. prometheus-operator/kube-prometheus on GitHub
4. README
5. Releases