Cortex: multi-tenant long-term Prometheus storage, and what it costs you

The problem Cortex exists to solve, and who it is actually for

A single Prometheus server holds its data on local disk and answers queries from that same process. That works until you need retention measured in years, or until several teams want to send metrics into one place without seeing each other's data. Cortex is aimed at exactly those two pressures. The README describes it as a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus and OpenTelemetry Metrics, and lists four features: it can run across multiple machines in a cluster, replicate data between machines, isolate data and queries from multiple independent Prometheus sources in a single cluster, and store metric data long term in S3, GCS, Swift or Microsoft Azure.

That audience is narrow. This is not a drop-in replacement for a Prometheus binary on a VM. It is a distributed system that you deploy, size, and operate, and the README points at a separate documentation site for Getting Started, Architecture, Configuration and Guides rather than explaining deployment in the repository itself. If your problem is one team, one cluster, and a few months of retention, Cortex is more machinery than the problem requires.

How the architecture splits ingestion, storage and query

The README's feature list is short, but the repository layout and the documentation links tell you the shape of the system. There is a cmd/ directory, a pkg/ directory, a vendor/ directory, and a separate integration/ directory, which is the layout of a Go service built as one binary that can run in several roles. The README links an Architecture Overview page, so the intended reading order is the documentation site, not the source tree.

The important consequence of that design is that ingestion and querying are separate concerns. Prometheus sends metrics to Cortex, and Cortex writes them to object storage rather than to a local disk it owns. Queries then read back from that storage layer. Because the same system serves multiple tenants, isolation is a property of the deployment, not something you configure per Prometheus. The dependencies in go.mod are consistent with this: AWS SDK v2 for S3, a MinIO client, Redis clients, Consul, memberlist, and a large set of Prometheus-derived packages. Object storage, a key-value store for the index, and a gossip or Consul-based ring are all part of the picture. The README does not spell out which components are mandatory for a minimal deployment, so treat the Configuration page as the source of truth before you plan capacity.

Installing Cortex and sending it a first metric

The README does not contain install commands. It links to a Getting Started page at cortexmetrics.io/docs/getting-started/, and the repository supplies a Makefile for building images rather than for installing a running system. The Makefile sets IMAGE_PREFIX to quay.io/cortexproject/ by default and builds one image per directory containing a Dockerfile, so the published images live under that prefix.

What the Makefile does show is the build convention. The target below is the repository's own pattern: every directory with a Dockerfile builds an image named after that directory, tagged with the image prefix plus the computed image tag.

IMAGE_PREFIX ?= quay.io/cortexproject/
IMAGE_TAG ?= $(if $(GIT_TAG),$(GIT_TAG),$(shell ./tools/image-tag))

If you build from source instead, the module path and Go version are declared at the top of go.mod, so a checkout builds with the Go toolchain rather than with a language-agnostic installer.

go 1.27.0
module github.com/cortexproject/cortex

The repository also ships a packaging/ directory and a schemas/ directory, but the README does not describe what either contains, so do not assume an OS package or a Helm chart from those names alone. For the actual first run, including which config keys are required and which storage backend to point at, the Getting Started and Configuration pages are the only documented path. Once Cortex is accepting writes, the client side is ordinary Prometheus remote write configuration, which the README does not reproduce.

Where Cortex is the wrong choice

The clearest limitation is operational. Nothing in the README describes a single-node mode, a bundled storage backend, or a default configuration that runs without external services. The feature list assumes a cluster and assumes object storage. If you cannot run object storage, or you do not want to operate a key-value store and a ring, Cortex is the wrong tool regardless of how well it scales.

A second limitation is documentation placement. The README is a landing page: it links to Architecture, Configuration, Guides, Security and Contributing, and it spends more space on community calls and a decade of conference talks than on how to run the thing. That is a signal about where the knowledge lives and who is expected to consume it. There is no rollback procedure in the README, no upgrade path between releases, and no statement about what happens to in-flight writes during a version change. For a storage system that is a real gap, and it means your upgrade process has to come from somewhere else.

Finally, multi-tenancy is a design property, not a switch. If your requirement is one tenant with strict network isolation, the tenant isolation machinery is overhead you are paying for and not using.

Cortex compared with running Thanos on top of Prometheus

The two projects have a shared history, and the README is candid about it: one of the listed talks is titled "Sharing is Caring: Leveraging Open Source to Improve Cortex & Thanos," and a 2020 KubeCon talk is titled "Scaling Prometheus: How We Got Some Thanos Into Cortex." They are not independent designs that happen to overlap.

The difference in approach is where the writing happens. In a Thanos-style setup, Prometheus itself uploads its blocks to object storage and a separate query layer fans out across those stores; Prometheus remains the writer and the source of truth for its own data. In Cortex, Prometheus does not keep the long-term copy. It sends metrics to Cortex, and Cortex owns the write path, the index, and the retention. That is why Cortex can offer multi-tenancy as a first-class feature and why it needs a key-value store and a ring to do it. The trade is that you gain a shared, isolated, queryable store and you give up the property that each Prometheus is independently self-sufficient.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the most recent push recorded for it is 2026-09-22. Releases are frequent and include release candidates: v1.22.0-rc.1 on 2026-09-21, v1.22.0-rc.0 on 2026-09-12, and v1.21.1 on 2026-06-05. The presence of release candidates ahead of a stable tag means you should decide deliberately whether you track rc builds or wait for the stable tag; the repository does not tell you which to prefer.

There is a RELEASE.md and a CHANGELOG.md at the top level, so the project documents its own release process and its changes. Neither is reproduced in the README. For upgrade cost, the honest position is that the README does not document rollback, does not describe a migration path between major versions, and does not state a support window. Budget time to read CHANGELOG.md before every upgrade rather than assuming compatibility.

The licence is Apache-2.0, which is a permissive licence with an explicit patent grant and a requirement to preserve notices. That is the whole of what this material supports; whether your organisation's policies accept it is a question for your own legal review, not something the repository answers. Note also that the repository vendors its dependencies and ships a VENDORED_CODE.md, so the licence obligations of the vendored tree are worth checking separately from the top-level LICENSE.

Editorial conclusion

Cortex fits platform teams that already run Kubernetes and object storage and need one Prometheus-compatible endpoint shared by many independent tenants. It does not fit a single team that just wants one Prometheus to keep its own data for a year; a single-node store is far less operational surface. Before adopting it, read the Getting Started and Configuration pages at cortexmetrics.io and decide on the storage backend, because the README names S3, GCS, Swift and Microsoft Azure but does not document rollback or an upgrade path between releases.

Frequently asked questions

Official sources

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