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.planSecrets 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.tfvarsversionné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 #
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 validateComplé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 ? #
| Outil | Point fort |
|---|---|
| Provisioning par fichiers | simple, au démarrage de Grafana ; dashboards en lecture seule |
| Git Sync | synchronisation bidirectionnelle avec un dépôt, modification depuis l'interface puis pull request |
| Terraform | tout Grafana (permissions, équipes, alertes) avec plan et état |
| API HTTP et scripts | migrations, exports en masse, outils maison |
Commandes à connaître #
Commandes à connaître
GET /api/search?type=dash-db: rechercher des dashboardsGET /api/dashboards/uid/:uid: exporter un dashboardPOST /api/dashboards/db: créer ou mettre à jour un dashboardGET /api/dashboards/uid/:uid/versions: historique d'un dashboardterraform plan -var-file=env/prod.tfvars: prévisualiser les changements en productionterraform import grafana_dashboard.api <uid>: reprendre un dashboard existant dans Terraform
