prometheus-adapter: exposing Prometheus metrics to Kubernetes autoscaling

Custom metrics API for the Horizontal Pod Autoscaler

Kubernetes' autoscaling/v2 HorizontalPodAutoscaler can scale on custom metrics, but only when something exposes those metrics through the Kubernetes Metrics API. prometheus-adapter fills that role for clusters that already run Prometheus. It registers as an API server extension and serves Prometheus query results through the custom.metrics.k8s.io endpoint.

The project implements three Kubernetes metrics APIs: Custom, Resource and External. The Custom Metrics API covers per-resource metrics like HTTP requests per pod. The Resource API allows the adapter to replace the metrics server for CPU and memory when the cluster already runs Prometheus and collects those metrics. These are distinct endpoints, and which one a given configuration uses depends on how the YAML config file describes the metrics.

Compatibility starts at Kubernetes 1.6.

The config file controls both metric discovery and API presentation

Prometheus metrics do not automatically become Kubernetes custom metrics. The adapter consults a YAML configuration file, specified with `--config=<yaml-file>` (or `-c`), that controls which Prometheus metrics are discovered and how they appear in the Kubernetes API.

Discovery is periodic. The adapter queries Prometheus at the interval set by `--metrics-relist-interval`, which defaults to 10 minutes, to build its cache of available metrics. Only metrics that match the rules in the config file appear in the custom metrics API. A metric that Prometheus collects but that no config rule selects is invisible to the HPA.

The adapter's default configuration is at `deploy/manifests/custom-metrics-config-map.yaml` inside the repository. The documentation has a config walkthrough at `docs/config-walkthrough.md` and a full reference at `docs/config.md`.

Installing via Helm or deploying the official registry.k8s.io image

Helm is the documented install path. The chart lives in the prometheus-community repository:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install my-release prometheus-community/prometheus-adapter

Helm 2 users must pass `--name` before the chart argument.

For non-Helm deployments, official images are at `registry.k8s.io/prometheus-adapter/prometheus-adapter:$VERSION`; older builds before that registry existed are in two unofficial locations: `quay.io/repository/coreos/k8s-prometheus-adapter-amd64` and `hub.docker.com/r/directxman12/k8s-prometheus-adapter/`. Deployment YAML is in the `deploy/` directory of the repository. A staging registry at `console.cloud.google.com/gcr/images/k8s-staging-prometheus-adapter/GLOBAL/` holds images for each master branch commit, which the README says is useful for testing a specific commit or deploying a patch before a new release.

--metrics-max-age defaults to the relist interval, and mismatches cause metrics to disappear

`--metrics-max-age` sets how far back in time the adapter queries Prometheus when refreshing its cache. Set to `10m`, it queries for metrics that have datapoints within the last 10 minutes, and only those metrics appear in the adapter. The README states a direct consequence: metrics-max-age must be equal to or larger than the Prometheus scrape interval, or metrics will occasionally disappear from the adapter.

By default, metrics-max-age is set to the same value as the relist interval to avoid confusing behavior. The README references a specific pull request (PR #230) as the source of this default. It also calls out two specific cases where setting metrics-max-age explicitly makes sense: pulling from AWS CloudWatch or Google Monitoring, both of which can have delays between when data is sampled and when it appears in the metrics system.

`--prometheus-url` specifies the Prometheus endpoint. `--lister-kubeconfig` configures how the adapter talks to a Kubernetes API server for label selector operations, defaulting to in-cluster configuration.

config-gen converts the old implicit ruleset to an explicit YAML configuration

Earlier versions of the adapter applied an implicit set of rules to discover Prometheus metrics. Users migrating from those versions can use the included `config-gen` tool to generate a YAML configuration that matches the old behavior:

$ go run cmd/config-gen/main.go [--rate-interval=<duration>] [--label-prefix=<prefix>]

The tool takes optional flags for the rate interval and a label prefix. Output is a YAML configuration that can be saved, reviewed and then passed to the adapter with `--config`. This is a migration step, not a permanent workflow: after running config-gen once, operators typically adjust the generated YAML rather than regenerating it repeatedly.

For an end-to-end deployment example, the README references an external deployment by @luxas at github.com/luxas/kubeadm-workshop. That deployment demonstrates Prometheus, the adapter and a demo pod serving `http_requests_total`, which becomes the custom metrics API metric `pods/http_requests`, then used as an autoscaling target. The README notes that the tutorial uses a slightly older version of the adapter.

Kubernetes API v0.30.0, Go 1.22.5, and multi-architecture image support

go.mod declares the module as `sigs.k8s.io/prometheus-adapter` and sets Go 1.22.1 as the minimum toolchain version, with toolchain go1.22.2 specified. The Makefile sets GO_VERSION to 1.22.5 as the Go version used in container builds.

Direct Kubernetes dependencies include k8s.io/api v0.30.0, k8s.io/apiserver v0.30.0 and k8s.io/metrics v0.30.0. `sigs.k8s.io/custom-metrics-apiserver v1.30.0` and `sigs.k8s.io/metrics-server v0.7.1` are direct dependencies. Prometheus client libraries are `github.com/prometheus/client_golang v1.18.0` and `github.com/prometheus/common v0.46.0`.

The Makefile lists 5 supported build architectures: amd64, arm, arm64, ppc64le and s390x. Container builds use a distroless static base image from `gcr.io/distroless/static:latest-$ARCH` and run the adapter binary as user 65534.

prometheus-adapter is distributed under Apache-2.0.

When the adapter is the wrong metrics pipeline for HPA scaling

prometheus-adapter only works with Prometheus as the metrics source. An operator who wants to autoscale on metrics from a time-series database other than Prometheus cannot use this adapter: the `--prometheus-url` flag is the only connection point the README documents.

Another constraint comes from the Kubernetes API version coupling. go.mod pins k8s.io/api at v0.30.0, corresponding to Kubernetes 1.30. Deploying this adapter on a significantly older cluster risks API incompatibilities. The mapping between the adapter's dependency versions and supported Kubernetes minor versions is not spelled out in the README, which means testing against the target cluster version is necessary before production deployment.

For operators who want HPA scaling on metrics that Prometheus does not already expose, adding a Prometheus exporter is a prerequisite step that sits entirely outside what the adapter manages.

Editorial conclusion

prometheus-adapter is the right choice for a Kubernetes cluster that already runs Prometheus and needs the HPA to scale on custom metrics, since it exposes those metrics to the autoscaling/v2 HPA without a separate metrics store. Skip it when the cluster does not run Prometheus, because the adapter has no other documented metrics source. Before deploying, verify that k8s.io v0.30.0 in go.mod is compatible with your cluster version, review the default config at deploy/manifests/custom-metrics-config-map.yaml, and decide whether to set --metrics-max-age explicitly or leave it at its default, which matches the relist interval.

Frequently asked questions

Official sources

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