graph-go est un mappeur d'infrastructure en ligne de commande. Il découvre automatiquement votre infrastructure en se connectant au démon Docker, en inspectant les conteneurs en cours d'exécution et en sondant les bases de données et les services de stockage. L'interface utilisateur est servie par le backend et reflète l'état réel du backend — pas d'inventaire manuel nécessaire.

Étiquettes Docker

graph-go respecte un petit ensemble d'étiquettes de conteneur graphgo.* (définissez-les sur tout conteneur que vous souhaitez contrôler) :

Utilisez-les pour rattraper les conteneurs mal classifiés, pointer graph-go vers un DSN personnalisé, ou masquer un conteneur du graphe sans le supprimer.

Démarrage rapide — testez-le en 30 secondes

Lancez la pile de démonstration préconfigurée avec la CLI. C'est le moyen le plus rapide de voir graph-go dans un environnement réaliste et le chemin d'intégration prévu pour les nouveaux utilisateurs :

git clone https://github.com/guilherme-grimm/graph-go.git
cd graph-go
go run ./cmd/app demo

Ouvrez http://localhost:8080. La commande s'exécute attachée via Docker Compose. Appuyez sur Ctrl+C pour arrêter la session attachée.

La première exécution peut prendre plusieurs minutes sur une machine froide car Docker peut avoir besoin de télécharger les images de base et de construire les images de démonstration locales. Les exécutions suivantes sont beaucoup plus rapides.

La pile de démonstration s'attend à ce que les ports hôtes suivants soient libres : 8080, 5432, 27017, 9000, et 9001.

Si vous avez besoin d'un démontage explicite après :

docker compose -f docker-compose.demo.yml down

Exécution contre votre propre pile

Un conteneur, un port. Montez le socket Docker en lecture seule et graph-go découvre automatiquement tout ce qui tourne sur l'hôte :

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

graph-go ne fait que lire le socket Docker. Le flag :ro impose cela — conservez-le.

Ouvrez http://localhost:8080. L'auto‑découverte gère les conteneurs Docker et (lorsqu'un kubeconfig ou un compte de service in‑cluster est présent) les ressources Kubernetes sans aucun fichier de configuration.

Pour les services qui vivent en dehors de Docker/Kubernetes (bases de données distantes, services cloud gérés), montez un fichier de configuration — voir Configuration.

Binaire pré‑compilé

Binaire unique autonome — l'interface utilisateur est intégrée, mais le point d'entrée reste la CLI.

# Linux amd64 (nécessite GitHub CLI ; parcourez les Releases pour d'autres plateformes)
gh release download --repo guilherme-grimm/graph-go --pattern 'graph-go_*_linux_amd64.tar.gz' --clobber
tar xzf graph-go_*_linux_amd64.tar.gz
./graph-go serve   # ou simplement `./graph-go` — c'est pareil

Ouvrez http://localhost:8080. Autres plateformes sur la page Releases.

Commandes

Flags globaux (s'appliquent à chaque sous‑commande) : --config, --log-level, --log-format. Voir graph-go <commande> --help pour la surface complète par commande.

Flux typique :

1. graph-go demo pour une démonstration locale réaliste.
2. graph-go serve pour exécuter contre votre propre infrastructure.
3. graph-go scan pour une automatisation ponctuelle, des exports ou des vérifications CI.

Ports

Configuration

L'auto‑découverte est le chemin. Montez le socket Docker et/ou exécutez à l'intérieur d'un cluster Kubernetes — graph-go découvre votre infrastructure sans aucun fichier de configuration nécessaire.

Utilisez la configuration YAML (conf/config.yaml) uniquement comme échappatoire pour les services qui ne sont pas atteignables via la découverte — bases de données distantes, services cloud gérés, points de terminaison externes. Voir conf/config.sample.yaml pour le schéma complet — exemples pour chaque adaptateur et chaque bloc de configuration (server, docker, kubernetes, connections).

Pour utiliser un fichier de configuration avec l'exécution Docker ci-dessus :

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/conf/config.yaml:/app/conf/config.yaml:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

Utilisation autorisée uniquement : graph-go est destiné à visualiser l'infrastructure que vous possédez ou pour laquelle vous avez la permission d'accéder. Ne le pointez pas vers des systèmes sans autorisation.

Aperçu de l'architecture

Backend (Go)

                          ┌─────────────────────────────────────┐
                          │         Interface Discoverer        │
                          │  Discover() · Watch() · Close()     │
                          └──────────┬──────────┬───────────────┘
                                     │          │
                          ┌──────────▼──┐  ┌────▼──────────────┐
                          │   Docker    │  │   Kubernetes       │
                          │  Discoverer │  │   Discoverer       │
                          │ (conteneurs,│  │ (informateurs,     │
                          │  classifie, │  │  pods,             │
                          │  événements)│  │  déploiements,     │
                          │              │  │  services, santé) │
                          └──────┬──────┘  └────┬──────────────┘
                                 │               │
                          ┌──────▼───────────────▼──────┐
                          │  Découverte parallèle +     │
                          │  Fusion (concaténer         │
                          │  ServiceInfo)               │
                          └──────────────┬──────────────┘
                                         │
Config (YAML) ──→ Fusion YAML ──────────▶│
                                         ▼
                          ┌─────────────────────────────┐
                          │     Registre d'adaptateurs   │
                          │  ├─ PostgreSQL → Tables + FK │
                          │  ├─ MongoDB   → Collections  │
                          │  ├─ MySQL     → Tables + FK  │
                          │  ├─ Redis     → Keyspaces    │
                          │  ├─ Elasticsearch → Indexes  │
                          │  ├─ S3        → Compartiments│
                          │  └─ HTTP      → Santé + dép. │
                          │                               │
                          │  + Topologie (nœuds/arêtes K8s)│
                          └──────────────┬───────────────┘
                                         ▼
                          Modèle de graphe (Nœuds + Arêtes)
                                         ▼
                          API REST + WebSocket (Temps réel)

Composants clés :

• Interface Discoverer : Contrat uniforme (Discover, Watch, Close) pour tous les backends de découverte — Docker et Kubernetes s'exécutent en parallèle, les résultats sont concaténés
• Découverte Docker : Inspecte les conteneurs, classifie les images, extrait les identifiants des variables d'environnement, surveille les événements Docker pour les changements de topologie en direct
• Découverte Kubernetes : Utilise les informateurs client-go avec un traitement d'événements anti-rebond ; découvre les espaces de noms, déploiements, StatefulSets, DaemonSets, Pods et Services avec cartographie de santé
• Adaptateurs : Implémentent l'interface Adapter pour sonder les bases de données et services de stockage
• Registre : Gère les adaptateurs et les ensembles de topologie, crée des nœuds parents au niveau service, agrège les données du graphe
• Cache : TTL de 30 secondes avec motif singleflight pour éviter la ruée vers le serveur
• WebSocket : Diffuse les mises à jour de santé toutes les 5 secondes

Frontend (React + TypeScript)

• Disposition en couloirs : Disposition tenant compte des espaces de noms avec classification en zones (système, infra, espaces de noms applicatifs)
• Conteneurs de groupes : Les espaces de noms K8s s'affichent sous forme de boîtes réductibles via le regroupement React Flow
• Inspecteur de nœuds : Panneau latéral affichant des métadonnées détaillées et des connexions
• Hook WebSocket : Mises à jour de santé en temps réel sans sondage

Hiérarchie des nœuds

Découvert par adaptateur :
  Nœud de service (postgres/mongodb/s3)
      └─ Nœud de base de données/compartiment
          └─ Nœud de table/collection/préfixe

Découvert par Kubernetes :
  Espace de noms (conteneur de groupe)
      └─ Déploiement / StatefulSet / DaemonSet
          └─ Pod
      └─ Service K8s ──routes_vers──→ Pod

Les arêtes représentent des relations (contient, clé_étrangère, routes_vers, etc.).

Stack technique

Backend :

• Go 1.25.6
• gorilla/mux (routage HTTP)
• k8s.io/client-go (découverte Kubernetes + informateurs)
• pgxpool (PostgreSQL)
• mongo-driver v2 (MongoDB)
• go-sql-driver/mysql (MySQL)
• go-redis/v9 (Redis)
• go-elasticsearch/v8 (Elasticsearch)
• AWS SDK v2 (S3)
• coder/websocket (WebSocket)
• testcontainers-go (tests d'intégration)

Frontend :

• TypeScript
• React 19
• @xyflow/react v12 (visualisation de graphe)
• Vite (outil de build)

Infrastructure :

• Docker + Docker Compose
• PostgreSQL 17
• MongoDB 7
• MySQL 8
• Redis 7
• Elasticsearch 8
• MinIO (compatible S3)

Tests

Tests unitaires

go test ./...

S'exécute sans Docker. Inclut des tests de fonctions pures et des tests de gestionnaires HTTP.

Tests d'intégration

go test -tags=integration -v -timeout=5m ./internal/adapters/...

Nécessite Docker. Utilise testcontainers-go pour lancer des instances de bases de données réelles (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) — pas de simulations.

Chaque adaptateur passe par la suite de tests contractuels (adaptertest.RunContractTests) qui valide :

• Cycle de vie connecter/déconnecter
• Découverte des nœuds/arêtes (identifiants uniques, références parent valides, types corrects)
• Métriques de santé (clé de statut, clés requises)

Exécuter les tests d'un seul adaptateur :

go test -tags=integration -v ./internal/adapters/redis/

Tous les tests

make test  # unitaires + vérification de type
go test -tags=integration -timeout=5m ./internal/adapters/...  # intégration

Référence API

GET /api/graph

Retourne le graphe complet de l'infrastructure (nœuds + arêtes).

Réponse :

{
  "data": {
    "nodes": [
      {
        "id": "service-postgres",
        "type": "postgres",
        "name": "postgres",
        "metadata": { "adapter": "postgres" },
        "health": "healthy"
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "service-postgres",
        "target": "pg-mydb",
        "type": "contains",
        "label": "contains"
      }
    ]
  }
}

GET /api/node/{id}

Retourne les détails d'un nœud spécifique.

GET /api/health

Retourne l'état de santé de l'adaptateur (ok/dégradé/erreur).

WS /websocket

Diffuse des mises à jour en temps réel. Deux types de messages sont émis, tous deux encapsulés comme { "type": "...", "payload": { ... } }. Il n'y a pas de champ timestamp — les clients déduisent l'ordre par arrivée.

health_update — envoyé pour chaque nœud une fois par cycle (toutes les 5 s). Les nœuds possédés par un adaptateur obtiennent leur santé via la recherche d'adaptateur ; les nœuds de topologie (par exemple, ressources Kubernetes) portent leur santé directement sur le nœud.

{
  "type": "health_update",
  "payload": {
    "nodeId": "service-postgres",
    "health": "healthy"
  }
}

health peut valoir healthy, degraded ou unhealthy.

graph_update — envoyé lorsque l'ensemble des identifiants de nœuds change (un nœud a été ajouté ou supprimé par la découverte). payload est vide ; les clients doivent re‑récupérer /api/graph.

{
  "type": "graph_update",
  "payload": {}
}

Ajouter un nouvel adaptateur

1. Créer un paquet d'adaptateur dans internal/adapters/{nom}/
2. Implémenter l'interface Adapter :
   root@kitploit:~

   type Adapter interface {
       Connect(config ConnectionConfig) error
       Discover() ([]nodes.Node, []edges.Edge, error)
       Health() (HealthMetrics, error)
       Close() error
   }
   

3. S'enregistrer via init() avec adapters.RegisterFactory("nom", ...)
4. Ajouter des tests d'intégration (obligatoire) — créer {nom}_integration_test.go avec :
   • Balise de build //go:build integration
   • TestMain utilisant testcontainers-go pour lancer une instance réelle
   • Amorcer des données représentatives
   • Appeler adaptertest.RunContractTests pour valider le contrat de l'interface
   • Ajouter des tests spécifiques à l'adaptateur (filtrage, format d'ID, métadonnées, etc.)
5. Importer l'adaptateur dans internal/server/server.go (import vide pour )

Ajouter un nouveau découvreur

Les découvreurs se trouvent dans internal/discovery/{nom}/ et implémentent l'interface Discoverer :

type Discoverer interface {
    Name() string
    Discover(ctx context.Context) ([]ServiceInfo, error)
    Watch(ctx context.Context, onChange func()) error
    Close() error
}

1. Créer un paquet découvreur dans internal/discovery/{nom}/
2. Implémenter l'interface Discoverer — retourner []ServiceInfo depuis Discover(). Les découvreurs producteurs de topologie (comme K8s) remplissent directement Nodes/Edges ; ceux orientés adaptateur (comme Docker) remplissent Config pour le pont adaptateur.
3. Câbler dans le serveur dans internal/server/server.go — ajouter une fonction build{Nom}Discovery() et l'appeler aux côtés des découvreurs existants.
4. Ajouter des tests d'intégration avec //go:build integration — utiliser une infrastructure réelle (kind/k3d pour K8s, testcontainers pour les autres). Pas de simulations.

Voir CONTRIBUTING.md pour des conseils détaillés.

Contribuer

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md pour les directives concernant :

• Configuration de développement
• Conventions de style de code
• Comment ajouter de nouveaux adaptateurs
• Soumettre des demandes de tirage

Portée d'utilisation et éthique

Utilisation prévue :

• Visualiser et surveiller l'infrastructure que vous possédez ou pour laquelle vous avez l'autorisation d'accéder
• Tableaux de bord DevOps et cartographie de topologie
• Documentation d'infrastructure et intégration
• Explorer les schémas et relations de bases de données

Non destiné à :

• Scan ou reconnaissance non autorisée de systèmes
• Tests de sécurité sans autorisation explicite
• Accéder à des systèmes que vous ne possédez ou ne contrôlez pas

Les utilisateurs sont responsables de s'assurer qu'ils disposent des autorisations appropriées avant de connecter graph-go à une infrastructure.

Licence

Ce projet est sous licence GNU Affero General Public License v3.0 (AGPL-3.0).

Voir le fichier LICENSE pour les détails. AGPL exige que les versions modifiées utilisées sur un réseau soient également open‑source.

CI/CD & Releases

Le projet utilise GitHub Actions pour l'intégration continue et les releases automatisées.

• CI s'exécute à chaque push/PR sur main — tests unitaires backend, tests d'intégration (testcontainers) et build frontend
• Releases sont déclenchées par des tags de version (v*) et produisent :
  • Binaires multiplateformes (Linux, macOS, Windows) via GoReleaser
  • Image Docker unique poussée vers ghcr.io/guilherme-grimm/graph-go

Pour créer une release :

git tag v0.1.0
git push --tags

Feuille de route

• Auto‑découverte Docker
• Surveillance de santé des services HTTP
• Adaptateur MySQL
• Adaptateur Redis
• Adaptateur Elasticsearch
• Tests d'intégration avec testcontainers-go (tous les adaptateurs)
• Suite de tests contractuels pour la conformité de l'interface adaptateur
• Interface Discoverer (backends de découverte enfichables)
• Orchestrateur Kubernetes (Espaces de noms, Déploiements, StatefulSets, DaemonSets, Pods, Services)
• Surveillance K8s en temps réel basée sur informateur avec anti‑rebond
• Disposition en couloirs avec conteneurs de groupes d'espaces de noms
• Pont adaptateur K8s (classifier les pods par image, connecter les adaptateurs aux bases de données dans les pods)
• Observabilité du flux (visualisation du flux de données en temps réel)
• Déclencheur de stress intégré (k6 avec visualisation de l'impact en temps réel)

Support

• Problèmes : github.com/guilherme-grimm/graph-go/issues
• Discussions : github.com/guilherme-grimm/graph-go/discussions

Construit avec ❤️ pour les ingénieurs DevOps et d'infrastructure