# Grafana y Prometheus en Kubernetes (AKS, GKE, EKS e IONOS)

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/grafana-prometheus-kubernetes/

## ¿Qué vas a aprender?

- Desplegar **Prometheus** y **Grafana** en Kubernetes con manifiestos YAML propios, sin depender de un chart.
- Medir un servicio con `/metrics` protegido 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 `kubectl` conectado 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/prometheus` y `grafana/grafana` y añade su `imagePullSecrets`.

## Paso a paso

### 1. Namespace y almacenamiento

```powershell
# 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
```

### 2. Secrets

```powershell
# 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
```

### 3. prometheus-config.yaml

```yaml
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
```

Validar:

```powershell
# 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. prometheus-rbac.yaml

```yaml
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. prometheus.yaml

```yaml
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
```

### 6. grafana.yaml

```yaml
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
```

Aplicar:

```powershell
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. Acceso con port-forward

```powershell
# 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
```

### 8. grafana-interno.yaml (balanceador interno)

```yaml
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 |
|---|---|
| AKS | service.beta.kubernetes.io/azure-load-balancer-internal: "true" |
| GKE | networking.gke.io/load-balancer-type: "Internal" |
| EKS | aws-load-balancer-scheme: "internal" (AWS Load Balancer Controller) |
| IONOS | No hay: port-forward o Ingress con TLS y acceso restringido |

### 9. Operación

```powershell
# 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
```

## 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).
