RousselTMLEARNING

Observabilité

Automatiser Grafana : API HTTP, Terraform et cycle de vie des dashboards

Industrialiser Grafana : API HTTP (dossiers, dashboards, utilisateurs, sources), fournisseur Terraform, dashboards en JSON dans Git, déploiement DEV, QUALIF et PROD, secrets, permissions, tests et cycle de vie.

1. L'API HTTP de Grafana #

Tout ce que fait l'interface est disponible par l'API.

Authentification #

Disponible dans : ✓ OSS ✓ Enterprise ✓ Cloud

Chaque appel porte un jeton de compte de service : Authorization: Bearer glsa_…. Le rôle du compte de service limite ce que le script peut faire.

Les appels les plus utiles #

export GRAFANA=https://grafana-dev.exemple.fr TOKEN=glsa_xxx
H=(-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json')
curl -s "${H[@]}" "$GRAFANA/api/search?type=dash-db&query=api" | jq -r '.[] | "\(.uid)  \(.title)"'   # rechercher
curl -s "${H[@]}" $GRAFANA/api/dashboards/uid/api-overview | jq '.dashboard' > api-overview.json  # exporter
# importer (création ou mise à jour) dans un dossier, avec un message d'historique
jq -n --slurpfile d api-overview.json '{dashboard: ($d[0] | .id = null), folderUid: "prod", overwrite: true, message: "import CI"}' \
  | curl -s "${H[@]}" -X POST $GRAFANA/api/dashboards/db -d @-
curl -s "${H[@]}" $GRAFANA/api/datasources | jq -r '.[] | "\(.uid) \(.type) \(.name)"'        # sources de données
curl -s "${H[@]}" $GRAFANA/api/dashboards/uid/api-overview/versions | jq '.[0:3]'              # historique
À savoir : Grafana 12 et 13 exposent aussi les dashboards et dossiers par de nouvelles API de type Kubernetes (/apis/dashboard.grafana.app/…), utilisées par Git Sync et le nouvel outil en ligne de commande. Les API classiques /api/… restent disponibles.

2. Terraform #

Décrire Grafana comme une infrastructure.

Le fournisseur grafana/grafana #

Le fournisseur Terraform officiel gère dossiers, dashboards, sources de données, équipes, permissions, comptes de service, règles d'alerte et points de contact, pour Grafana OSS, Enterprise et Cloud.

terraform {
  required_providers {
    grafana = { source = "grafana/grafana" }
  }
}
provider "grafana" {
  url  = var.grafana_url
  auth = var.grafana_token          # jeton de compte de service, fourni par TF_VAR_grafana_token
}
resource "grafana_folder" "prod" {
  title = "Production"
}
resource "grafana_team" "prod" {
  name = "Production"
}
resource "grafana_folder_permission" "prod" {
  folder_uid = grafana_folder.prod.uid
  permissions {
    team_id    = grafana_team.prod.id
    permission = "Edit"
  }
}
resource "grafana_data_source" "prometheus" {
  type = "prometheus"
  name = "Prometheus"
  url  = var.prometheus_url
}
resource "grafana_dashboard" "api" {
  folder      = grafana_folder.prod.uid
  config_json = file("${path.module}/dashboards/api-overview.json")
}

Plusieurs environnements #

# Un même code, un fichier de variables par environnement
terraform workspace select dev   || terraform workspace new dev
terraform apply -var-file=env/dev.tfvars
terraform workspace select prod  || terraform workspace new prod
terraform plan  -var-file=env/prod.tfvars -out=prod.plan   # relu et approuvé dans la merge request
terraform apply prod.plan

Secrets dans les déploiements #

  • Jetons et mots de passe passent par des variables d'environnement (TF_VAR_…) alimentées par le coffre de la CI ou Vault, jamais par les fichiers .tfvars versionnés.
  • Le fichier d'état Terraform contient des secrets : stockez-le dans un backend distant chiffré, à accès restreint.
  • Les sources de données diffèrent par environnement : dans le JSON des dashboards, utilisez une variable de type data source plutôt qu'un UID fixe.

3. Cycle de vie des dashboards #

Git, revue, validation et promotion.

Le pipeline #

Pipeline de déploiement des dashboards

Tester avant de déployer #

# Validation rapide dans la CI avant tout déploiement
for f in dashboards/*.json; do
  jq empty "$f" || exit 1                                          # JSON valide
  jq -e '.uid and .title' "$f" >/dev/null || { echo "$f : uid ou titre manquant"; exit 1; }
  jq -e '[.. | .datasource? | objects | select(.uid != null and (.uid | startswith("${") | not))] | length == 0' "$f" >/dev/null \
    || echo "$f : source de données codée en dur (utilisez une variable)"
done
terraform fmt -check && terraform validate

Complétez avec dashboard-linter (projet Grafana) pour les bonnes pratiques de requêtes, et un dashboard de recette déployé en DEV et vérifié avant la promotion.

Quel outil pour quel besoin ? #

OutilPoint fort
Provisioning par fichierssimple, au démarrage de Grafana ; dashboards en lecture seule
Git Syncsynchronisation bidirectionnelle avec un dépôt, modification depuis l'interface puis pull request
Terraformtout Grafana (permissions, équipes, alertes) avec plan et état
API HTTP et scriptsmigrations, exports en masse, outils maison

Commandes à connaître #

Commandes à connaître
  • GET /api/search?type=dash-db : rechercher des dashboards
  • GET /api/dashboards/uid/:uid : exporter un dashboard
  • POST /api/dashboards/db : créer ou mettre à jour un dashboard
  • GET /api/dashboards/uid/:uid/versions : historique d'un dashboard
  • terraform plan -var-file=env/prod.tfvars : prévisualiser les changements en production
  • terraform import grafana_dashboard.api <uid> : reprendre un dashboard existant dans Terraform

Articles liés

Administration et sécurité de Grafana : organisations, équipes, RBAC, comptes de service et authentification

Administrer Grafana en entreprise : organisations, équipes, dossiers, rôles et RBAC, permissions des sources …

Dashboard engineering : visualisations d'état, annotations, panneaux de bibliothèque et navigation

Concevoir des dashboards professionnels : State timeline, Status history, Node graph, annotations, panneaux d…

Exploiter Grafana : métriques internes, santé, logs, performances et sauvegardes

Savoir exploiter Grafana : endpoint /metrics et /api/health, logs, requêtes lentes, performances des dashboar…

Pour aller plus loin

Soutenir

♥ SOUTENIR

Soutenez RousselTM Learning

Les formations, articles, TP et attestations restent gratuits et sans publicité intrusive. Une contribution libre, du montant de votre choix, finance l’hébergement, les environnements de TP et l’écriture de nouveaux contenus.

Contribuer avec PayPal Montant libre · carte bancaire ou compte PayPalEn savoir plus
QR code PayPal
Ou scannez ce QR code avec votre téléphone

Merci, chaque contribution compte !