Kubernetes 1.37: histogramas nativos en Beta y cómo migrar Prometheus sin romper tus dashboards

El 11 de septiembre de 2026, el proyecto Kubernetes anunció que el soporte para histogramas nativos de métricas alcanzó el estado Beta y quedó habilitado por defecto en Kubernetes v1.37. La versión, publicada el 26 de agosto, integra la capacidad en componentes como kube-apiserver, kube-scheduler, kubelet, kube-controller-manager y kube-proxy.

Es una mejora importante para observar latencias y duraciones, pero la actualización del clúster no migra por sí sola la observabilidad. Kubernetes puede entregar histogramas clásicos y nativos a la vez; el servidor Prometheus decide qué formato negocia y almacena. Por eso, el trabajo operativo consiste en actualizar el colector, adaptar consultas y conservar una vía de regreso mientras se valida la nueva serie temporal.

Qué problema resuelven los histogramas nativos

Un histograma clásico de Prometheus se construye con límites fijos. Para una latencia en segundos, un instrumento puede exportar buckets como 0.005, 0.01, 0.025, 0.05 y así sucesivamente. Cada límite se convierte en una serie *_bucket con la etiqueta le; además se almacenan las series _count y _sum.

Ese diseño es sencillo y compatible, pero tiene dos costes. Primero, cada bucket multiplica las series por cada combinación de etiquetas. Segundo, los percentiles se estiman por interpolación entre límites que fueron elegidos antes de conocer la distribución real. Si la latencia cambia de escala o aparece una cola larga, los límites estáticos pueden ofrecer una imagen poco precisa.

Los histogramas nativos convierten el histograma en un tipo de muestra estructurada: una única serie contiene el recuento, la suma y un conjunto dinámico de buckets. Prometheus utiliza buckets exponenciales y una representación dispersa, por lo que no es necesario declarar todos los límites durante la instrumentación. La resolución se adapta al rango observado y los histogramas se pueden combinar entre sí cuando usan esquemas compatibles.

La documentación de Kubernetes estima una reducción aproximada de diez veces en el número de series por histograma. El anuncio de la versión la expresa como hasta un 90 % menos de series, pero no es una promesa universal: etiquetas, distribución de los datos, resolución y backend determinan el ahorro real. Mide memoria, ingestión, consultas y almacenamiento de tu instalación antes de extrapolarlo.

Qué cambia en Kubernetes v1.37

El feature gate se llama NativeHistograms. En v1.36 estaba disponible, pero había que activarlo manualmente; en v1.37 está en Beta y se habilita por defecto. Los administradores aún pueden desactivarlo y deben reiniciar el componente correspondiente para que el cambio tenga efecto.

La lista de componentes cubierta por la documentación oficial es:

Componente	Ejemplos de métricas o alcance
kube-apiserver	apiserver_request_duration_seconds y latencias relacionadas
kube-scheduler	Duración de la planificación y de plugins
kubelet	Métricas de nodo, runtime y ciclo de vida de pods
kube-controller-manager	Métricas del controlador
kube-proxy	Métricas del proxy

La transición está diseñada como doble exposición. Cuando el endpoint recibe una solicitud compatible, el payload Protobuf puede incluir los buckets clásicos y los campos del histograma nativo. Así, un Prometheus antiguo puede seguir leyendo el formato clásico y uno compatible puede ingerir el nativo. En cambio, el formato de texto (text/plain u OpenMetrics 1.0) continúa ofreciendo los buckets clásicos. Un curl sin negociación de contenido, por tanto, no demuestra que el componente carezca de histogramas nativos.

Esto separa dos decisiones que a menudo se confunden:

1. Kubernetes expone datos nativos porque el gate está activo.
2. Prometheus los negocia, ingiere y almacena solo si su versión y configuración lo permiten.

Matriz de compatibilidad de Prometheus

Comprueba la versión exacta del servidor antes de cambiar el scraping:

Versión de Prometheus	Soporte	Configuración relevante
Menor que 2.40	No admite histogramas nativos	Solo formato clásico; el gate de Kubernetes no cambia el resultado
2.40 hasta 2.x	Experimental	--enable-feature=native-histograms, global y sin control por trabajo
3.0–3.7	Estable	scrape_native_histograms y always_scrape_classic_histograms por trabajo; comprueba la versión exacta
3.8	Estable	Configuración por trabajo para control fino; la bandera global solo fija el valor predeterminado
3.9 o posterior	Estable	Configuración explícita por trabajo; la antigua bandera global es un no-op

La tabla sigue la clasificación operativa de la documentación de Kubernetes para esta integración. La especificación de Prometheus sitúa la primera implementación compatible en la versión 2.40 y el soporte estable del servidor a partir de la 3.8; son referencias complementarias, no una razón para omitir la comprobación de la versión exacta. Aunque Prometheus sea compatible, hay que revisar el resto de la cadena: remote write, almacenamiento remoto, reglas, consultas y la versión de Grafana u otra interfaz. La capacidad de ingestión local no garantiza que cada receptor remoto entienda o reenvíe muestras nativas.

Al corte de esta guía, la página oficial de descargas lista Prometheus 3.14.0 como versión más reciente y 3.13.3 como LTS. Son referencias de disponibilidad, no un requisito universal: elige una versión soportada por tu distribución, operadores, políticas de cambio y backend, y verifica sus notas de versión antes de actualizar.

En Prometheus 3.x, la negociación nativa utiliza Protobuf. Prometheus lo gestiona automáticamente si no se ha personalizado scrape_protocols; si existe una lista propia, debe incluir PrometheusProto.

Si usas remote write

La activación del scraping nativo solo cubre la ingestión local. Para enviar esas muestras a un almacenamiento remoto, cada destino remote_write debe ser compatible y declarar explícitamente send_native_histograms: true:

remote_write:
  - url: https://metrics.example.invalid/api/v1/write
    send_native_histograms: true

La URL es un marcador de posición. Confirma en la documentación del receptor si acepta histogramas nativos y si requiere Remote Write 2; de lo contrario, mantén el envío clásico o limita la migración al almacenamiento local. No confundas scrape_native_histograms (entrada) con send_native_histograms (salida).

Una migración reversible en Prometheus 3.x

Empieza por un trabajo de pruebas o por un subconjunto controlado de objetivos. La configuración mínima durante la transición es:

scrape_configs:
  - job_name: kubernetes-apiservers
    scrape_native_histograms: true
    always_scrape_classic_histograms: true

scrape_native_histograms: true permite que Prometheus solicite e ingiera muestras nativas. always_scrape_classic_histograms: true fuerza también la ingestión de los buckets clásicos cuando el endpoint expone ambos formatos.

Esta segunda opción es la protección contra el fallo más común. Si se activa la ingestión nativa pero se deja la opción clásica en false, Prometheus puede dejar de almacenar _bucket, _count y _sum. Un dashboard que todavía ejecute histogram_quantile(..._bucket...) no encontrará datos, aunque el endpoint de Kubernetes esté funcionando correctamente.

Valida la configuración con la herramienta y el procedimiento de despliegue habituales de tu distribución de Prometheus. El ejemplo es deliberadamente por trabajo: los nombres de jobs, relabeling, autenticación y descubrimiento de servicios dependen de cada instalación. No copies credenciales ni reemplaces una configuración completa por este fragmento.

Si todavía operas Prometheus 2.x, el feature flag es global:

prometheus --enable-feature=native-histograms

Ese modo no permite una migración progresiva por trabajo. En Prometheus 3.9 y posteriores no conviene trasladar la solución anterior: declara scrape_native_histograms de forma explícita en cada scrape_config.

PromQL: del bucket fijo al histograma nativo

Una consulta clásica para el percentil 99 de la duración de peticiones del API server es:

histogram_quantile(
  0.99,
  rate(apiserver_request_duration_seconds_bucket[5m])
)

La versión nativa opera sobre el nombre de la métrica sin el sufijo _bucket:

histogram_quantile(
  0.99,
  rate(apiserver_request_duration_seconds[5m])
)

Al agregar varios API servers, un histograma clásico debe conservar la etiqueta le para no mezclar límites:

histogram_quantile(
  0.99,
  sum by (le) (
    rate(apiserver_request_duration_seconds_bucket[5m])
  )
)

Con el tipo nativo no hay que agrupar por le:

histogram_quantile(
  0.99,
  sum(rate(apiserver_request_duration_seconds[5m]))
)

Revisa también las reglas que referencien _count y _sum. Para histogramas nativos, PromQL ofrece funciones como histogram_count() y histogram_sum(), además de histogram_fraction(), histogram_stddev() y histogram_stdvar(). La migración no consiste en hacer un reemplazo de texto indiscriminado: una expresión con filtros, agregaciones, recording rules o varias etiquetas debe volver a validarse semánticamente.

Procedimiento de verificación

Una secuencia práctica para SRE y equipos de plataforma es:

1. Inventariar. Registra las versiones de Kubernetes y Prometheus, los componentes en v1.37 y cualquier override de NativeHistograms. Busca en repositorios de dashboards, recording rules y alertas las referencias a _bucket, _count, _sum, histogram_quantile y le.
2. Probar la ruta. En staging, activa ambos formatos en un solo job. Confirma que el target se raspa sin errores y que el Prometheus elegido negocia Protobuf.
3. Duplicar consultas. Mantén temporalmente la versión clásica y crea la equivalente nativa. Compara percentiles, SLO y alertas sobre ventanas de tiempo con tráfico representativo; no esperes igualdad bit a bit porque los métodos de estimación son distintos.
4. Observar el coste. Mide process_resident_memory_bytes, latencia de consultas, muestras ingeridas y crecimiento de TSDB. Si usas remote write, confirma de manera independiente que el receptor conserva y consulta histogramas nativos.
5. Promover gradualmente. Lleva la configuración a producción por jobs o grupos de componentes. Conserva los clásicos mientras quede un panel, regla o consumidor sin migrar.
6. Retirar lo clásico con evidencia. Cuando las consultas nativas estén verificadas y no haya dependencias de las series clásicas, cambia always_scrape_classic_histograms a false y vuelve a medir. El ahorro depende de tu carga, no del número anunciado como máximo.

No uses el endpoint de métricas directamente con credenciales reales para experimentar. Para comprobar la exposición Protobuf, utiliza un entorno de pruebas y el mecanismo de autenticación de tu plataforma; la guía oficial muestra un ejemplo con curl solo como diagnóstico y advierte que no es una receta segura para producción.

Rollback sin deshacer la actualización del clúster

La ventaja de separar Kubernetes del colector es que el primer rollback puede ser rápido. En Prometheus 3.x, fija:

scrape_configs:
  - job_name: kubernetes-apiservers
    scrape_native_histograms: false

En el siguiente ciclo de scraping, ese job vuelve a solicitar e ingerir el formato clásico; no hace falta reiniciar Kubernetes. Si el problema está en la exposición del componente o necesitas que el clúster deje de anunciar nativos, desactiva el gate y reinicia el componente:

--feature-gates=NativeHistograms=false

La reversión del colector es la opción menos intrusiva. Documenta qué jobs cambiaron, conserva las consultas clásicas durante el periodo de observación y define de antemano qué aumento de memoria, errores de scrape o divergencia de SLO activa el rollback.

Conclusión

Kubernetes v1.37 convierte los histogramas nativos en una capacidad Beta disponible por defecto, no en una migración automática de toda la plataforma de observabilidad. El diseño de doble exposición permite avanzar sin cortar los dashboards existentes, siempre que Prometheus mantenga ambos formatos durante la transición.

La ruta prudente es actualizar el colector a una versión compatible, activar el scraping nativo por trabajo, conservar las series clásicas, migrar PromQL y validar almacenamiento, alertas y receptores remotos. Solo después de esa comprobación conviene retirar _bucket, _count y _sum. Así, la mejora de resolución y eficiencia de los histogramas nativos se convierte en una ganancia operativa medible, con un rollback sencillo si la carga real cuenta otra historia.

Fuentes primarias

• Kubernetes: Native Histograms Graduates to Beta — anuncio del estado Beta, doble exposición, componentes, configuración y ejemplos de PromQL (11 de septiembre de 2026).
• Kubernetes: Native Histogram Support for Kubernetes Metrics — requisitos, matriz de versiones, negociación Protobuf, migración y rollback.
• Kubernetes v1.37: Garhwal — publicación y contexto de la versión 1.37 (26 de agosto de 2026).
• Kubernetes 1.37: estado de la serie y parches — 1.37.0 como parche más reciente al corte del 14 de septiembre y 1.37.1 como próximo parche previsto.
• Kubernetes: calendario de patch releases — cadencia y fecha objetivo del siguiente parche.
• KEP-5808: Native Histogram Support for Kubernetes Metrics — diseño de la capacidad y estrategia de compatibilidad.
• Prometheus: Native Histograms — evolución del soporte desde Prometheus 2.40, estabilidad desde 3.8 y activación explícita del scraping.
• Prometheus: Configuration — referencia de scrape_native_histograms, always_scrape_classic_histograms y negociación de protocolos.
• Prometheus: Download — versiones 3.14.0 (latest) y 3.13.3 (LTS) visibles al corte editorial.