🔍 Introduction

Synchroniser des dashboards Grafana sur plusieurs environnements — développement, production, staging — est souvent source d’incohérences. Comment s'assurer que tous les environnements ont les bons dashboards, à jour, sans manipulations manuelles ?

Dans cet article, je présente une méthode automatisée et modulaire, basée sur :

• OpenTofu (fork libre et communautaire de Terraform)

• Terragrunt (wrapper Terraform permettant de booster les fonctionnalités de Terraform)

• GitLab pour la partie CI/CD et le stockage des fichiers d’état avec la feature built-in backend Terraform GitLab HTTP.

Le tout est structuré autour de deux dépôts GitLab :

1. Un dépôt dédié aux dashboards Grafana au format JSON

2. Un autre qui orchestre la synchronisation automatisée avec Grafana

La version de GitLab utilisée dans ce projet est une version Premium.
La feature de partage des artifacts entre projets needs:project présent dans le fichier .gitlab-ci.yml du projet grafana-sync n'est pas disponible dans la version OSS de GitLab.

Les technologies utilisées

OpenTofu (fork Terraform)

OpenTofu est un outil d'infrastructure as code (IaC) open source, issu d’un fork communautaire de Terraform (version 1.5.5), après le changement de licence de Terraform par HashiCorp (passage à la BSL).

Il permet de décrire, provisionner et gérer des infrastructures (serveurs, bases de données, services cloud, etc.) de façon déclarative, à l’aide de fichiers de configuration (.tf ou .tf.json).

Terragrunt

Terragrunt est un outil open source écrit en Go, conçu pour simplifier et améliorer l'utilisation de Terraform ou OpenTofu (dans notre cas).

Il agit comme un wrapper autour de Terraform/OpenTofu pour :

• Réduire la duplication de code dans les configurations (DRY)

• Faciliter la gestion de projets multi-environnements et multi-modules

• Gérer plus facilement les backends distants (comme un bucket S3, un backend HTTP, etc.)

• Orchestrer des déploiements complexes en chaînant plusieurs modules

Organisation des projets GitLab

1. Dépôt grafana-dashboards/ – La source des dashboards

Ce dépôt contient les dashboards Grafana organisés par dossier, sous forme de fichiers JSON.

dashboards/
├── k8s_dashboards/
│ └── K8S.json
├── misc_dashboards/
│ ├── blackbox.json
│ └── coredns.json

Pipeline .gitlab-ci.yml

Ce pipeline comprend deux étapes clés :

• prepare_dashboards : Créer un artifact des différents dashboards trouvés.

• trigger_sync : déclenche automatiquement un pipeline dans le second dépôt (grafana-sync) via l’API GitLab en y apportant l’artifact généré par le job GitLab précédent.

2. Dépôt grafana-sync/ – Le moteur de synchronisation

Ce dépôt contient :

• Un script shell pour générer dynamiquement la configuration Terragrunt pour chaque organisation Grafana.

• Les fichiers Terraform pour la création et l’édition des dossiers et dashboards Grafana pour chaque organisation.

• Un pipeline CI/CD pour exécuter le tout.

Il est nécessaire de définir 2 variables ou plus selon le nombre d’organisations Grafana à gérer.
Pour notre exemple, seules 2 organisations ont synchronisées, il est nécessaire d’y apporter au projet GitLab les API Keys Grafana de chaque organisation sous forme de variable secrète :

• GRAFANA_API_KEY_ORG1

• GRAFANA_API_KEY_ORG2

Les organisations sont définies dans le script generate_terragrunt.sh

# Définir les 2 organisations Grafana
ORGS=(
  "rec|${GRAFANA_API_KEY_ORG1}"
  "prod|${GRAFANA_API_KEY_ORG2}"
)

Le cœur du système : le script generate_terragrunt.sh

Ce script joue un rôle central : il parse les différents dashboards JSON du dépôt grafana-dashboards et les tranforme en une arborescence de blocs Terragrunt exécutables.

Fonctionnement détaillé :

1. Lecture des fichiers JSON Il parcourt récursivement les répertoires dashboards/* pour identifier chaque fichier .json.

2. Création de la structure d’exécution dans un dossier synced_dashboards
   Génération de l’arborescence suivante lors de l’exécution de la pipeline CICD :

    synced_dashboards/
    ├── prod
    │   ├── k8s_dashboards
    │   │   └── K8S.json
    │   ├── misc_dashboards
    │   │   ├── blackbox.json
    │   │   └── coredns.json
    │   └── terragrunt.hcl
    └── rec
        ├── k8s_dashboards
        │   └── K8S.json
        ├── misc_dashboards
        │   ├── blackbox.json
        │   └── coredns.json
        └── terragrunt.hcl
   
    7 directories, 8 files
   

3. Génération des blocs Terragrunt
   Pour chaque organisation Grafana (rec, prod), il génère un fichier terragrunt.hcl de cette forme :

    terraform {
      source = "../../terraform"
    }
   
    remote_state {
      backend = "http"
   
      config = {
        address        = "https://gitlab.com/api/v4/projects/71693011/terraform/state/rec"
        lock_address   = "https://gitlab.com/api/v4/projects/71693011/terraform/state/rec/lock"
        unlock_address = "https://gitlab.com/api/v4/projects/71693011/terraform/state/rec/lock"
        lock_method    = "POST"
        unlock_method  = "DELETE"
        username       = "gitlab-ci-token"
        password       = ""
      }
    }
   
    inputs = {
      grafana_url     = "https://moninstance-grafana.local"
      grafana_api_key = "abcdefgh"
      grafana_folder = ""
      gitlab_token    = ""
    }
   

4. Gestion du backend GitLab HTTP
   Terragrunt, dans chacun de ses fichiers .hcl utilise le backend GitLab HTTP comme stockage d’état distant (un fichier d’état par organisation Grafana).

Déroulé complet du workflow CI/CD

Voici comment tout s’enchaîne :

1. Un développeur modifie un fichier .json dans grafana-dashboards/

2. Le pipeline CI créé un artifcats à parti des fichiers json et déclenche un pipeline dans grafana-sync/

3. Le pipeline de grafana-sync/ :

• Lance le script generate_terragrunt.sh

• Génére la configuration Terragrunt pour chaque organisation Grafana

• Applique chaque bloc via Terragrunt

• Pour chaque fichier, il extrait :

  • Le nom du dossier (k8s_dashboards, misc_dashboards, etc.)

  • Le nom du dashboard (à partir du nom du fichier)

4. Les dossiers et dashboards sont créés ou mis à jour dans Grafana 🎉

5. Les fichiers d’état sont stockés sur GitLab dans le backend HTTP Terraform du projet grafana-dashboards

Avantages de cette approche

• Automatisation complète : plus aucun déploiement manuel de dashboards

• Multi-environnements synchronisés : chaque environnement est identique

• Factorisation propre avec Terragrunt

• Déploiement dynamique : une simple modification de JSON déclenche toute la chaîne

• Versionning clair : tout est traçable dans GitLab

Conclusion

Cette solution montre la puissance combinée de Terragrunt et OpenTofu (Terrraform) pour orchestrer la synchronisation automatique de dashboards Grafana à partir de fichiers JSON, tout en gardant une séparation claire entre la source de vérité (les fichiers JSON) et le moteur de déploiement (grafana-sync).

Grâce à cette architecture, maintenir plusieurs environnements Grafana devient simple, fiable et reproductible — un vrai confort opérationnel.

Références

• Dépôt dédié aux dashboards Grafana au format JSON

• Dépôt dédié à la synchronisation automatisée avec Grafana