1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Prometheus Operator / kube-prometheus-stack
kubectl -n monitoring patch prometheus kube-prometheus-stack-prometheus --type merge \
  -p '{"spec":{"enableAdminAPI":true}}'
kubectl -n monitoring port-forward svc/prometheus-operated 9090 &

# crear el snapshot (la ruta es /api/v1, no /api/v2)
curl -s -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
# {"status":"success","data":{"name":"20260926T101500Z-3f2b1c9a7d0e4b11"}}

# sacarlo del pod con tar por stdout, mucho más rápido que kubectl cp
SNAP=20260926T101500Z-3f2b1c9a7d0e4b11
kubectl -n monitoring exec prometheus-kube-prometheus-stack-prometheus-0 -c prometheus -- \
  tar cf - -C /prometheus/snapshots $SNAP | tar xf - -C ./backup/

Fuera de Kubernetes es lo mismo con el flag --web.enable-admin-api en la línea de comandos de Prometheus y el snapshot en <storage.tsdb.path>/snapshots/.

Por qué no vale copiar el directorio

La TSDB escribe en el head (WAL más el bloque en memoria) mientras compacta bloques de dos horas en bloques más grandes y borra los viejos. Un cp -r o un rsync de /prometheus en marcha pilla bloques a medio compactar, un WAL que ya no cuadra con los checkpoints, y con suerte arranca; con menos suerte, opening storage failed: … corrupted.

El snapshot lo hace Prometheus desde dentro: crea snapshots/<fecha>-<id>/ con hardlinks a los bloques ya compactados (ocupa casi nada y tarda segundos) y vuelca el head como un bloque más, así que la copia es consistente hasta el instante de la petición. Con ?skip_head=true se salta el head y solo incluye lo compactado, que basta si haces snapshots a diario y no te importan las últimas dos horas.

Restaurar

Un snapshot es un directorio de bloques (01HXYZ…/, cada uno con chunks/, index, meta.json, tombstones). Restaurar es ponerlos en la raíz del directorio de datos de la instancia destino:

1
2
3
4

# instancia nueva (StatefulSet o binario) parada, o al menos con el data dir vacío
kubectl -n newprom exec prometheus-new-0 -c prometheus -- rm -rf /prometheus/wal /prometheus/01*
tar cf - -C ./backup/$SNAP . | kubectl -n newprom exec -i prometheus-new-0 -c prometheus -- tar xf - -C /prometheus/
kubectl -n newprom delete pod prometheus-new-0     # reinicia para que lea los bloques

Prometheus carga los bloques al arrancar y los va compactando con los nuevos. Los bloques con etiquetas externas distintas (otro cluster, otro replica) se mezclan sin problema; lo que no puedes es restaurar bloques que se solapen en tiempo con datos que ya existen y esperar que se fusionen: se quedan duplicados hasta la siguiente compactación, y las consultas ven ambas series.

promtool tsdb list /prometheus y promtool tsdb analyze /prometheus <bloque> dicen qué rango cubre cada bloque y qué series pesan más.

Borrar series y liberar espacio

La misma API sirve para quitar métricas que no debían estar (un exporter con cardinalidad desbocada, datos de una prueba):

1
2

curl -s -XPOST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]={job="noisy-exporter"}&start=2026-09-01T00:00:00Z&end=2026-09-20T00:00:00Z'
curl -s -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

delete_series solo marca (tombstones); el espacio no se libera hasta clean_tombstones o la siguiente compactación. Los dos devuelven 204 sin cuerpo.

Trampas

• La admin API no tiene autenticación: cualquiera que llegue al 9090 puede borrar toda la base. Actívala, haz el snapshot por port-forward, y vuelve a ponerla en false. Nunca detrás de un Ingress sin auth.
• kubectl cp con miles de ficheros tarda una eternidad y a veces se corta; el tar por stdout de arriba es un solo flujo. Para snapshots de decenas de GB, monta un PVC de backup o usa un sidecar con mc/rclone hacia S3.
• Borra los snapshots viejos de /prometheus/snapshots/: son hardlinks, pero mantienen vivos bloques que la retención ya habría eliminado, y el disco crece sin que la retención lo explique.
• Thanos o Mimir con sidecar ya suben cada bloque a S3: ahí el snapshot solo sirve para el head. El backup son los buckets.
• kube-prometheus-stack: prometheus.prometheusSpec.enableAdminAPI: true en los values si quieres que el patch sobreviva al siguiente helm upgrade.

Referencias: TSDB Admin APIs en la documentación de Prometheus.

Ver también

• Grafana con SSO — la otra mitad del stack.
• ZFS: proteger snapshots con hold — si el data dir de Prometheus vive en ZFS, los snapshots del sistema de archivos son otra opción consistente.

1

https://grafana.example.com/login?disableAutoLogin=true

Eso te lleva al formulario de usuario y contraseña aunque auto_login = true te esté redirigiendo al proveedor OAuth. Si además no recuerdas la contraseña del admin local:

1
2
3
4

# contenedor / pod
grafana cli --homepath /usr/share/grafana admin reset-admin-password 'nueva'
# paquete
grafana-cli admin reset-admin-password 'nueva'

Y si el formulario está desactivado ([auth] disable_login_form = true), primero GF_AUTH_DISABLE_LOGIN_FORM=false en el entorno y reinicia.

Roles que se deshacen solos

Le das Editor a alguien en Administration → Users, y al día siguiente vuelve a ser Viewer. No es un bug: en cada login OAuth Grafana sincroniza el rol de la organización con lo que diga el proveedor (o con auto_assign_org_role si el proveedor no dice nada) y pisa lo que pusiste a mano.

Dos formas de vivir con ello:

1. Que el proveedor mande de verdad. Mapea grupos o claims a roles con JMESPath y haz que sea estricto, para que un usuario sin grupo no entre como Viewer por defecto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[auth.github]
enabled = true
allow_sign_up = true
auto_login = true
client_id = $__file{/etc/secrets/github-client-id}
client_secret = $__file{/etc/secrets/github-client-secret}
scopes = user:email,read:org
allowed_organizations = my-org
role_attribute_strict = true
allow_assign_grafana_admin = true
role_attribute_path = contains(groups[*], '@my-org/grafana-admin') && 'GrafanaAdmin' || contains(groups[*], '@my-org/grafana-editor') && 'Editor' || contains(groups[*], '@my-org/grafana-viewer') && 'Viewer'

2. Que Grafana no toque los roles. Si prefieres gestionarlos en la UI:

1
2

[auth.github]
skip_org_role_sync = true

skip_org_role_sync va por proveedor (auth.github, auth.google, auth.generic_oauth, auth.azuread, auth.okta, auth.gitlab, SAML). El antiguo interruptor global [auth] oauth_skip_org_role_update_sync está obsoleto; si todavía lo tienes en el .ini, cámbialo por el de cada proveedor.

Con Google, hosted_domain y allowed_domains limitan quién puede entrar; sin role_attribute_path todos entran con auto_assign_org_role (Viewer por defecto).

Datasources aprovisionados

Los datasources definidos en provisioning/datasources/*.yaml (en el chart de Helm, datasources.datasources.yaml) tienen tres propiedades que sorprenden:

• No se editan en la UI si llevan editable: false: el formulario aparece bloqueado. Es lo correcto en producción; el cambio va en el YAML.
• Los secretos van en secureJsonData, no en jsonData: Grafana los cifra con secret_key antes de guardarlos en su base de datos (/var/lib/grafana/grafana.db, SQLite por defecto) y no los devuelve por la API. Tokens, contraseñas y certificados de cliente van ahí; en jsonData quedan en claro.
• No desaparecen al quitarlos del YAML. Grafana solo inserta y actualiza; para borrar hay que decirlo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: 1
prune: true                  # versiones recientes: borra lo aprovisionado que ya no esté en este archivo
deleteDatasources:
  - name: Sentry-old
    orgId: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    orgId: 1
    url: http://prometheus-server.monitoring.svc.cluster.local
    isDefault: true
    editable: false
    version: 1
  - name: Sentry
    type: grafana-sentry-datasource
    access: proxy
    orgId: 1
    editable: false
    jsonData:
      url: https://sentry.io
      orgSlug: my-org
    secureJsonData:
      authToken: ${SENTRY_TOKEN}      # variable de entorno del proceso de Grafana

Las variables de entorno se expanden con $VAR o ${VAR}; un $ literal en un secreto se escribe $$.

Trampas

• auto_login con varios proveedores se ignora: solo funciona con uno configurado para auto-login.
• allow_sign_up = false deja fuera a cualquier usuario nuevo del proveedor, incluido el que acabas de dar de alta en el grupo; el error en el log es “user signup disabled”.
• role_attribute_strict = true sin grupo mapeado rechaza el login con “Role attribute not found”; es lo que quieres, pero avisa a la gente.
• El admin local sigue existiendo con SSO: cámbiale la contraseña y guárdala en el gestor de secretos, es tu puerta de emergencia junto con disableAutoLogin.
• secret_key por defecto (SW2YcwTIb9zpOOhoPsMm) cifra los secureJsonData de cualquier Grafana igual; ponle el tuyo ([security] secret_key) antes de aprovisionar nada, porque cambiarlo después invalida lo cifrado.

Referencias: Configure authentication y Provisioning en la documentación de Grafana.

Ver también

• Proxmox con Keycloak (OpenID) — el mismo patrón de SSO, con Keycloak como proveedor.