kubernetes-mixin: Prometheus alerts and Grafana dashboards for Kubernetes, generated from Jsonnet

The problem kubernetes-mixin solves: alert and dashboard definitions that rot in a UI

Kubernetes exposes hundreds of metrics, and the useful alerts on top of them are not obvious. Most teams end up clicking dashboards together in Grafana and writing PromQL alerts by hand, then discovering months later that a metric was renamed upstream and the alert has been silent ever since. kubernetes-mixin takes the opposite approach: the alerts, recording rules and dashboards live as Jsonnet source in a repository, and a build step renders them into YAML and dashboard JSON you load into Prometheus and Grafana.

The audience is specific. You need a Prometheus-compatible monitoring stack, Grafana, and enough Jsonnet fluency to import a library and override a few fields. The README describes the project plainly as "a set of Grafana dashboards and Prometheus alerts for Kubernetes", so this is not an operator, not an agent, and not a Helm chart. It is a library of definitions plus the tooling to compile them.

How the Jsonnet source renders into rules and dashboards

The repository layout tells most of the story. The dashboards/ directory holds the dashboard sources, alerts/ and rules/ hold alerting and recording rules, lib/ holds shared helpers, and config.libsonnet and mixin.libsonnet are the entry points you import. jsonnetfile.json and jsonnetfile.lock.json pin the external Jsonnet dependencies, which is why jb (jsonnet-bundler) appears in the Makefile tooling alongside jsonnet, jsonnetfmt, jsonnet-lint, promtool and pint.

The Makefile defines the pipeline. SRC_DIR defaults to dashboards and OUT_DIR defaults to dashboards_out, and the default target runs fmt, generate, lint and test in that order. Formatting uses jsonnetfmt with fixed arguments, linting covers Jsonnet and the generated Prometheus rules, and the test target runs promtool, which means the alert expressions are evaluated as unit tests rather than trusted by inspection. That test step is the part worth copying into your own pipeline: it is what stops a rule that references a renamed metric from shipping quietly.

The generated output is what you actually deploy. The README points at the releases page for "changelogs and generated dashboards, alerts, and recording rules", so you can either render them yourself from a pinned tag or take the artifacts attached to a release.

Installing kubernetes-mixin and rendering your first rules

There is no package to install and no server to run. You clone the repository, let the Makefile download its pinned tools into tmp/bin, and render. The README gives this as the way to set up a local development environment, which creates a kind cluster:

make dev

The README states you should see a banner ending with the note that Grafana is available at http://localhost:3000, that data appears after a few minutes, and that alert and recording rules require `make dev-reload`. Dashboards refresh every 10s, and `make generate` followed by a browser refresh picks up dashboard changes. To tear the cluster down again:

make dev-down

For a real deployment you do not want the kind cluster. You want the generated artifacts, and the Makefile exposes that as the generate target:

make generate

After that, dashboards_out contains the rendered dashboard JSON to import into Grafana, and the generated rule files are what you point Prometheus at. The README does not document a rollback procedure for a bad rule set, so treat the generated files as you would any other monitoring config and keep the previous render.

Metric requirements and the compatibility table you should read twice

This is where kubernetes-mixin punishes casual upgrades. Mixin versions do not map one-to-one to Kubernetes versions, and the README says so directly: compatibility depends on the metrics and labels exposed by Kubernetes and by exporters such as kube-state-metrics, node-exporter and windows-exporter, and on which metrics your stack actually collects.

The concrete breakages are documented. The API-server rules use apiserver_request_sli_duration_seconds, which Kubernetes introduced in v1.26, so every tagged release from version-0.13.0 through version-1.5.6 needs Kubernetes v1.26 or later. The scheduler rules moved twice. Older rules used scheduler_e2e_scheduling_duration_seconds and scheduler_binding_duration_seconds, both of which Kubernetes removed. In version-1.3.0 the e2e metric was replaced with scheduler_scheduling_attempt_duration_seconds, but releases before version-1.4.0 still use the removed binding metric and can show missing scheduler data even when the API-server requirement is satisfied. version-1.4.0 replaced it with scheduler_pod_scheduling_sli_duration_seconds, which Kubernetes introduced in v1.29, and version-1.4.0 through version-1.5.6 plus master all require v1.29 or later for scheduler metrics.

The README is honest about the limits of its own guidance: the tables document known metric requirements and historical compatibility, and do not guarantee that every dashboard and rule works with every later Kubernetes version. The CI workflow checks generation, formatting, linting and rule tests, but does not test a matrix of Kubernetes versions. Automated metric compatibility checks are still an open issue, tracked as #1249. If you run a Kubernetes version your exporter set does not match, you find out from empty panels.

When kubernetes-mixin is the wrong tool

If you do not already run Jsonnet, this project asks you to adopt a build toolchain before you get a single alert. The Makefile pulls jsonnet, jb, jsonnetfmt, jsonnet-lint, promtool, markdownfmt, vale and pint into tmp/bin; that is a lot of moving parts for a team that just wants a dashboard. A team with three clusters and one part-time SRE will get more value from a curated dashboard someone else maintains than from a Jsonnet library they must upgrade on a schedule.

The second mismatch is expecting a chart. The RELATED SEARCHES data shows people looking for a "kubernetes mixin helm chart", and the repository does not contain one. The top-level entries are a Makefile, Jsonnet files, alerts/, dashboards/, rules/ and tests/. If your delivery model is Helm, you either wrap the generated artifacts yourself or pick a project that ships that packaging.

The third is version drift. Because the rules depend on specific metric names, an old mixin against a new cluster fails silently rather than loudly. The README's advice is to pin a release tag and review its changelog when upgrading, and to check that your monitoring stack collects the metrics and labels the dashboards and rules use. Kubernetes version alone does not establish compatibility with your exporter versions or scrape configuration.

Alternatives and how their approach differs

The closest alternative in the search data is Grafana's own mixin ecosystem. Grafana publishes a set of mixins for its own components, such as the Mimir mixin, and those follow the same Jsonnet-plus-Makefile pattern. The difference is scope: Grafana's mixins describe Grafana's products, while kubernetes-mixin describes Kubernetes itself and the exporters around it. If you run Loki or Mimir alongside Kubernetes, you end up importing more than one mixin and rendering them together, which is exactly the workflow jsonnet-bundler exists to support.

A second option is a prebuilt dashboard set distributed as JSON or as a chart, where you import files and edit them in the Grafana UI. That trades the build step for divergence: your edits live in Grafana's database, not in Git, and the next upstream change has to be merged by hand. kubernetes-mixin's whole reason to exist is to avoid that trade, and the cost of avoiding it is the Jsonnet toolchain.

The third is writing the rules yourself. That is defensible for a small number of alerts you fully understand, and it removes the upgrade treadmill. It also means rediscovering the metric renames documented in this repository's README on your own.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-22, four days before this writing. Releases are tagged as version-MAJOR.MINOR.PATCH, with changelogs starting at version-0.13.0; the most recent tags are version-1.5.6 on 2026-07-08, version-1.5.5 on 2026-06-03 and version-1.5.4 on 2026-05-28. The master branch holds development changes between releases, so pinning a tag is the sane default.

Upgrade cost is the real maintenance burden, and it is not the code. Each release can move a metric requirement, as version-1.3.0 and version-1.4.0 did for the scheduler. Upgrading means reading the changelog, checking your Kubernetes version against the compatibility table, and confirming your exporters still emit the named metrics. The repository also carries a runbook.md, which is where the alert annotations point when a rule fires.

The project was transferred from kubernetes-monitoring/kubernetes-mixin to kubernetes-sigs/kubernetes-mixin. The README asks that new mixins reference github.com/kubernetes-sigs/kubernetes-mixin going forward, and notes that existing references to the old path continue to work through GitHub's transfer redirects. The licence is Apache-2.0, which permits commercial use and modification and requires that you keep the licence and notice files; the source files carry SPDX headers to that effect. This is a description of the licence text, not legal advice.

What to verify before you commit to it

Check three things in order. First, your Kubernetes version against the table: v1.26 or later for the API-server SLI metrics, and v1.29 or later for scheduler metrics if you are on version-1.4.0 or later. Second, that your stack collects the metrics and labels the specific dashboards and rules you plan to deploy use, since the README states that Kubernetes version alone does not establish compatibility with your exporter versions or scrape configuration. Third, that you can run jsonnet and jb in CI, because the value of this project comes from generating the artifacts reproducibly rather than from a one-time render.

If all three hold, the payoff is a monitoring layer you can diff and review like any other code, with promtool tests guarding the alert expressions. If any of them fails, the generated JSON is still usable, but you have taken on the upgrade treadmill without the automation that makes it bearable.

Editorial conclusion

Adopt kubernetes-mixin if you run Prometheus and Grafana against Kubernetes and want the alert and dashboard definitions in version control rather than in a UI. Do not adopt it if you cannot run jsonnet and jb in CI, or if you expect a Helm chart, because the repository ships a Makefile and Jsonnet, not a chart. Before rolling it out, check that your Kubernetes version is v1.26 or later for the API-server rules and v1.29 or later for the scheduler rules, and confirm your stack collects the metrics those rules name.

Frequently asked questions

Official sources

1. Issues
2. kubernetes-sigs/kubernetes-mixin on GitHub
3. License: Apache-2.0
4. README
5. Releases