kube-prometheus: jsonnet as a library, with a compatibility matrix per release branch

It is jsonnet first, and the checked-in manifests are a sample

The repository states its nature in one line: the content of this project is written in jsonnet, and this project could both be described as a package as well as a library.

Then the intent, which is the sentence to hold on to: this project is intended to be used as a library, that is, the intent is not for you to create your own modified copy of this repository.

So the compiled output is a convenience, not the product. The README says a compiled version of the Kubernetes manifests generated with this library, specifically with `example.jsonnet`, is checked into the repository in order to try the content out quickly.

That distinction explains the whole layout. `jsonnet/` holds the library, `example.jsonnet` is the entry point that produces `manifests/`, and the `manifests/` directory is regenerated output. If you edit manifests directly, your next build discards the change.

It also explains the sibling repository it points at for dashboards and alerts: many of the useful ones come from the kubernetes-mixin project, which similarly provides composable jsonnet as a library for users to customise.

Eight components, plus an optional dashboard replacement

The component list is the stack in eight entries.

The Prometheus Operator, then highly available Prometheus, then highly available Alertmanager, then Prometheus node-exporter and Prometheus blackbox-exporter, then the Prometheus Adapter for Kubernetes Metrics APIs, then kube-state-metrics, and Grafana.

Two of those entries carry an adjective that matters. Prometheus and Alertmanager are both described as highly available.

Then there is one optional addon. Perses is described as a CNCF Sandbox alternative to Grafana, with a documentation page on using Perses instead of Grafana.

That is a real architectural choice rather than a cosmetic one, because the dashboards in this stack are Grafana dashboards.

The stack is meant for cluster monitoring, so it comes pre-configured to collect metrics from all Kubernetes components, and it delivers a default set of dashboards and alerting rules on top.

The kubelet must have webhook auth, or Prometheus needs a client certificate

The prerequisites section is short and then specific, and the specificity is the point.

You need a Kubernetes cluster, that is all. By default it is assumed the kubelet uses token authentication and authorization, because otherwise Prometheus needs a client certificate, which gives it full access to the kubelet rather than just the metrics. Token authentication and authorization allow more fine grained and easier access control.

So there are two flags the kubelet configuration must contain. `--authentication-token-webhook=true` enables a ServiceAccount token being used to authenticate against the kubelet, and the same can be set through the kubelet configuration value `authentication.webhook.enabled` set to `true`. And `--authorization-mode=Webhook` enables the kubelet performing an RBAC request with the API to decide whether the requesting entity, Prometheus in this case, may access a resource, specifically the `/metrics` endpoint, and the same can be set through `authorization.mode` set to `Webhook`.

Read as a security decision rather than a setup step: the default is scoped access through RBAC, and the alternative the README warns about is a certificate that can do anything to the node.

The adapter is deployed whether or not it can work

One sentence in the prerequisites section describes a failure mode you will otherwise discover later.

This stack provides resource metrics by deploying the Prometheus Adapter. This adapter is an Extension API Server, and Kubernetes needs to have this feature enabled, otherwise the adapter has no effect, but is still deployed.

So the resources appear in your cluster, the pods run, and nothing happens. That is a specific and unpleasant kind of partial success, and the README flags it in advance.

The fix is on the Kubernetes side rather than in this project: Kubernetes needs the extension API server feature enabled for the adapter to have any effect.

The example files include an `etcd.jsonnet` and client certificates, `etcd-client-ca.crt`, `etcd-client.crt` and `etcd-client.key`, alongside `etcd-skip-verify.jsonnet`, which suggests the examples cover authenticating to an external or secured etcd as well.

The compatibility table is a window, not a claim

The compatibility section lists what is tested against what, and the surrounding prose is careful.

The versions supported and work as we test against these versions in their respective branches, with a note that other versions might work, and a second note that in CI only the last two releases and the main branch are tested on a regular basis.

Then the matrix, five Kubernetes columns from 1.33 to 1.37 against four rows. `release-0.17` covers 1.33, 1.34 and 1.35. `release-0.18` covers 1.33 through 1.36. `release-0.19` covers 1.35, 1.36 and 1.37. And `main` covers 1.35, 1.36 and 1.37.

Read the diagonals. Newer branches drop older Kubernetes versions and add newer ones, so choosing a branch is choosing which Kubernetes versions you are willing to run and which you are willing to upgrade from. `release-0.17` will not take 1.36, and `main` will not take 1.33.

The releases are v0.19.0 on 2026-09-24, v0.18.0 on 2026-06-18 and v0.17.0 on 2026-03-19, with the last push on 2026-11-02, so the branch you pin and the Kubernetes you run move on a quarterly rhythm.

Setup is applied twice, and setup goes first on purpose

The quickstart applies the namespace and CustomResourceDefinitions before the monitoring components, and gives the reason.

We create the namespace and CustomResourceDefinitions first to avoid race conditions when deploying the monitoring components.

The commands:

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

The server-side apply is not incidental. The note says that due to some CRD size they are using the kubectl server-side apply feature, generally available since Kubernetes 1.22, and that on previous Kubernetes versions it may not be available, in which case you would need `kubectl create` instead.

So on a cluster older than 1.22 the quickstart does not apply as written, and the README tells you which command to use instead.

There is a one-line alternative, `kubectl apply --server-side -f manifests/setup -f manifests`, and the README is candid that it may be necessary to run it multiple times for all components to be created successfully. Tearing down is one command with `--ignore-not-found=true` on both directories.

Seven tools in tmp/bin, and a Go module for the tests

The Makefile puts every tool in one directory, `tmp/bin`, which is the first thing to know about the build.

The tools are mdox, jb, gojsontoyaml, jsonnet, jsonnet-lint, jsonnetfmt and kubeconform, plus kubescape from `~/.kubescape/bin` rather than the local one.

So the toolchain is jsonnet and three checkers that validate its output: a linter, a formatter configured with a fixed style (`-n 2 --max-blank-lines 2 --string-style s --comment-style s`), and kubeconform for schema validation. Kubescape has a threshold of 1, which reads as a fail-on-any-finding setting for a security scanner.

The Makefile also generates its own shell completion from the target list, with separate bash and zsh targets.

Then the surprise in a jsonnet project: `go.mod` declares Go 1.26.0 and requires k8s.io/api and k8s.io/apimachinery at v0.37.2 and k8s.io/client-go at v0.37.1 alongside the Prometheus client library.

The root also has `jsonnetfile.json` and `jsonnetfile.lock.json` for the jsonnet dependencies, `kustomization.yaml`, `example.jsonnet`, `kubescape-exceptions.json` for the scanner, `.mdox.validate.yaml` for documentation link checking, and a `RELEASE.md` for the release process.

Editorial conclusion

kube-prometheus suits a cluster team that wants a complete monitoring stack with dashboards and alerting rules already written, and that is prepared to consume jsonnet rather than edit YAML. It does not suit you if you want a Helm chart, since the project is jsonnet and says the intent is that you do not maintain your own modified copy, and it does not suit you if your cluster version sits outside your branch's row of the compatibility table. Verify three things before deploying: which Kubernetes versions your branch supports and that your version is in it, that your kubelet has token webhook authentication and Webhook authorization enabled, which the stack assumes, and that the Prometheus Adapter extension API server feature is enabled, since without it the adapter has no effect but is still deployed.

Frequently asked questions

Official sources

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