Configuración
Métricas
Tres fuentes de métricas: Metrics Server para los datos en vivo, el agente para el historial y los flujos, o tu Prometheus actual (incluidas las ofertas gestionadas), y el almacén VictoriaMetrics que guarda el historial.
En esta página
KubeBolt tiene tres fuentes de métricas. Se combinan: todo clúster empieza con Metrics Server, y el agente añade historial cuando lo quieres.
| Fuente | Configuración | Qué obtienes |
|---|---|---|
| Metrics Server | Ninguna (viene preinstalado en la mayoría de las distribuciones) | CPU y memoria en vivo de pods y nodos |
| Agente: colectores / scrape | Instalar el agente | Métricas históricas en el VictoriaMetrics de KubeBolt: señales del kubelet y de los nodos, sidecar de scrape vmagent opcional para targets de Prometheus, flujos de red de Hubble opcionales |
| Agente: lee tu Prometheus | Agente con promRead | El mismo historial, obtenido del Prometheus que ya tienes, incluidos Amazon Managed Prometheus, Google Managed Prometheus y Azure Monitor |
Metrics Server (base)
El Metrics Collector consulta metrics.k8s.io/v1beta1 (PodMetrics y
NodeMetrics) cada 30 segundos (el flag --metric-interval de la API). Los
resultados se guardan en una caché en memoria, así que esta fuente no tiene
historial propio.
Degradación elegante: si Metrics Server no está instalado, KubeBolt muestra todo el estado de los recursos y los eventos con normalidad; las barras de uso indican «Metrics Server not detected». El Collector distingue «no instalado» de «403 Forbidden».
Respaldo por namespace: cuando se deniega el acceso a las métricas de todo el clúster, el Collector consulta cada namespace accesible por separado, y se omiten las métricas de nodo.
Historial enviado por el agente
El agente envía muestras por gRPC a la API de KubeBolt, que las escribe en el almacén de métricas. Ese historial alimenta las pestañas Capacity y Reliability, el historial de métricas de los workloads y la pestaña Cost:
- Colectores integrados (siempre activos): el DaemonSet envía estadísticas del kubelet y de cAdvisor, además de señales de carga y presión (PSI) del nodo.
- Flujos de Hubble (
hubble.enabled=true, desactivado por defecto): en clústeres con Cilium, flujos de red leídos del relay de Hubble. - Sidecar de scrape (
scrape.enabled=true): unvmagentincluido hace scraping de targets de Prometheus dentro del clúster (por defecto, los pods anotados conprometheus.io/scrape: "true", más jobs dedicados de node-exporter y kube-state-metrics que puedes activar). Tiene topes defensivos de cardinalidad (maxSeriesPerTarget, un tope de series totales) para que un exporter que se porta mal no inunde el almacén. vmagent envía por remote_write de Prometheus ascrape.remoteWriteUrl(vacío significa que hace scraping pero descarta las muestras), así que necesita el receptor del backend activado. - promRead (
agent.promRead.enabled=true): un Deployment de una sola réplica consulta la APIquery_rangede tu Prometheus para las familias que los colectores no producen (kube-state-metrics, carga/PSI del nodo, disco, errores de red), más las familias de OpenCost conagent.promRead.cost.enabled=true. Modos de autenticación:none,basicAuth,bearer,awsSigV4(AMP vía IRSA),gcpIam(GMP vía Workload Identity),azureWorkloadIdentity. Valores por defecto: consulta cada30s,stepde30s,lookbackde60s.
scrape y promRead son mutuamente excluyentes: el chart falla en
helm template si los dos están activados. Si una fuente de node-exporter ya
envía series de carga/PSI, pon agent.deferNodeStress=true para evitar
series duplicadas.
Almacén de métricas
El historial vive en VictoriaMetrics. El chart de Helm incluye uno de un solo nodo como StatefulSet; en su lugar, puedes apuntar KubeBolt a uno que ya tengas.
| Valor del chart | Por defecto | Qué hace |
|---|---|---|
metrics.storage.embedded.enabled | true | Despliega el VictoriaMetrics incluido |
metrics.storage.embedded.retention | 30d | Cuánto tiempo se guardan las muestras. Sube persistence.size a la vez |
metrics.storage.embedded.persistence.size | 10Gi | Su volumen. persistence.enabled y storageClass están al lado |
metrics.storage.embedded.resources | 100m/256Mi solicitados, 1000m/2Gi de límite | Los requests y límites del pod de VictoriaMetrics |
metrics.storage.embedded.extraArgs | [] | Se añaden a los flags propios del chart (--dedup.minScrapeInterval=30s, --maxLabelsPerTimeseries=60); un flag que repites gana |
metrics.storage.externalUrl | (ninguno) | Tu VictoriaMetrics, que se usa cuando embedded.enabled=false |
metrics.storage.existingSecret | (ninguno) | Secret con username y password y/o token para ese almacén |
Un almacén externo tiene que hablar la API de VictoriaMetrics: KubeBolt escribe
con /api/v1/import/prometheus y /api/v1/write y luego lo consulta, así que
un Prometheus a secas no basta. Arráncalo con -maxLabelsPerTimeseries=60.
Un reinicio del almacén no deja huecos en las métricas del agente. Desde la 2.6.6, la API retiene un lote que el almacén rechazó por un motivo pasajero (error de conexión, timeout, 5xx, 429) y lo vuelve a escribir cuando el almacén responde, del más antiguo al más nuevo y con las marcas de tiempo de las propias muestras. Retiene hasta 64 MiB, unos cuatro minutos de una instalación con mucha actividad; a partir de ahí, se descartan los lotes más antiguos. Cualquier otro 4xx no se reintenta. Funciona con cualquier agente 1.x.
Fuera de Helm, KUBEBOLT_METRICS_STORAGE_URL (por defecto
http://localhost:8428) y sus hermanas _TOKEN / _USERNAME / _PASSWORD
apuntan la API al almacén; Docker Compose incluye uno, con la retención fijada
por KUBEBOLT_METRICS_RETENTION (por defecto 30d). Sin almacén configurado y
sin ninguno respondiendo en la URL por defecto, la API registra en el log que el
historial está desactivado: la CPU y la memoria en vivo siguen llegando de
Metrics Server y todo lo histórico queda vacío. Consulta
Variables de entorno.
Receptor de remote_write de Prometheus
KubeBolt también puede aceptar remote_write de Prometheus en
POST /api/v1/prom/write, desde el sidecar de scrape del agente o desde un
Prometheus tuyo. El receptor está desactivado por defecto: actívalo con
KUBEBOLT_REMOTE_WRITE_ENABLED=true (Helm: metrics.remoteWrite.enabled) o en
Administration → Agents & Ingest → Configuration. Su autenticación es
KUBEBOLT_REMOTE_WRITE_AUTH_MODE: disabled (el valor por defecto, no se
comprueba ningún bearer token), permissive (se comprueba el token y uno
erróneo o ausente queda en el log, pero la petición pasa igualmente) o
enforced (se exige un token de ingesta válido; cualquier otra cosa recibe
401). Usa enforced para todo lo que sea accesible desde fuera del clúster.
Con el agente en auth.mode=ingest-token, vmagent envía el mismo token, así que
un único token cubre los dos caminos.
Qué se acepta:
- Por defecto, solo las familias de métricas de KubeBolt:
kube_*,node_*,container_*,kubelet_*,pod_flow_*,pod_dns_*,hubble_*,kubebolt_*,process_*yup. Las demás series se descartan salvo conKUBEBOLT_PROM_WRITE_ALLOW_CUSTOM_SERIES=true, que el archivo de Docker Compose define y el chart de Helm no. - Dentro de los límites por tenant: 10 000 muestras por segundo con una
ráfaga de 100 000, y 1 000 000 de series activas, cada uno ajustable con las
variables
KUBEBOLT_PROM_WRITE_DEFAULT_*.
Consultas
Las métricas históricas se exponen a través de la API (/api/v1/metrics/query
y /api/v1/metrics/query_range) con PromQL, acotadas al clúster seleccionado.