Mimari

Bu sayfa Consul Guardian'ın iç yapısını, bileşenlerini ve veri akışını açıklar.

Sistem Genel Bakış

                                ┌─────────────────────────────────────────┐
                                │          Consul Guardian Agent          │
                                │                                         │
 ┌──────────────┐  Blocking     │  ┌─────────────┐   ┌───────────────┐   │
 │              │  Query        │  │   Watcher    │   │   Scheduler   │   │
 │    Consul    │ ◄──────────── │  │   Engine     │   │   (Cron)      │   │
 │   Cluster    │  KV Changes   │  └──────┬───────┘   └──────┬────────┘  │
 │              │ ─────────────>│         │                   │           │
 │  KV Store    │               │  ┌──────▼───────────────────▼────────┐  │
 │  ACL'ler     │  Snapshot API │  │        Change Processor           │  │
 │  Session'lar │ ◄──────────── │  │  - Diff Hesaplayıcı               │  │
 │  Catalog     │               │  │  - Çatışma Çözücüsü               │  │
 └──────────────┘  Restore(CAS) │  │  - Şifreleme İşleyicisi           │  │
                  ◄──────────── │  └──────┬───────────────────┬────────┘  │
                                │         │                   │           │
                                │  ┌──────▼───────┐   ┌──────▼────────┐  │
                                │  │  Git Syncer   │   │   Storage     │  │
                                │  │               │   │   Manager     │  │
                                │  └──────┬────────┘   └──────┬────────┘  │
                                └─────────┼───────────────────┼───────────┘
                                          │                   │
                          ┌───────────────┤                   ├─────────────────┐
                          ▼               ▼                   ▼                 ▼
                    ┌──────────┐   ┌──────────┐        ┌──────────┐     ┌──────────┐
                    │   Git    │   │  Slack/  │        │  S3/GCS/ │     │  Yerel   │
                    │   Repo   │   │  Webhook │        │  MinIO   │     │  Disk    │
                    └──────────┘   └──────────┘        └──────────┘     └──────────┘

Bileşenler

Watcher Engine (İzleme Motoru)

Consul blocking query kullanarak KV değişikliklerini gerçek zamanlı izler.

Her prefix için ayrı bir goroutine çalışır
ModifyIndex takibiyle sadece değişen key'leri tespit eder
Index geri gitmesi durumunu ele alır (Raft snapshot restore)
Hata durumunda adaptive rate limiter ile exponential backoff uygular

Change Processor (Değişiklik İşleyici)

Watcher'dan gelen değişiklikleri işler ve ilgili bileşenlere dağıtır.

Diff Hesaplayıcı: Önceki ve mevcut durumu karşılaştırır, eklenen/değişen/silinen key'leri belirler
Çatışma Çözücüsü: Eşleyici yazmalarda son yazma kazanır (last-write-wins) stratejisi
Şifreleme İşleyicisi: SOPS uyumlu şifreleme (aktifse)

Git Syncer (Git Senkronizasyonu)

KV değişikliklerini dosya sistemine yazar ve Git'e commit eder.

Consul key yolunu dosya yoluna çevirir: config/production/database -> config/production/database.json
İçerik tipine göre dosya uzantısı belirler (JSON, YAML, TXT)
Değişiklik özetini içeren commit mesajı oluşturur
Opsiyonel olarak uzak repo'ya push yapar

Storage Manager (Depolama Yöneticisi)

Snapshot'ların depolanmasını ve saklama politikalarının uygulanmasını yönetir.

Pluggable backend mimarisi: S3, GCS, MinIO, yerel disk
SHA-256 ile snapshot doğrulama
Retention policy: sayı veya yaş bazında otomatik silme

Scheduler (Zamanlayıcı)

Cron ifadeleriyle zamanlanmış işlemleri yönetir.

Snapshot zamanlama
Drift kontrolü zamanlama
robfig/cron/v3 kütüphanesi kullanır

Veri Akışı

Watch Akışı (KV-to-Git Sync)

1. Agent başlar, yapılandırmayı okur (izlenecek prefix'ler, Git repo yolu)
2. Her prefix için:
   a. GET /v1/kv/{prefix}?recurse → başlangıç durumunu al
   b. Her key için ModifyIndex'i bellekte sakla
   c. KV çiftlerini dosya sistemine yaz (Git working directory)
   d. Git commit: "Initial sync: {prefix}"
3. İzleme döngüsüne gir:
   a. GET /v1/kv/{prefix}?recurse&index={sonIndex}&wait=5m (blocking)
   b. Her key'in ModifyIndex'ini karşılaştır → değişiklikleri bul
   c. Değişen/yeni key'ler için:
      - Dosya sistemi temsilini güncelle
      - git add {degisen_dosyalar}
   d. Silinen key'ler için:
      - Dosyayı kaldır
      - git rm {silinen_dosyalar}
   e. Değişiklik özetiyle Git commit
   f. Opsiyonel: git push
   g. Opsiyonel: uyarı bildirimi gönder
   h. sonIndex'i güncelle, (a)'ya dön

Snapshot Akışı

1. Zamanlayıcı tetiklenir (cron ifadesi)
2. GET /v1/snapshot (Consul Snapshot API)
3. SHA-256 ile bütünlük doğrulaması
4. Depolama backend'ine yükle:
   - Dosya adı: consul-{dc}-{zaman_damgasi}.snap
   - Metadata: DC, zaman, Consul versiyonu
5. Saklama politikasını uygula:
   - Mevcut snapshot'ları listele
   - Sayı/yaş limitini aşan eskilerini sil

Drift Tespiti Akışı

1. Git'ten "olması gereken" durumu oku (source of truth)
2. Consul'dan "gerçek" durumu oku
3. Farkı hesapla:
   - MISSING: Git'te var, Consul'da yok
   - EXTRA: Consul'da var, Git'te yok
   - DRIFTED: İkisinde de var ama değerler farklı
4. Drift raporu oluştur
5. auto_reconcile aktifse: Git durumunu Consul'a uygula (CAS ile)
6. Uyarı yapılandırıldıysa: raporu ilgili kanallara gönder

Restore Akışı

1. Kullanıcı: consul-guardian restore --prefix config/prod --revision abc123
2. Planlama aşaması:
   a. Belirtilen Git revizyonundan hedef durumu oku
   b. Consul'dan mevcut durumu oku
   c. Farkı hesapla (eklenecek, güncellenecek, silinecek key'ler)
   d. Planı kullanıcıya göster
3. --dry-run ise: burada dur, sadece planı göster
4. Uygulama aşaması:
   a. Key'leri 64'lük gruplara böl (Consul transaction limiti)
   b. Her grup için:
      - CAS ile Consul Transaction API'yi kullan
      - ModifyIndex'in değişmediğini doğrula
      - CAS başarısız olursa: tekrar oku, yeniden hesapla, yeniden dene
   c. Son durumun hedefle eşleştiğini doğrula
5. İşlem loglanır, takıma bildirilir

Teknoloji Tercihleri

Bileşen	Teknoloji	Neden
Dil	Go 1.22+	Tek binary, Consul ekosistemiyle uyum, goroutine'ler
CLI	Cobra + Viper	Go CLI'ları için standart
Consul Client	hashicorp/consul/api	Resmi Go client
Git	go-git/go-git/v5	Saf Go Git implementasyonu (git binary gerektirmez)
Frontend	React 19, TypeScript, Vite	Modern, hızlı build
UI	shadcn/ui, Tailwind CSS	Tutarlı, özelleştirebilir bileşenler
Zamanlama	robfig/cron/v3	Cron ifadesi parser
Log	log/slog (stdlib)	Go 1.21+ standart yapısal loglama
Metrik	prometheus/client_golang	Standart gözlemlenebilirlik
Test	testify, testcontainers-go	Assertion'lar + gerçek Consul container testleri

Dizin Yapısı

consul-guardian/
├── cmd/                  # CLI komutları (Cobra)
│   ├── root.go           # Root komut, global flag'ler
│   ├── watch.go          # watch komutu
│   ├── dashboard.go      # dashboard komutu
│   ├── drift.go          # drift komutu
│   ├── restore.go        # restore komutu
│   ├── snapshot.go       # snapshot komutu
│   └── version.go        # version komutu
├── internal/             # İç bileşenler
│   ├── watcher/          # Blocking query izleme
│   ├── sync/             # Git senkronizasyonu
│   ├── snapshot/         # Snapshot yönetimi
│   ├── restore/          # Geri yükleme (CAS)
│   ├── drift/            # Drift tespiti
│   ├── storage/          # Depolama backend'leri
│   ├── alert/            # Uyarı sistemi
│   ├── crypto/           # Şifreleme (SOPS)
│   └── consul/           # Consul client sarmalayıcı
├── frontend/             # React dashboard
├── docs/                 # Proje dokümantasyonu
└── main.go               # Giriş noktası

Sistem Genel Bakış​

Bileşenler​

Watcher Engine (İzleme Motoru)​

Change Processor (Değişiklik İşleyici)​

Git Syncer (Git Senkronizasyonu)​

Storage Manager (Depolama Yöneticisi)​

Scheduler (Zamanlayıcı)​

Veri Akışı​

Watch Akışı (KV-to-Git Sync)​

Snapshot Akışı​

Drift Tespiti Akışı​

Restore Akışı​

Teknoloji Tercihleri​

Dizin Yapısı​