Cross-dashboard variables Grafana : partager des variables entre dashboards

1. Pourquoi partager des variables entre dashboards ? #

Le problème résolu, les deux portées et ce qui change par rapport aux variables locales.

Le problème #

Disponible dans : ✓ OSS ✓ Enterprise ✓ Cloud Fonction en public preview, sur activation

Une variable classique n'existe que dans le dashboard où vous l'avez créée. Avec trente dashboards filtrés par environnement, vous recréez trente fois la variable env. Ajouter une valeur comme recette impose trente modifications, et les écarts s'installent : env ici, environment là, prod d'un côté et production de l'autre.

Les cross-dashboard variables résolvent ce problème : vous définissez la variable une seule fois, puis plusieurs dashboards la réutilisent. Vous la modifiez à un seul endroit et tous les dashboards qui l'utilisent suivent.

Ne confondez pas. Les variables « globales » vues plus tôt dans ce chapitre sont les variables intégrées de Grafana, comme $__from ou $__interval. Ici, « global » désigne la portée d'une variable que vous créez vous-même.

Deux portées #

• Globale : proposée à tous les dashboards de l'organisation.
• Par dossier : proposée uniquement aux dashboards placés dans le même dossier.

Un sous-dossier n'hérite pas. Lors de nos tests, un dashboard placé dans un sous-dossier de Core metrics ne voyait aucune variable de ce dossier : seules les variables globales lui étaient proposées.

Locale ou partagée ? #

Gardez une variable locale quand elle n'a de sens que pour un seul dashboard, par exemple le choix d'un seuil d'affichage. Partagez ce qui décrit votre organisation : environnement, région, équipe, client.

2. Activer la fonctionnalité #

Feature toggle, Docker, vérification et statut de la fonctionnalité.

Un statut à connaître #

Fonctionnalité en public preview. Grafana Labs indique un support limité et de possibles ruptures de compatibilité avant la disponibilité générale. Testez-la d'abord hors production. La documentation ne précise pas de version minimale : cet article a été vérifié sur Grafana OSS 13.3.0.

La documentation la présente comme disponible sur Grafana Cloud, Enterprise et Open source. Sur Grafana Cloud, où vous n'avez pas accès au fichier de configuration, contactez le support.

Activer le toggle #

Dans le fichier de configuration, puis redémarrez Grafana :

# /etc/grafana/grafana.ini (ou custom.ini)
[feature_toggles]
grafana.dashboardGlobalVariables = true

Ou avec une variable d'environnement, pratique avec Docker :

docker run -d --name grafana -p 3000:3000 \
  -e GF_FEATURE_TOGGLES_ENABLE=grafana.dashboardGlobalVariables \
  grafana/grafana:13.3.0

Vérifiez ensuite que le toggle est actif (admin:admin est le compte par défaut d'une installation neuve : adaptez-le) :

curl -s -u admin:admin http://localhost:3000/api/frontend/settings \
  | jq '.featureToggles["grafana.dashboardGlobalVariables"]'
# true

Une entrée Variables apparaît alors dans le menu Dashboards.

3. Créer une variable partagée #

Le formulaire de Dashboards > Variables, champ par champ.

Pas à pas #

1. Ouvrez Dashboards > Variables.
2. Cliquez sur New variable.
3. Choisissez la portée dans Folder, puis le Variable type.
4. Renseignez le nom, puis les options du type choisi.
5. Cliquez sur Save.

Le piège du champ Folder. Le champ s'appelle « Folder » même pour une variable globale : c'est le dossier racine Dashboards, sélectionné par défaut, qui rend la variable globale. Choisissez un autre dossier pour limiter sa portée.

Les champs #

Les types disponibles #

Le formulaire de Grafana 13.3.0 propose aussi Filter and Group by, que la page de documentation ne cite pas.

Valeurs libres activées par défaut. Sur une variable Custom, Allow custom values est coché par défaut : un utilisateur peut donc saisir une valeur hors liste. Décochez-le si la variable sert à imposer une nomenclature.

La liste des variables #

La page Dashboards > Variables regroupe les variables : celles d'un dossier apparaissent sous celui-ci, les globales à la racine de la liste.

4. Rattacher la variable à un dashboard #

L'étape indispensable, souvent oubliée.

Créer ne suffit pas #

Une variable créée n'apparaît pas toute seule dans vos dashboards. Tant qu'elle n'est pas rattachée, le sélecteur est absent et $env reste affiché tel quel, sans être remplacé :

Pas à pas #

1. Ouvrez le dashboard et cliquez sur Edit.
2. Cliquez sur le bouton + en haut du dashboard, puis sur Variable. L'icône Add new element de la barre latérale donne le même résultat.

3. Choisissez Global or folder variable.

4. Cochez les variables voulues, ou All global et All folder pour prendre toutes celles de chaque portée.
5. Cliquez sur Save, ajoutez éventuellement une description, confirmez avec Save, puis cliquez sur Exit edit.

Le panneau affiche maintenant les valeurs sélectionnées :

Pour retirer une variable, repassez par la barre latérale du dashboard. Pour la modifier, passez par Dashboards > Variables.

Liste explicite ou « All » ? #

Attention à « All ». Avec All global, toute nouvelle variable globale ajoute un sélecteur à ces dashboards dès leur prochaine ouverture.

5. Utiliser la variable au quotidien #

Requêtes, titres, URL et modification centralisée.

Dans les requêtes et les titres #

Une fois rattachée, la variable s'utilise comme n'importe quelle autre.

# Prometheus : une valeur
rate(http_requests_total{env="$env", service="$service"}[5m])

# Prometheus : variable multi-valeur (env=~ et le format regex)
sum by (service) (rate(http_requests_total{env=~"${env:regex}"}[5m]))

Avec Loki :

{env="$env", service="$service"} |= "error"

Dans un titre de panneau :

Erreurs de ${service} en ${env}

Dans l'URL #

Le préfixe var- fonctionne aussi : un lien présélectionne les valeurs, ce qui est utile dans une alerte ou un runbook.

https://grafana.example.com/d/core1?var-env=dev&var-service=batch

Modifier une seule fois #

Nous avons ajouté la valeur recette et changé le libellé dans Dashboards > Variables : les deux changements sont apparus dans le dashboard au rechargement, sans le modifier ni l'enregistrer.

La contrepartie. Une erreur se propage aussi partout. Avant de renommer ou de supprimer une variable partagée, repérez les dashboards qui l'utilisent : renommer revient à casser le $env de leurs requêtes.

6. Conflits, déplacements et droits #

Ce que la documentation ne précise pas, testé sur Grafana 13.3.0.

Conflits de noms #

La documentation ne dit rien des conflits. Voici ce que nous avons observé. Deux variables d'une même portée ne peuvent pas avoir le même nom : le formulaire le refuse (A variable with this name already exists in the selected folder) et l'API répond 409. Une variable de dossier peut en revanche porter le nom d'une variable globale.

• Dans le dossier concerné, la variable globale env disparaît de la liste au profit de celle du dossier.
• Si le dashboard définit aussi une variable locale env, c'est la locale qui s'applique : la valeur partagée est ignorée.

Conseil. Évitez ces homonymes. Un même nom qui donne des valeurs différentes selon le dossier rend les dashboards difficiles à comprendre.

Déplacer ou supprimer #

Pas d'avertissement. Ces cas ne produisent aucune alerte dans Grafana : vérifiez vos dashboards après un déplacement de dossier ou une suppression.

Qui peut faire quoi ? #

Résultats obtenus avec l'API et les rôles d'organisation par défaut, sans permission de dossier particulière. Vérifiez-les sur votre instance si vous avez personnalisé les droits.

7. Automatiser avec l'API #

Lister et créer des variables, et lire le rattachement d'un dashboard.

Avant de commencer #

API en bêta. La page de documentation ne décrit ni API ni provisioning. Les appels ci-dessous sont ceux que nous avons validés sur Grafana 13.3.0, avec la version v2beta1 : ils peuvent changer avant la disponibilité générale. Ne les intégrez pas à une automatisation critique sans test à chaque montée de version.

Lister #

curl -s -u admin:admin \
  http://localhost:3000/apis/dashboard.grafana.app/v2beta1/namespaces/default/variables \
  | jq -r '.items[] | [.metadata.name, .spec.kind, (.metadata.annotations["grafana.app/folder"] // "global")] | @tsv'
# env                     CustomVariable    global
# region                  ConstantVariable  global
# service--core-metrics   CustomVariable    core-metrics

Créer une variable globale #

curl -s -u admin:admin -H 'Content-Type: application/json' \
  http://localhost:3000/apis/dashboard.grafana.app/v2beta1/namespaces/default/variables -d '{
  "apiVersion": "dashboard.grafana.app/v2beta1",
  "kind": "Variable",
  "metadata": {"name": "region"},
  "spec": {"kind": "ConstantVariable", "spec": {
    "name": "region",
    "query": "eu-west-3",
    "current": {"text": "eu-west-3", "value": "eu-west-3"},
    "hide": "hideVariable",
    "skipUrlSync": true
  }}
}'

Créer une variable de dossier #

Le nom technique suit la forme <nom>--<uid du dossier> : tout autre nom est refusé avec une erreur 400. Le nom à utiliser dans les requêtes reste spec.spec.name.

curl -s -u admin:admin -H 'Content-Type: application/json' \
  http://localhost:3000/apis/dashboard.grafana.app/v2beta1/namespaces/default/variables -d '{
  "apiVersion": "dashboard.grafana.app/v2beta1",
  "kind": "Variable",
  "metadata": {
    "name": "service--core-metrics",
    "annotations": {"grafana.app/folder": "core-metrics"},
    "labels": {"grafana.app/folder": "core-metrics"}
  },
  "spec": {"kind": "CustomVariable", "spec": {
    "name": "service",
    "query": "api,front,batch",
    "current": {"text": "api", "value": "api"},
    "options": [],
    "multi": false,
    "includeAll": false,
    "label": "Service",
    "hide": "dontHide",
    "skipUrlSync": false,
    "allowCustomValue": false
  }}
}'

Où est stocké le rattachement ? #

Le rattachement ne figure pas dans la liste variables du dashboard, qui reste vide : il est stocké dans une annotation. Si vous versionnez vos dashboards, vérifiez que votre outil conserve cette annotation.

curl -s -u admin:admin \
  http://localhost:3000/apis/dashboard.grafana.app/v2beta1/namespaces/default/dashboards/core1 \
  | jq -r '.metadata.annotations["grafana.app/useCrossDashboardVariables"]'
# {"global":["env"],"folder":["service"]}

La valeur vaut "all" avec All global ou All folder, et "none" si rien n'est rattaché.

8. Bonnes pratiques et dépannage #

Les réflexes à adopter, les erreurs fréquentes et un exercice.

Bonnes pratiques #

• Fixez une convention de nommage avant de créer la première variable : env, region, team.
• Réservez la portée globale à ce qui concerne vraiment toute l'organisation, et préférez le dossier pour le reste.
• Limitez le nombre de variables rattachées à un dashboard : trop de sélecteurs nuisent à la lecture.
• Décrivez chaque variable : le champ Description aide ceux qui ne l'ont pas créée.
• Testez sur une instance hors production : la fonctionnalité peut encore changer.

Dépannage #

À vous de jouer #

1. Lancez Grafana avec la commande Docker de la partie 2 et vérifiez le toggle.
2. Créez les dossiers Core metrics et Finance, avec un dashboard dans chacun et un panneau Text qui affiche env = $env.
3. Créez la variable globale env (type Custom, valeurs prod,preprod,dev).
4. Constatez que $env s'affiche tel quel, puis rattachez la variable aux deux dashboards.
5. Ajoutez la valeur recette dans Dashboards > Variables et vérifiez qu'elle apparaît dans les deux dashboards.
6. Créez dans Finance une variable env de valeurs x,y et observez ce qui change dans la liste de rattachement de chaque dossier.

Sources #

• Grafana : Cross-dashboard variables
• Grafana : Add variables
• Grafana : Feature toggles

Documentation consultée et comportements testés en novembre 2026 sur Grafana OSS 13.3.0.