kubernetes/metrics: the API types behind custom and resource metrics

A staged repository, not a place to send pull requests

The first thing the README tells you is that this is an automatically published staged repository for Kubernetes, and that it is read-only for importing and not used for direct contributions. Issues and pull requests belong in the main Kubernetes repository.

That single fact shapes how you should evaluate the project. This is not a standalone tool you install and run. It is one slice of the Kubernetes source tree, published separately so that other Go projects can depend on it as a module without pulling in the entire kubernetes/kubernetes repository, which is enormous.

The purpose section states it plainly. The repository contains type definitions and client code for the metrics APIs that Kubernetes makes use of, and depending on the API, the actual implementations live elsewhere. Consumers of the metrics APIs can use the repository to access implementations of the APIs, while implementors should use the library when implementing their API servers.

So there are two audiences, and they use the same code differently. A consumer wants the client and the types, so it can ask a cluster for metrics. An implementor wants the same types, so its server speaks the same wire format as everyone else.

The module is k8s.io/metrics, and it is published under the k8s.io import path, which is the standard convention for Kubernetes submodules. The Go version requirement is stated in the module file:

module k8s.io/metrics

go 1.27.0

The go.mod also carries a godebug line defaulting to go1.27 and a comment at the top noting that the file is generated and should not be edited directly, which is the usual signal that the dependencies are pinned by the release tooling rather than chosen by hand.

Custom Metrics API and Resource Metrics API

The repository covers two APIs, and the difference between them is about who owns the metric.

The Custom Metrics API allows consumers to access arbitrary metrics which describe Kubernetes resources. The README says it is intended to be implemented by monitoring pipeline vendors, on top of their metrics storage solutions. The word arbitrary is the point. A custom metric can be anything a monitoring vendor can produce about an object, not just the fixed set of CPU and memory numbers the cluster can measure itself. If you want a per-tenant request rate or a business metric attached to a Deployment, this is the API shape for it.

The import path is k8s.io/metrics/pkg/apis/custom_metrics.

The Resource Metrics API is the narrow one. It allows consumers to access resource metrics, CPU and memory, for pods and nodes. It is implemented by metrics-server and by prometheus-adapter, both from the kubernetes-sigs organisation. The import path is k8s.io/metrics/pkg/apis/metrics.

That last point is the one to internalise. The API that most people interact with, the one behind kubectl top and the Horizontal Pod Autoscaler reading resource metrics, has its implementations elsewhere. What lives here is the contract: the request and response types, the group and version identifiers, the list and item shapes that a client marshals and a server unmarshals.

If you want an implementation rather than a contract, the README points you at the kubernetes-sigs/custom-metrics-apiserver library, which it describes as containing the basic infrastructure required to set up such an API server for the custom metrics API.

The dependency set and what it tells you about the client

The go.mod requires k8s.io/api, k8s.io/apimachinery, k8s.io/client-go and k8s.io/code-generator, plus github.com/stretchr/testify for tests. The four Kubernetes dependencies are pinned to pseudo-versions that carry a timestamp and a commit hash rather than a release tag, for example k8s.io/api at a version ending in 20261014062226.

That is the staging area's versioning convention showing through. Because the repository is published automatically from the main Kubernetes tree on every change, the dependency versions track the exact commit the types were generated from, which is what makes the API types consistent with the rest of the platform at that moment.

The presence of k8s.io/code-generator is a signal about how the types are produced. The Kubernetes API machinery generates the type definitions, the deep copy functions, the client code and the apply configurations from a single source of truth, and the code-generator dependency is what ties this repository into that pipeline. The top-level listing backs this up: there is a doc.go at the root, a pkg/ directory holding the packages, a hack/ directory that typically carries the code generation scripts, and the go.sum and go.mod pair. The OWNERS file, SECURITY_CONTACTS and the code of conduct document complete the set of files that a Kubernetes subproject carries.

The practical consequence for a consumer is that importing this module pulls in apimachinery and client-go, which is where the dependency weight of a Kubernetes client lives. That is unavoidable if you want to talk to the API with the standard client machinery, and it is worth accounting for before you add it to a service that currently has no Kubernetes dependencies.

Following the Kubernetes release train for compatibility

The compatibility section is short and points at the platform's general policy rather than a table of versions. The APIs in this repository follow the standard guarantees for Kubernetes APIs, and will follow Kubernetes releases.

That is a meaningful commitment in practice, because it means the API group and version you compile against are the ones the cluster serves, and the deprecation rules of the Kubernetes API machinery apply. When an API version is removed upstream, it is removed here too, on the platform's schedule rather than on this repository's own.

The recent release list for this repository is empty, which is consistent with how staged repositories work. There are no GitHub releases to point at, because the artifact is the module at a set of pseudo-versions, and the last push was on 2026-10-14. The README notes that the documentation for engaging with the community lives on the Kubernetes community page, and that the maintainers of this repository are reachable on the #sig-instrumentation Slack channel and on the corresponding mailing list.

The contribution section points at a CONTRIBUTING.md in the repository for the details, and the code of conduct document governs participation. The odd spelling in the heading of that section, Contibution, is in the original and is worth mentioning only because a search for the correctly spelled word will not find it.

Which project to actually install for a working setup

The most common mistake with this repository is expecting it to be a metrics service. It is not. Nothing in the tree starts a server, scrapes a kubelet, or stores a time series.

The working pieces are three separate projects, and choosing between them is a design decision rather than an installation detail. metrics-server is the in-tree answer for resource metrics, giving you CPU and memory for pods and nodes with the lowest operational overhead. prometheus-adapter serves the same resource metrics API shape but derives them from Prometheus, which is the choice when you already run Prometheus and want one place to query. And for custom metrics, custom-metrics-apiserver provides the infrastructure to stand up an API server for arbitrary per-object metrics, which is the piece you build on if your monitoring vendor exposes something the cluster cannot measure itself.

The difference in approach between them is where the resource metrics are read from and how much machinery sits between you and the kubelet. metrics-server talks to the kubelet directly. prometheus-adapter asks Prometheus, which has already scraped the data, and translates what Prometheus has into the metrics API shape. custom-metrics-apiserver is a server you extend.

A client library is a fourth concern, and that is where this repository fits. When you write Go code that calls any of those three, you import the types from k8s.io/metrics so your request and response objects are the same ones the server speaks, rather than hand-rolled structs that drift out of alignment the first time a field is added.

The limits of a read-only, generated repository

There are constraints here that are not bugs and cannot be fixed by waiting.

The first is that you cannot contribute here. The README is explicit that this repository is read-only for importing and that contributions go to the main Kubernetes repository. If you find a problem with a type definition, your patch goes into kubernetes/kubernetes, and the staged repository picks up the change on the next publish. That workflow is fine for a project with a wide reviewer base and a full CI pipeline behind it, and it does mean you cannot point a pull request at this tree.

The second is that the API surface is versioned by the platform, not by this project. There is no independent release cadence here, and no way to pin a metrics client to a version that diverges from the cluster. If your service needs to talk to clusters at different versions, you will find yourself importing different module versions in different builds, and the compatibility work is on you.

The third is scope. Two APIs live here, and if you need a third kind of metrics, a different Kubernetes API group entirely, or anything like a horizontally scalable long-term store, none of it is in this module.

None of these make it a poor dependency. They make it a narrow one. If you need a metrics backend, a dashboard, a long-term store or a scraper, the answer is elsewhere, and this repository is the piece that lets your Go code speak the right protocol to whatever you chose.

Editorial conclusion

Adopt kubernetes/metrics as a Go dependency if you are writing a client for a Kubernetes metrics API, or implementing one, and you want the exact contract the platform guarantees. Do not treat this repository as a source of implementation, a metrics backend, or a place to send pull requests, since the actual servers live in metrics-server, prometheus-adapter and custom-metrics-apiserver, and this tree is read-only. Verify first that the import path you need exists, that the API version your client speaks matches what your cluster serves, and that you have picked the right implementation project before you write any server code.

Frequently asked questions

Official sources

1. Issues
2. kubernetes/metrics on GitHub
3. License: Apache-2.0
4. README