Deployment

How Prometheus is built, packaged, and shipped. Operator-side deployment guidance is in documentation/examples/ and the user docs at https://prometheus.io/docs/; this page covers what the repository itself does.

Build artefacts

The release pipeline produces:

• Binaries: prometheus and promtool for linux/{amd64,arm64,386,armv7,armv6,ppc64le,s390x,riscv64}, darwin/{amd64,arm64}, windows/{amd64,386}, freebsd/{amd64,386}, openbsd/{amd64,386}, netbsd/{amd64,386}, and dragonfly/amd64. See .promu.yml for the matrix.
• Tarballs: one per OS/arch, named prometheus-<version>.<os>-<arch>.tar.gz, plus a separate prometheus-web-ui-<version>.tar.gz containing prebuilt UI assets so users can build slim binaries from source.
• Docker images: two variants:
  • prom/prometheus:<version>-busybox — the long-standing busybox-based image, default tag :<version>.
  • prom/prometheus:<version>-distroless — newer (3.10) distroless variant, UID/GID 65532, no VOLUME declaration.
• Container repos: quay.io/prometheus/prometheus and docker.io/prom/prometheus.

The matching prom/promtool and quay.io/prometheus/promtool images carry the CLI.

Build pipeline

The release pipeline runs in CI (.github/workflows/ci.yml) on tags v*. Highlights:

1. make assets — build the UI.
2. make assets-tarball — package prometheus-web-ui-<version>.tar.gz.
3. make npm_licenses — bundle license files for npm dependencies.
4. make assets-compress — gzip the embedded UI assets.
5. promu crossbuild — produce per-platform binaries.
6. make docker — build container images.
7. Publish artefacts to GitHub Releases, Docker Hub, and Quay.

The prometheus/promu build helper is what produces reproducible binaries; flags and tags are set in .promu.yml.

Docker

Two Dockerfiles:

• Dockerfile — the busybox-based image. Default prom/prometheus:latest.
• Dockerfile.distroless — distroless variant. prom/prometheus:latest-distroless.

The 3.10 release introduced the distroless variant alongside the busybox image. Migrating named volumes from busybox to distroless requires chown -R 65532:65532 /prometheus on the volume — the busybox image used nobody/nogroup, the distroless one uses nonroot (65532:65532).

docker run --rm -v prometheus-data:/prometheus alpine \
    chown -R 65532:65532 /prometheus
docker run -v prometheus-data:/prometheus prom/prometheus:latest-distroless

Platform-specific build tags

.promu.yml sets these tags by default in release builds:

• netgo — pure-Go DNS resolver. Avoids glibc nss linkage in the binary.
• osusergo — pure-Go user/group lookup.
• builtinassets — embed UI assets into the binary.

Users building from source can override these. The README's "Service discovery plugins" section shows how to slim binaries with remove_all_sd plus enable_<name>_sd.

Release cadence

A minor release every six weeks; coordinated by the rotating release-coordinator role (see MAINTAINERS.md::v3 release coordinators). Process documented in RELEASE.md. A typical cycle:

1. Cut RC (week 5 of cycle): tag v3.x.0-rc.0, freeze the release-3.x branch.
2. Bake-off: 1–2 weeks of testing, with bug-fix commits cherry-picked to the release branch.
3. Cut final: tag v3.x.0, build artefacts, publish.
4. Patch releases: cherry-picks for security and severe bugs become v3.x.y over the release-branch's lifetime.

Each user-visible major has a paired internal v0.3xx.y tag for go get users — the README explains the mapping.

Configuration files in the repo

• Dockerfile, Dockerfile.distroless — image builds.
• .promu.yml — promu build matrix and flags.
• Makefile, Makefile.common — build targets (the latter is shared across prometheus/* repos).
• documentation/examples/prometheus.yml — example config used by make build's smoke test.

Health checks

For container orchestrators:

• Liveness: GET /-/healthy — returns 200 while the process is responsive.
• Readiness: GET /-/ready — returns 200 only after WAL replay completes. Returns the X-Prometheus-Stopping header during graceful shutdown so load balancers can drain (3.10 fix #17795).

Resource sizing

Operator guidance lives in documentation/storage.md and the user docs. Rule of thumb:

• Memory: ~1.5 GB per million active series for a 24h retention.
• Disk: ~1.5 bytes per sample, post-compaction.
• CPU: scales with scrape rate and PromQL query complexity.

Federation, HA, and replication

Prometheus has no built-in clustering. Common patterns:

• HA pairs — two identical Prometheus instances scraping the same targets, ideally with external_labels.replica to differentiate.
• Federation — central Prometheus federates aggregated series from leaf instances via /federate.
• Remote storage — ship samples to Mimir / Cortex / Thanos / etc. via remote write for long-term storage and global views.

Monitoring Prometheus

Prometheus exposes its self-metrics on /metrics. The Jsonnet "mixin" under documentation/prometheus-mixin/ is the canonical alerts + dashboards bundle for self-monitoring; it is published as a prometheus-mixin tarball.

See How to monitor for what to watch and Security for hardening.