Una guía práctica para montar la monitorización con Prometheus y Grafana en un clúster de Kubernetes gestionado: AKS (Azure), GKE (Google Cloud), EKS (AWS) o IONOS Managed Kubernetes. Con manifiestos YAML listos para adaptar, credenciales en Secrets, acceso solo por la red interna y las diferencias entre nubes. Todos los manifiestos y comandos están también en el README.md de la izquierda.
¿Qué vas a aprender?
- Desplegar Prometheus y Grafana en Kubernetes con manifiestos YAML propios, sin depender de un chart.
- Medir un servicio con
/metricsprotegido por usuario, contraseña y HTTPS, y descubrir pods automáticamente. - Guardar contraseñas y certificados en Secrets, no en ConfigMaps ni en el YAML.
- Dar acceso a Grafana de forma privada en AKS, GKE, EKS e IONOS.
- Recargar la configuración, revisar el estado y resolver los errores más habituales.
Requisitos previos
- Un clúster de AKS, GKE, EKS o IONOS Managed Kubernetes, y
kubectlconectado a él (ver la guía de administración de Kubernetes). - Permisos para crear namespaces, ClusterRoles y volúmenes persistentes.
- Windows con PowerShell; Docker Desktop solo para validar la configuración.
- En EKS, el complemento Amazon EBS CSI driver para los discos, y el AWS Load Balancer Controller si vas a usar un balanceador interno.
- Las versiones de las imágenes son de ejemplo: fija siempre una versión concreta (nunca
latest) y revisa la última estable en las notas de versión de Prometheus y Grafana. - Si tu clúster solo descarga imágenes de un registro privado, copia ahí
prom/prometheusygrafana/grafanay añade suimagePullSecrets.
Paso a paso
1. Prepara el namespace y comprueba el almacenamiento
Prometheus y Grafana guardan datos en disco, así que necesitan un volumen persistente. Comprueba que estás en el clúster correcto y qué StorageClass se usará por defecto:
# El clúster correcto y un namespace propio para la monitorización
kubectl config current-context
kubectl create namespace monitorizacion
# Qué StorageClass se usará para los discos (la marcada como "(default)")
kubectl get storageclass
Si ninguna aparece como (default), añade storageClassName en los volumeClaimTemplates de los pasos 5 y 6. En EKS, sin el EBS CSI driver los volúmenes se quedan en Pending, y en los clústeres nuevos gp2 ya no viene marcada por defecto.
2. Guarda las credenciales en Secrets
Las contraseñas no van en el ConfigMap de Prometheus ni en el repositorio: cualquiera con acceso de lectura al namespace o al Git las vería. Créalas como Secrets a partir de ficheros locales, que borras después:
# Contraseña y certificado de la autoridad (CA) del servicio que vas a medir
kubectl create secret generic prometheus-objetivo -n monitorizacion `
--from-file=password=.\objetivo-password.txt `
--from-file=ca.crt=.\ca-interna.crt
# Usuario y contraseña del administrador de Grafana
kubectl create secret generic grafana-admin -n monitorizacion `
--from-literal=admin-user=admin `
--from-file=admin-password=.\grafana-password.txt
# Borra los ficheros locales con las contraseñas cuando el Secret esté creado
Remove-Item .\objetivo-password.txt, .\grafana-password.txt
Para el servicio que vas a medir, usa un usuario solo de lectura de métricas. Si su certificado lo firma una CA interna, guarda el ca.crt: así Prometheus valida el certificado en vez de saltarse la comprobación.
3. Configura Prometheus
La configuración va en un ConfigMap. Este ejemplo mide tres cosas: el propio Prometheus, un servicio con /metrics protegido (con password_file y ca_file, que leen el Secret del paso 2) y los pods del clúster que lo pidan con anotaciones:
apiVersion: v1
kind: ConfigMap
metadata:
name: prometheus-config
namespace: monitorizacion
data:
prometheus.yml: |
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
# El propio Prometheus
- job_name: prometheus
static_configs:
- targets: ['localhost:9090']
# Un servicio con /metrics protegido por usuario y contraseña, y HTTPS con CA propia
- job_name: mi-servicio
scrape_interval: 30s
scheme: https
metrics_path: /metrics
basic_auth:
username: lector-metricas
password_file: /etc/prometheus/secretos/password
tls_config:
ca_file: /etc/prometheus/secretos/ca.crt
static_configs:
- targets: ['metricas.mi-empresa.internal:8443']
# Los pods del clúster que lo pidan con anotaciones prometheus.io/*
- job_name: pods
kubernetes_sd_configs:
- role: pod
relabel_configs:
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep
regex: "true"
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
- source_labels: [__meta_kubernetes_namespace]
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
target_label: pod
Para que Prometheus mida un pod, añade a su plantilla prometheus.io/scrape: "true", prometheus.io/port y, si no es /metrics, prometheus.io/path. Antes de aplicarla, valida la configuración con promtool:
# Valida la configuración antes de aplicarla (necesita Docker Desktop)
# Guarda el bloque prometheus.yml en un fichero aparte para esta comprobación
docker run --rm -v "${PWD}:/cfg" --entrypoint promtool prom/prometheus:v3.2.1 check config /cfg/prometheus.yml
4. Da permisos de lectura para descubrir pods
El descubrimiento de pods consulta la API de Kubernetes, así que Prometheus necesita su propia cuenta de servicio con permisos de solo lectura:
apiVersion: v1
kind: ServiceAccount
metadata:
name: prometheus
namespace: monitorizacion
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: prometheus-lectura
rules:
- apiGroups: [""]
resources: [nodes, nodes/metrics, services, endpoints, pods]
verbs: [get, list, watch]
- nonResourceURLs: [/metrics]
verbs: [get]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: prometheus-lectura
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: prometheus-lectura
subjects:
- kind: ServiceAccount
name: prometheus
namespace: monitorizacion
5. Despliega Prometheus
Un StatefulSet con un disco propio, ejecutado sin privilegios de root (el usuario nobody, 65534, de la imagen oficial), con sondas de salud, límites de memoria y 15 días de retención. --web.enable-lifecycle permite recargar la configuración sin reiniciar:
apiVersion: v1
kind: Service
metadata:
name: prometheus
namespace: monitorizacion
spec:
selector:
app: prometheus
ports:
- name: web
port: 9090
targetPort: 9090
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: prometheus
namespace: monitorizacion
spec:
serviceName: prometheus
replicas: 1
selector:
matchLabels:
app: prometheus
template:
metadata:
labels:
app: prometheus
spec:
serviceAccountName: prometheus
securityContext:
runAsNonRoot: true
runAsUser: 65534
runAsGroup: 65534
fsGroup: 65534
# nodeSelector: # opcional: un node pool dedicado a la monitorización
# pool: monitorizacion
containers:
- name: prometheus
image: prom/prometheus:v3.2.1
args:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
- --storage.tsdb.retention.time=15d
- --web.enable-lifecycle
ports:
- containerPort: 9090
readinessProbe:
httpGet: { path: /-/ready, port: 9090 }
livenessProbe:
httpGet: { path: /-/healthy, port: 9090 }
initialDelaySeconds: 30
resources:
requests: { cpu: 250m, memory: 1Gi }
limits: { memory: 2Gi }
securityContext:
allowPrivilegeEscalation: false
volumeMounts:
- name: config
mountPath: /etc/prometheus
- name: secretos
mountPath: /etc/prometheus/secretos
readOnly: true
- name: datos
mountPath: /prometheus
volumes:
- name: config
configMap:
name: prometheus-config
- name: secretos
secret:
secretName: prometheus-objetivo
volumeClaimTemplates:
- metadata:
name: datos
spec:
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 20Gi
El tamaño del disco depende de cuántas series midas y de la retención: empieza con 20 GB y vigila el uso (paso 9).
6. Despliega Grafana con Prometheus ya configurado
Grafana lee el usuario administrador del Secret y la fuente de datos de un fichero de provisioning, así que arranca ya conectada a Prometheus por su nombre interno del clúster:
apiVersion: v1
kind: ConfigMap
metadata:
name: grafana-datasources
namespace: monitorizacion
data:
prometheus.yaml: |
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
access: proxy
url: http://prometheus.monitorizacion.svc.cluster.local:9090
isDefault: true
---
apiVersion: v1
kind: Service
metadata:
name: grafana
namespace: monitorizacion
spec:
selector:
app: grafana
ports:
- name: web
port: 3000
targetPort: 3000
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: grafana
namespace: monitorizacion
spec:
serviceName: grafana
replicas: 1
selector:
matchLabels:
app: grafana
template:
metadata:
labels:
app: grafana
spec:
securityContext:
runAsNonRoot: true
runAsUser: 472
fsGroup: 472
containers:
- name: grafana
image: grafana/grafana:11.6.0
ports:
- containerPort: 3000
env:
- name: GF_SECURITY_ADMIN_USER
valueFrom:
secretKeyRef: { name: grafana-admin, key: admin-user }
- name: GF_SECURITY_ADMIN_PASSWORD
valueFrom:
secretKeyRef: { name: grafana-admin, key: admin-password }
readinessProbe:
httpGet: { path: /api/health, port: 3000 }
resources:
requests: { cpu: 100m, memory: 256Mi }
limits: { memory: 512Mi }
securityContext:
allowPrivilegeEscalation: false
volumeMounts:
- name: datos
mountPath: /var/lib/grafana
- name: datasources
mountPath: /etc/grafana/provisioning/datasources
readOnly: true
volumes:
- name: datasources
configMap:
name: grafana-datasources
volumeClaimTemplates:
- metadata:
name: datos
spec:
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 5Gi
Aplica todo y espera a que los pods estén listos:
kubectl apply -f .\prometheus-config.yaml
kubectl apply -f .\prometheus-rbac.yaml
kubectl apply -f .\prometheus.yaml
kubectl apply -f .\grafana.yaml
kubectl get pods,pvc,svc -n monitorizacion
kubectl rollout status statefulset/prometheus -n monitorizacion
kubectl rollout status statefulset/grafana -n monitorizacion
7. Entra en Grafana de forma segura
Para empezar no necesitas exponer nada: kubectl port-forward abre un túnel desde tu equipo, autenticado con tus credenciales del clúster:
# Grafana en http://localhost:3000 (usuario y contraseña del Secret grafana-admin)
kubectl port-forward svc/grafana 3000:3000 -n monitorizacion
# Prometheus en http://localhost:9090 (Status > Targets: todos los objetivos en UP)
kubectl port-forward svc/prometheus 9090:9090 -n monitorizacion
En Grafana, ve a Explore, elige Prometheus y consulta up: cada objetivo medido aparece con valor 1 si responde.
8. Publica Grafana solo en la red interna
Cuando el equipo necesite entrar sin kubectl, usa un balanceador interno, con una IP privada de la red del clúster, y limita además desde qué redes se puede conectar:
apiVersion: v1
kind: Service
metadata:
name: grafana-interno
namespace: monitorizacion
annotations:
# Solo la línea de tu nube:
service.beta.kubernetes.io/azure-load-balancer-internal: "true" # AKS
# networking.gke.io/load-balancer-type: "Internal" # GKE
# service.beta.kubernetes.io/aws-load-balancer-type: "external" # EKS (AWS Load Balancer Controller)
# service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip" # EKS
# service.beta.kubernetes.io/aws-load-balancer-scheme: "internal" # EKS (ya es el valor por defecto)
spec:
type: LoadBalancer
loadBalancerSourceRanges:
- 10.20.0.0/16 # solo la red de tu oficina o tu VPN, nunca 0.0.0.0/0
selector:
app: grafana
ports:
- name: web
port: 3000
targetPort: 3000
| Nube | Balanceador interno | Notas |
|---|---|---|
| AKS | azure-load-balancer-internal: "true" | IP privada de la VNet del clúster. |
| GKE | networking.gke.io/load-balancer-type: "Internal" | IP privada de la VPC. |
| EKS | aws-load-balancer-scheme: "internal" con el AWS Load Balancer Controller | Crea un Network Load Balancer interno. |
| IONOS | No hay balanceador interno para Services | Los Services LoadBalancer solo funcionan en node pools públicos y asocian una IP pública fija a un nodo: para Grafana, mejor port-forward o un Ingress con TLS y acceso restringido. |
loadBalancerSourceRanges limita las IP de origen: GKE lo aplica en balanceadores internos y externos; en EKS solo tiene efecto si el balanceador conserva la IP del cliente (con nlb-target-type: "ip" viene desactivado). En cualquier nube, refuérzalo con las reglas de red (NSG, firewall de la VPC o security groups).
Nunca publiques Grafana ni Prometheus con 0.0.0.0/0: Prometheus no tiene usuario ni contraseña por defecto, y cualquiera que llegue a él puede leer todas las métricas.
9. Opera el día a día
Para cambiar lo que se mide, edita el ConfigMap, aplícalo y pide a Prometheus que recargue. También tienes aquí cómo comprobar el estado, leer los logs y vigilar el espacio en disco:
# Cambiar la configuración de Prometheus sin reiniciarlo
kubectl apply -f .\prometheus-config.yaml
# (espera alrededor de un minuto a que el pod vea el ConfigMap nuevo)
kubectl port-forward svc/prometheus 9090:9090 -n monitorizacion
curl.exe -X POST http://localhost:9090/-/reload # en otra ventana de PowerShell
# Comprobar el estado
curl.exe http://localhost:9090/-/ready
kubectl logs statefulset/prometheus -n monitorizacion --tail=50
kubectl logs statefulset/grafana -n monitorizacion --tail=50
# Espacio en disco de Prometheus
kubectl exec prometheus-0 -n monitorizacion -- df -h /prometheus
Si la recarga falla, Prometheus sigue con la configuración anterior y lo dice en sus logs: corrige el error y vuelve a recargar.
Errores habituales
El objetivo aparece DOWN con «x509: certificate signed by unknown authority»
Prometheus no confía en el certificado del servicio. Añade la CA que lo firma en tls_config.ca_file (paso 2). No uses insecure_skip_verify: true: así cualquiera podría suplantar el servicio y recibir la contraseña.
El objetivo aparece DOWN con «401 Unauthorized»
El usuario o la contraseña no son correctos, o el fichero tiene un salto de línea al final. Vuelve a crear el Secret con kubectl create secret … --dry-run=client -o yaml | kubectl apply -f - y reinicia el pod.
El pod se queda en Pending
Normalmente es el volumen: kubectl describe pvc -n monitorizacion dice por qué. No hay StorageClass por defecto, falta el EBS CSI driver en EKS o el nodeSelector no encaja con ningún nodo.
CrashLoopBackOff con «permission denied» en /prometheus o /var/lib/grafana
El disco no tiene permisos para el usuario del contenedor. Comprueba que el securityContext del pod lleva fsGroup (65534 para Prometheus, 472 para Grafana).
Grafana no conecta con Prometheus
Revisa la URL de la fuente de datos: dentro del clúster es http://prometheus.monitorizacion.svc.cluster.local:9090, nunca localhost. Comprueba también que el pod de Prometheus está listo.
El balanceador se queda con EXTERNAL-IP en «pending»
La nube no ha podido crearlo: mira los eventos con kubectl describe svc grafana-interno -n monitorizacion. En EKS, revisa que el AWS Load Balancer Controller esté instalado; en IONOS, que el node pool sea público.
Los pods anotados no aparecen en Targets
Falta el RBAC del paso 4 (los logs de Prometheus muestran «forbidden»), o las anotaciones no están en la plantilla del pod sino en el Deployment. El valor de prometheus.io/scrape tiene que ser el texto "true", entre comillas.
Siguientes pasos
- Definir alertas con Alertmanager (por ejemplo, objetivo caído o disco casi lleno) y enviarlas al canal del equipo.
- Medir el propio clúster con kube-state-metrics y node-exporter, o pasar al chart kube-prometheus-stack de Helm cuando necesites todo el conjunto.
- Guardar los dashboards de Grafana como código (provisioning de dashboards) en el repositorio.
- Para retención larga o varios clústeres, valorar un servicio gestionado de Prometheus de tu nube, o Thanos o Mimir.
- Desplegar los manifiestos desde un pipeline (ver la guía de CI/CD con GitHub Actions).