Écrire le JSON des tableaux de bord à la main ne passe pas à l’échelle, et l’exporter depuis l’interface laisse celle-ci comme véritable source. Les outils d’observabilité as code de Grafana répondent aux deux problèmes : le Foundation SDK génère des tableaux de bord à partir de code typé, Git Sync fait lire et écrire les tableaux de bord par Grafana dans un dépôt Git, et la CLI gcx envoie et récupère des ressources depuis le terminal. Plusieurs de ces fonctionnalités sont récentes et certaines API sont marquées alpha ; consultez donc la documentation de votre version.

Générer des tableaux de bord avec le Foundation SDK

Le Foundation SDK fournit des builders pour les tableaux de bord, les panneaux et les requêtes en Go, TypeScript, Python, PHP et Java. Vous décrivez un tableau de bord dans un langage typé, et l’appel à build() produit le JSON du tableau de bord. Comme c’est du code, vous bénéficiez de vérifications à la compilation, de la réutilisation (une fonction qui construit une ligne standard de panneaux de service) et d’une relecture de code normale.

Installez-le pour votre langage, par exemple :

# Go
go get github.com/grafana/grafana-foundation-sdk/go@latest

# TypeScript
npm install @grafana/grafana-foundation-sdk

Les paquets Python, PHP et Java sont listés dans la documentation du SDK. Il cible Grafana 10 et les versions plus récentes.

Un workflow typique :

1. Écrivez un petit programme qui définit les tableaux de bord et écrit le JSON de chacun dans dashboards/<name>.json.
2. Exécutez-le en CI.
3. Commitez le JSON généré, ou publiez-le comme artefact de build.
4. Livrez le JSON avec le mécanisme que vous utilisez déjà : un dossier de fournisseur, une ConfigMap, une ressource GrafanaDashboard, Terraform ou Git Sync.

# esquisse d'un job de CI
steps:
  - run: npm ci
  - run: npx tsx dashboards/generate.ts --out dashboards/generated
  - run: git diff --exit-code dashboards/generated   # échoue si les fichiers générés sont périmés

La vérification git diff --exit-code garantit que personne ne modifie le JSON généré à la main et que le code et la sortie restent synchronisés.

Git Sync

Git Sync permet à Grafana de stocker les tableaux de bord sous forme de JSON dans un dépôt Git. Les changements circulent dans les deux sens : une modification dans l’interface de Grafana devient un commit ou une pull request, et un changement fusionné dans le dépôt apparaît dans Grafana. Grafana interroge le dépôt toutes les 60 secondes par défaut, et un webhook fait arriver les mises à jour presque immédiatement. Git Sync est en disponibilité générale dans Grafana 13 sur toutes les éditions. Il prend en charge GitHub (avec authentification par App), GitHub Enterprise, GitLab, Bitbucket et Git simple via un type de dépôt « Pure Git ».

Vous pouvez le configurer entièrement as code avec une ressource Repository. Créez repository.yaml :

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  title: My Repository
  type: github
  github:
    url: https://github.com/<org>/<repo>
    branch: main
    path: grafana/
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
secure:
  token:
    create: '<git-personal-access-token>'

Notes sur les champs :

• type vaut github, githubEnterprise, gitlab, bitbucket ou git, et chacun a son propre bloc. Bitbucket et Git simple nécessitent aussi un tokenUser.
• path est le dossier du dépôt dont Grafana est propriétaire.
• workflows contrôle ce que font les enregistrements depuis l’interface : write commite directement sur la branche, et branch ouvre une pull request.
• sync.target vaut folder (par défaut) ou folderless.
• secure.token porte l’identifiant, qui est donc stocké comme secret et non dans la spec. À la place d’un jeton, vous pouvez utiliser une connexion via GitHub App ou OAuth app avec spec.connection.name ; elles nécessitent un connection.yaml séparé.
• La version d’API est v0alpha1 ; les noms de champs peuvent donc changer d’une version à l’autre.

Appliquez-le avec gcx (section suivante), ou via l’interface de Grafana si vous préférez.

Ce que Git Sync fait de mieux : permettre aux auteurs travaillant dans l’interface et aux ingénieurs orientés Git de partager une seule source de vérité, avec une relecture par pull request pour chaque changement. Lisez la page des limitations d’usage avant de l’adopter pour une grande instance, car le provisionnement d’un grand nombre de tableaux de bord pose des questions de performance.

La CLI gcx

gcx est la ligne de commande de Grafana pour travailler avec les ressources et, sur Grafana Cloud, avec d’autres produits. Elle fonctionne avec Grafana Cloud et avec Grafana open source ou Enterprise 12 et versions ultérieures, et remplace l’ancien outil grafanactl (la migration consiste surtout à renommer la commande, et grafanactl resources serve devient gcx dev serve). Installez-la depuis le dépôt du projet et configurez un contexte avec l’URL de votre Grafana et un jeton, comme décrit dans sa documentation.

Commandes courantes :

# envoyer les fichiers de ressources locaux vers Grafana
gcx resources push --path ./resources

# lister ce qui existe, ou inspecter une ressource
gcx resources get repositories
gcx resources get repository/my-repo -o yaml

# modifier ou supprimer
gcx resources edit repository/my-repo
gcx resources delete repository/my-repo

# prévisualiser les tableaux de bord en direct pendant le développement
gcx dev serve

Utilisez-la en CI pour envoyer les définitions de ressources depuis le dépôt, ou en local pendant que vous construisez des tableaux de bord avec le SDK.

Choisir entre les approches

Situation	Recourir à
Nombreux tableaux de bord similaires, ou blocs réutilisables	Foundation SDK, livré par n’importe quel mécanisme
Les auteurs travaillent dans l’interface mais vous voulez Git comme référence	Git Sync
GitOps Kubernetes, un objet par tableau de bord	Grafana Operator
Automatisation de toute la plateforme, y compris équipes et permissions	Terraform
Un seul Grafana, fichiers JSON statiques	Simple dossier de fournisseur

Elles se combinent bien : générez le JSON avec le SDK, commitez-le dans un dépôt, et laissez Git Sync ou un dossier de fournisseur le livrer.

Vérifier

gcx resources get repositories
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  "http://localhost:3000/api/search?type=dash-db" | jq '.[] | {title, folderTitle}'

Pour les problèmes de synchronisation d’un dépôt, consultez le statut du dépôt dans Grafana (sous Administration, puis Provisioning) et le log du serveur Grafana. Les problèmes typiques sont un jeton expiré, une mauvaise branche ou un mauvais chemin, et un webhook qui ne peut pas atteindre Grafana.