En Kubernetes, el chart de Helm de Grafana convierte las carpetas de provisioning en configuración que escribes en values.yaml. El chart renderiza ConfigMaps y Secrets, los monta en las rutas que Grafana espera y reinicia o recarga cuando cambian. Eso hace de Grafana un buen candidato para GitOps, ya que el archivo de valores es lo único que editas. Esta guía construye un archivo de valores que provisiona un data source, dashboards, alertas y ajustes del servidor.

El alojamiento de charts está cambiando: algunos charts de Grafana Labs se están moviendo a un repositorio mantenido por la comunidad. Antes de instalar, comprueba el README del chart para ver la URL del repositorio y la versión del chart que debes usar, y fija esa versión. Las claves de valores de abajo siguen la estructura documentada del chart, pero confírmalas en el values.yaml de la versión que instales.

Instala

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
helm install grafana grafana/grafana \
  --namespace monitoring --create-namespace \
  --version <chart-version> \
  -f values.yaml

Si el chart se ha movido, reemplaza la URL del repositorio por la del README. Mantén el comando, el --version y el archivo de valores en Git para que la instalación sea repetible.

Ajustes del servidor: grafana.ini

Todo lo que pondrías en grafana.ini va bajo la clave grafana.ini, organizado por secciones:

grafana.ini:
  server:
    root_url: https://grafana.example.com/
  users:
    allow_sign_up: false
  analytics:
    reporting_enabled: false
    check_for_updates: false
  log:
    mode: console

Los valores que no deben subirse a Git pueden hacer referencia a variables de entorno o archivos, como en la guía de configuración (por ejemplo password: $__file{/etc/secrets/db/password}).

Credenciales de admin y otros secretos

Usa un Secret de Kubernetes existente en lugar de una contraseña en los valores:

admin:
  existingSecret: grafana-admin
  userKey: admin-user
  passwordKey: admin-password

envFromSecret: grafana-secrets   # cada clave se convierte en una variable de entorno

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secrets
  namespace: monitoring
stringData:
  POSTGRES_PASSWORD: change-me
  SLACK_WEBHOOK_URL: https://hooks.slack.com/services/XXX/YYY/ZZZ

Los archivos de provisioning pueden entonces usar $POSTGRES_PASSWORD y ${SLACK_WEBHOOK_URL}. Cifra el Secret con SOPS o sincronízalo con External Secrets en lugar de hacer commit de él como YAML plano (consulta la guía de secretos).

Data sources

La clave datasources se renderiza en un archivo de provisioning:

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Prometheus
        uid: prometheus
        type: prometheus
        access: proxy
        url: http://prometheus-server.monitoring.svc.cluster.local
        isDefault: true
        editable: false

Dashboards: tres formas

1. En línea desde archivos de la carpeta del chart. Declara un proveedor y lista los dashboards por origen:

dashboardProviders:
  dashboardproviders.yaml:
    apiVersion: 1
    providers:
      - name: default
        orgId: 1
        folder: ''
        type: file
        disableDeletion: false
        allowUiUpdates: false
        options:
          path: /var/lib/grafana/dashboards/default

dashboards:
  default:
    node-exporter:
      gnetId: 1860
      revision: 37
      datasource: Prometheus
    kubernetes-overview:
      json: |
        { "uid": "k8s-overview", "title": "Kubernetes Overview", "panels": [] }

Las entradas pueden venir de grafana.com (gnetId y revision), una URL o JSON en línea. La clave bajo dashboards (aquí default) debe coincidir con el nombre de la carpeta options.path del proveedor.

2. Desde ConfigMaps que gestionas tú mismo. Mantén el JSON de los dashboards en sus propios ConfigMaps (por ejemplo generados por Kustomize a partir del repositorio) y móntalos:

dashboardsConfigMaps:
  default: grafana-dashboards

3. Con el sidecar. Un contenedor sidecar vigila el clúster en busca de ConfigMaps (o Secrets) con una etiqueta y los carga como dashboards, de modo que cada equipo de aplicación puede distribuir su propio dashboard junto a sus manifiestos:

sidecar:
  dashboards:
    enabled: true
    label: grafana_dashboard
    labelValue: "1"
    searchNamespace: ALL
    folderAnnotation: grafana_folder
    provider:
      foldersFromFilesStructure: true
  datasources:
    enabled: true
    label: grafana_datasource
  alerts:
    enabled: true
    label: grafana_alert

apiVersion: v1
kind: ConfigMap
metadata:
  name: webapp-dashboard
  namespace: webapp
  labels:
    grafana_dashboard: "1"
  annotations:
    grafana_folder: Applications
data:
  webapp.json: |
    { "uid": "webapp-overview", "title": "Webapp Overview", "panels": [] }

El enfoque del sidecar es el que mejor escala entre equipos: nadie edita los valores de Grafana para añadir un dashboard.

Alertas

Los archivos de provisioning de alertas pueden venir de la clave alerting, usando los formatos YAML de la guía de alertas:

alerting:
  contactpoints.yaml:
    secret:
      apiVersion: 1
      contactPoints:
        - orgId: 1
          name: team-slack
          receivers:
            - uid: team-slack-1
              type: slack
              settings:
                url: ${SLACK_WEBHOOK_URL}
                recipient: '#alerts'
  policies.yaml:
    apiVersion: 1
    policies:
      - orgId: 1
        receiver: team-slack

El envoltorio secret: coloca ese archivo en un Secret en lugar de un ConfigMap. Consulta el values.yaml del chart para ver la forma exacta en tu versión. Las reglas de alertas pueden venir de la misma clave o del ajuste alerts del sidecar.

Persistencia y réplicas

persistence:
  enabled: true
  size: 5Gi
replicas: 1

SQLite sobre un volumen persistente soporta una sola réplica. Para alta disponibilidad, apunta Grafana a PostgreSQL mediante grafana.ini y aumenta replicas.

Despliega con Flux

Si usas Flux, el chart se convierte en un HelmRelease, y los valores de arriba van en spec.values:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: grafana
  namespace: monitoring
spec:
  interval: 10m
  chart:
    spec:
      chart: grafana
      version: "<chart-version>"
      sourceRef:
        kind: HelmRepository
        name: grafana
        namespace: flux-system
  valuesFrom:
    - kind: ConfigMap
      name: grafana-values

Un cambio en los valores en Git se despliega automáticamente. Consulta la guía de Helm de la serie de Flux para HelmRepository, remediation y detección de desviaciones.

Verifica

kubectl get pods -n monitoring
kubectl port-forward svc/grafana 3000:80 -n monitoring &
curl -s http://localhost:3000/api/health
kubectl logs deploy/grafana -n monitoring -c grafana | grep -i provisioning

Si falta un dashboard o un data source, revisa primero las líneas de log de provisioning y luego los logs del sidecar (-c grafana-sc-dashboard) en busca de problemas de etiquetas o namespaces.