Kubernetes v1.37 moves native histogram support for Kubernetes component metrics to Beta and enables it by default. The change gives platform and observability teams access to distribution data without relying exclusively on manually selected fixed bucket boundaries, but it also makes Prometheus configuration and migration planning important.
Native histograms can improve storage efficiency, query performance, and visibility into metric distributions. The expected benefits are workload-dependent: Kubernetes documentation and KEP-5808 describe an approximate tenfold reduction in time-series count per histogram as a potential result, not a guarantee for every deployment.
What changed in Kubernetes 1.37
According to the Kubernetes native histogram documentation, support is Beta beginning with Kubernetes v1.37 and is enabled by default. Kubernetes v1.36 or later is required for the documented feature. On v1.36, operators must enable the feature gate manually; on v1.37, the gate is enabled by default.
The NativeHistograms feature gate controls whether Kubernetes components expose native histograms. It can be explicitly enabled or disabled with the --feature-gates command-line option, using settings such as --feature-gates=NativeHistograms=true.
The documented components are:
kube-apiserverkube-controller-managerkube-schedulerkubeletkube-proxy
The gate can be controlled independently for each component. That means a cluster may not expose native histograms consistently if the relevant components have different versions or feature-gate settings.
Why native histograms matter
Classic Prometheus histograms use a fixed set of bucket boundaries selected when the metric is defined. Native histograms use exponential bucket boundaries and can represent distributions with more adaptable resolution. This is particularly relevant for latency quantiles, where fixed buckets can make accuracy depend heavily on whether the chosen boundaries match the observed workload.
The operational benefit is not simply a new exposition format. Native histograms are intended to reduce the number of time series associated with a histogram while preserving more distribution detail. The Kubernetes documentation and KEP-5808 describe storage and query improvements, along with a default maximum of 160 buckets for native histogram storage in the KEP.
Those figures should be treated as planning guidance rather than universal capacity guarantees. Operators should watch Prometheus memory use, storage behavior, and metrics endpoint behavior after enabling the feature.
Prometheus still controls ingestion
Enabling native histogram exposure in Kubernetes does not automatically mean Prometheus will ingest and store native histograms. The Prometheus side must support native histogram scraping and be configured to request it.
The Kubernetes documentation lists Prometheus 2.40 or later as required to scrape and store native histograms. For applicable Prometheus 3.x configurations, the documented migration settings are:
scrape_native_histograms: true
always_scrape_classic_histograms: trueThese settings are applied per scrape job. When native histogram scraping is enabled, Prometheus requests a native-capable Protobuf exposition format. A text-format request returns classic histogram buckets instead. If scrape protocols have been customized, PrometheusProto must remain available.
The supplied Kubernetes documentation and KEP-5808 differ on the exact Prometheus 3.x maturity boundary. The documentation describes native histogram support across several Prometheus 3.x versions, with configuration behavior changing in later versions, while the KEP states that stable support begins with Prometheus 3.8.0. Because those sources do not align, teams should verify the behavior and configuration requirements for the specific Prometheus version they operate rather than treating one version policy as definitive.
Classic histogram compatibility requires a staged migration
Kubernetes components can expose native and classic Prometheus histogram formats together when a native-capable format is requested. That dual-exposition behavior allows existing dashboards and alerts to continue using classic histogram series while teams evaluate native data and update queries.
During migration, retaining classic ingestion is important. The Kubernetes documentation warns that enabling native histogram ingestion while disabling classic histogram ingestion can leave dashboards and alerts that depend on classic _bucket queries with no data.
A safer sequence is to enable native ingestion and keep always_scrape_classic_histograms: true while testing. Update dashboards and alert queries to use native histogram data, validate them in staging, and confirm production coverage before disabling classic ingestion. After verification, classic ingestion can be disabled with always_scrape_classic_histograms: false if the remaining monitoring requirements allow it.
What you should do
- Inventory versions. Confirm that the relevant Kubernetes components are running v1.36 or later and identify the Prometheus version used for scraping and storage.
- Check each component’s gate. Review the
NativeHistogramssetting for the API server, control-plane components, kubelet, and kube-proxy. On v1.36, enable it manually where appropriate; on v1.37, verify the default has not been overridden. - Review scrape protocols. Confirm that Prometheus can request the native-capable Protobuf format and that
PrometheusProtoremains available if protocols were customized. - Start with dual ingestion. Enable
scrape_native_histograms: trueand retainalways_scrape_classic_histograms: truefor the relevant scrape jobs. - Test monitoring queries. Review latency dashboards and alerts, especially those based on classic
_bucketseries. Test changes in staging before changing production ingestion behavior. - Monitor resource effects. Track memory usage, storage behavior, and metrics endpoint performance after rollout. The expected efficiency gains and resource overhead can vary by metric and workload.
Availability and remaining caveats
Native histogram support is documented as Beta in Kubernetes v1.37 and enabled by default; it is not described in the supplied material as a separate managed-service or platform-specific capability. The documentation establishes the Kubernetes-side feature gate and Prometheus requirements, but it does not provide an exact v1.37 release schedule in the supplied sources.
Operators can roll back by changing Prometheus ingestion settings or disabling the Kubernetes feature gate and restarting the affected component. Any rollback plan should account for the possibility that dashboards and alerts depend on classic histogram data.
