Thanos ships as one binary of subcommands, and its default Dockerfile pins an amd64 base digest

Each subcommand does one thing, and the binary is the whole product

The design philosophy is stated in three lines and they are load bearing. Each subcommand should do one thing and do it well, the given example being that thanos query proxies incoming calls to known Store API endpoints and merges the result. Components are written to work together, the example being that blocks are stored in native Prometheus format. And the last line asks for components that are easy to read, write and run, in the spirit of UNIX and Go. The repository layout follows that: cmd/ holds the entry points and pkg/ and internal/ hold the reusable parts, so each capability is a separate program you deploy and scale on its own. The cost of that separation is that you are assembling a system rather than installing an application. There is no single Thanos deployment to turn on, which means every piece of routing, every component address and every failure domain between them is a decision you make and then own.

Sidecar or Receive, and the README does not choose for you

Two deployment shapes are presented. Deployment with Sidecar for Kubernetes puts a component next to each Prometheus so it can serve that Prometheus data through the Store API. Deployment with Receive exists in order to scale out, or to implement with other remote write compatible sources. The distinction that matters is where writes terminate. With the sidecar, Prometheus remains the writer and Thanos reads what it already stored. With Receive, remote write compatible sources can write directly into Thanos, which is how you get sources other than Prometheus in front of the same query layer. The project does not state a rule for choosing between them, so the decision is yours. Treat the architecture choice as the first thing to settle and treat the getting started guide at thanos.io as the place that documents the wiring, since the overview page only names the two shapes.

Object storage is the only optional dependency, and downsampling is the speed lever

The dependency claim is narrow and testable: any object storage is the only, optional dependency. Thanos leverages the Prometheus 2.0 storage format to store historical metric data in object storage while retaining fast query latencies, which is what lets unlimited retention coexist with a live query path. Two consequences follow for whoever runs it. First, HA deduplication and merging of metrics collected from Prometheus HA pairs happens on the fly, so the query layer is doing merge work on every request rather than serving pre-merged data, and the component you scale for read traffic is the one doing that work. Second, downsampling of historical data is offered for massive query speedup, and the README does not describe how raw and downsampled data are retained, so check the documentation before setting a downsampling policy.

The published image pins an amd64 busybox digest unless you run make docker

The Dockerfile names a digest and it is architecture specific:

ARG BASE_DOCKER_SHA="14d68ca3d69fceaa6224250c83d81d935c053fb13594c811038c461194599973"
FROM quay.io/prometheus/busybox@sha256:${BASE_DOCKER_SHA}

The comment above it says the default is the amd64 SHA and that make docker adjusts it for arm64. The Makefile makes that concrete: it reads .busybox-versions, selects the digest for the detected architecture from a list of amd64, arm64 and ppc64le, and prints only support amd64, arm64 or ppc64le arch before failing on anything else. The practical trap is straightforward. Building from this Dockerfile directly on a non-amd64 machine keeps the amd64 default unless you go through make docker. Remember what the image does at runtime: a non root user with uid 1001, no home directory and no password, with the binary copied to /bin/thanos as the entrypoint.

Every commit to main produces a main-<date>-<sha> image

The release model gives you two channels and they are not equivalent. The stated intent is that the main branch should be stable and usable, and every commit to main builds a docker image named main-<date>-<sha> in quay.io/thanos/thanos with a mirror at thanosio/thanos on Docker Hub. Separately, minor releases happen every 6 weeks, with tarballs built for major platforms and release images produced, and the details live in the release process documentation. The listed releases are v0.42.5 from 2026-10-27, v0.42.4 from 2026-07-30 and v0.42.3 from 2026-07-29, while the last push to main is dated 2026-10-30, so main has moved past the newest minor release. That gives you a genuine choice: wait up to six weeks for a tagged minor release, or pin a main-<date>-<sha> image and take on the job of tracking upstream yourself. The dated main tags are per commit builds, not releases, so treat them with the same caution you would give any untagged build.

The gRPC Store API is the contract every provider has to satisfy

The integration point is described as a simple gRPC Store API for unified data access across all metric data, plus easy integration points for custom metric providers. That is the seam to understand, because thanos query merges whatever the Store API endpoints return, and the HA deduplication path is defined in terms of metrics collected from Prometheus HA pairs. So a custom provider is not a plugin in the loose sense: it is a server that speaks Store API, and if it returns series that the deduplication path considers duplicates of one another, the merging behaviour is the project's and not the provider's. The README does not explain how a non Prometheus provider is treated by that path, which is the gap to close before you point custom metrics at a query layer. The upside of the same design is real: any store that can serve Store API becomes a first class part of a global query view, and blocks stay in native Prometheus format so nothing has to be transcoded on the way in.

mixin/runbook.md is excluded from the markdown formatter, so it can drift

Operational content sits in several places rather than in one. mixin/ holds the alerting and recording rule bundle, examples/ contains alerts, dashboards and an interactive directory, tutorials/ holds guided walkthroughs, and the website is built from the repository with netlify.toml. Maintainers are listed in MAINTAINERS.md and adopters are tracked in a data file, website/data/adopters.yml. One detail in the Makefile is worth knowing before you rely on any of it. The formatting target for markdown files collects docs, examples, the mixin directory and the root markdown files, and it explicitly filters mixin/runbook.md out of that set. A file excluded from the formatter is not checked by the same pass as everything else, so the runbook is the page in this repository most able to fall out of step with the components it describes. If you are adopting the mixin, read the runbook against the version you actually run rather than trusting it to match.

Editorial conclusion

Adopt Thanos when you already run several Prometheus servers and need one query surface across them, with object storage as the retention tier, and when you are willing to own the component topology yourself. Do not adopt it to replace Prometheus: the README describes it as sitting on top of existing deployments and levering the Prometheus 2.0 storage format. Before building images, note that the default Dockerfile pins an amd64 busybox digest and that arm64 and ppc64le need make docker. Before choosing an architecture, read the getting started guide, because the README names sidecar and Receive without saying when to prefer one.

Frequently asked questions

Official sources

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