kube-thanos, the Jsonnet library that turns Thanos into Kubernetes manifests

A library first, generated YAML second

kube-thanos describes itself as a repository collecting Kubernetes manifests combined with documentation and scripts to provide an easy to deploy experience for Thanos on Kubernetes.

The important detail is in the next line. The content of the project is written in Jsonnet, and the README says the project could both be described as a package as well as a library. That is a deliberate framing, because a Jsonnet library is consumed rather than copied, and the manifests directory is the compiled output of that library rather than the source of truth.

The quickstart section spells out the intent: this project is intended to be used as a library, meaning the intent is not for you to create your own modified copy of the repository. For a quickstart though, a compiled version of the Kubernetes manifests generated with the library, specifically with example.jsonnet, is checked into the repository so you can try the content out quickly. To try the stack unmodified, you create the stack with make deploy, and to tear it down you run make teardown.

So there are two usage models. The quick one is make deploy against the checked-in manifests. The real one is to add the library to your own Jsonnet project and compile your own manifests. Most teams that end up depending on this will take the second path, and the README is careful to point out that even then you do not need to copy the whole repository, only a few select files.

The Jsonnet entry point, and what the components look like

The example file is the clearest statement of the API, because it shows the four Thanos components being composed from a shared config.

The file opens by importing the library and then defines a common config that the components share:

local t = import 'kube-thanos/thanos.libsonnet';

local commonConfig = {
  config+:: {
    local cfg = self,
    namespace: 'thanos',
    version: 'v0.31.0',
    image: 'quay.io/thanos/thanos:' + cfg.version,
    imagePullPolicy: 'IfNotPresent',

From there each component takes the shared config and adds its own settings. The receive ingestor is built with t.receiveIngestor, the receive router with t.receiveRouter, the store with t.store, and the query component with t.query, and the query component is given the store endpoints and the ingestor store endpoints as its stores.

The final expression is what makes the file work as a manifest generator. Each component's resources are prefixed with the component name, so the output object keys are names like thanos-store, thanos-query, thanos-receive-router and thanos-receive-ingestor, and the hashring-specific ingestor resources get a name that includes the hashring.

Two things about the design are worth noting. The object storage configuration can be set to null, which the example uses to disable shipping to object storage for the purposes of the example, and the serviceMonitor option is set per component, which is how the Prometheus operator ServiceMonitor resources are opted into.

Consuming the library with jsonnet-bundler

The installing section is the one that matters for anyone who does not want to fork the repository.

The content consists of a set of Jsonnet files making up a library to be consumed. You install it in your own project with jsonnet-bundler, the Jsonnet package manager, and the sequence is:

$ mkdir my-kube-thanos; cd my-kube-thanos
$ jb init  # Creates the initial/empty `jsonnetfile.json`
# Install the kube-thanos dependency
$ jb install github.com/thanos-io/kube-thanos/jsonnet/kube-thanos@main # Creates `vendor/` & `jsonnetfile.lock.json`, and fills in `jsonnetfile.json`

The README notes that jb can be installed with go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb, and that installing a given version of the library uses the same jb install command with a version ref instead of main. Updating the dependency later is a matter of running jb update.

Compiling is a single script invocation, and the README gives the example as ./build.sh example.jsonnet. Before compiling you need the gojsontoyaml tool, installed with go get github.com/brancz/gojsontoyaml. The README also points out that the script uses the vendor/ directory to render all manifests in a json structure of {filename: manifest-content}, and that the script runs the jsonnet code, reads each key of the generated json, uses that key as the file name, writes the value of that key to that file, and converts each json manifest to yaml.

For output as json rather than yaml, the README says you can skip the pipe and everything after it, which is a small thing that saves installing a second tool if your pipeline prefers json.

The build script and what the Makefile does around it

The build script is short and its structure is worth understanding, because it is what turns Jsonnet into Kubernetes YAML.

JSONNET=${JSONNET:-jsonnet}
GOJSONTOYAML=${GOJSONTOYAML:-gojsontoyaml}

# Make sure to start with a clean 'manifests' dir
rm -rf manifests
mkdir manifests

The tool names are overridable through environment variables, which is what lets the Makefile inject its own pinned versions. The script then runs jsonnet with -J vendor and -m manifests, and pipes the output through a shell loop that converts each generated JSON file to YAML with gojsontoyaml and removes the intermediate file.

The same pattern runs three times over, for the main manifests, for the examples/all/manifests directory which generates all components and is mostly used for testing, and for examples/development-minio, which is the MinIO-backed example used locally.

The Makefile wraps that. The default target is fmt generate validate. The generate target depends on the manifests, which in turn depend on jsonnet, gojsontoyaml, the vendor directory and the example files, and it removes and recreates the manifests directory before running build.sh. There are separate fmt and lint targets using jsonnet-fmt and jsonnet-lint, a vendor target that runs jb install, and the deploy and teardown targets that talk to kubectl. The Makefile pins the Kubernetes version to 1.27.0 and the prometheus-operator version to 0.46.0, which is a reminder that the operator CRDs this project depends on are version-coupled to it.

Deploying to a kind cluster, and the limits of the project

The prerequisites are minimal. To try out the stack, you start kind with the command kind create cluster, and the rest of the quickstart is make deploy and make teardown.

The deploy target creates the thanos and minio namespaces, applies the prometheus-operator ServiceMonitor CRD directly from the operator repository at the pinned version, then creates the development-minio example and finally the manifests themselves. To tear down, you delete the development-minio resources and the manifests, and the README explains that the previous steps have created a bunch of manifest files in the manifest/ folder which you install with kubectl apply -f manifests/. After that you check the monitoring namespace, or the namespace you set in the namespace field, and make sure the pods are running.

The limitation the project states about itself is at the top of the README and it is not softened: everything is experimental and may change significantly at any time. That matters more here than in a typical manifest repository, because the consumers of this library are the pipelines of other teams, and a library whose contents can shift without notice is a dependency you have to pin and re-check.

The release record shows the same tension. The listed versions are v0.23.0 from October 2021, v0.26.0 from June 2022 and v0.29.0 from November 2022, while the example configuration in the README pins the Thanos version to v0.31.0. In other words, the tagged library releases trail the manifests and examples, so the main branch is where the current content lives, which is also what the jb install command in the documentation points at.

Editorial conclusion

Adopt kube-thanos if you run Thanos on Kubernetes and want your manifests generated from Jsonnet rather than maintained as YAML, since the library gives you the store, query, receive router and receive ingestor components with configurable replicas, object storage and service monitor settings. Do not adopt it if you want a supported product, because the README says everything is experimental and may change significantly at any time, and the published version tags stop in 2022 while the manifests and the example track newer releases. Before you commit, check the jsonnet library under jsonnet/kube-thanos and the version field in example.jsonnet, decide whether to consume the library through jsonnet-bundler rather than forking the repository, and note the maintenance picture, with the last push on 2026-06-23.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. thanos-io/kube-thanos on GitHub