Watch (İzleme)

Watch, Consul Guardian'ın temel özelliğidir. Consul KV'deki değişiklikleri gerçek zamanlı olarak izler ve her değişikliği Git'e commit eder.

Nasıl Çalışır?

Watch mekanizması Consul'un blocking query özelliğini kullanır. Basitçe şöyle çalışır:

1. Guardian, Consul API'ye bir istek gönderir: "Bana şu prefix'teki tüm key'leri ver"
2. Consul, cevapla birlikte bir X-Consul-Index değeri döndürür
3. Guardian, sonraki isteğinde bu index'i gönderir: "Bu index'ten sonra bir değişiklik olursa bana söyle"
4. Consul, değişiklik olana kadar bağlantıyı açık tutar (long-polling)
5. Değişiklik olduğunda Consul hemen cevap verir
6. Guardian farkı hesaplar, değişen dosyaları Git'e commit eder
7. Döngü başına döner

Consul KV          Guardian              Git Repo
   │                  │                     │
   │  GET /kv?index=0 │                     │
   │<─────────────────│                     │
   │  [tum key'ler]   │                     │
   │─────────────────>│                     │
   │                  │  git commit          │
   │                  │────────────────────>│
   │                  │                     │
   │  GET /kv?index=42│                     │
   │<─────────────────│  (bekliyor...)      │
   │     ...          │                     │
   │  (key değişti!)  │                     │
   │─────────────────>│                     │
   │                  │  git commit          │
   │                  │────────────────────>│

Bu yaklaşım, periyodik polling'e göre çok daha verimli. Değişiklik yokken gereksiz istek yapılmaz, değişiklik olduğunda ise 5 saniye içinde yakalanır.

Temel Kullanım

# Tek prefix izle
consul-guardian watch --prefix "config/"

# Birden fazla prefix izle
consul-guardian watch --prefix "config/,env/,feature-flags/"

# Belirli prefix'leri hariç tut
consul-guardian watch \
  --prefix "config/" \
  --exclude-prefix "config/ephemeral/"

Yapılandırma Seçenekleri

CLI flag'leri veya consul-guardian.yaml dosyası ile yapılandırabilirsin:

watch:
  prefixes:
    - "config/"
    - "env/"
    - "feature-flags/"
  exclude_prefixes:
    - "config/ephemeral/"
  poll_interval: "5m"    # Blocking query bekleme süresi (max 10m)

Flag	Yapılandırma	Varsayılan	Açıklama
--prefix	watch.prefixes	""	İzlenecek KV prefix'leri (virgüllü liste)
--exclude-prefix	watch.exclude_prefixes	""	Hariç tutulacak prefix'ler
--git-repo	git.repo_path	./consul-backup	Git repo dizini
--poll-interval	watch.poll_interval	5m	Blocking query bekleme süresi

Git Sync Davranışı

Watch her değişiklik tespit ettiğinde şu adımları izler:

Eklenen key'ler

Key'in değeri dosya sisteminde oluşturulur. Dosya uzantısı içeriğe göre otomatik belirlenir:

• JSON içeriği: .json
• YAML içeriği: .yaml
• Diğer: .txt

config/production/database → consul-backup/config/production/database.json

Değiştirilen key'ler

Dosya güncellenir, yeni içerik yazılır.

Silinen key'ler

Dosya Git'ten kaldırılır (git rm).

Commit mesajı formatı

consul-guardian: 3 keys changed

Modified: config/production/database
Added: config/production/new-service
Deleted: config/staging/old-key

Otomatik push

Uzak repo'ya otomatik push yapmasını istersen:

git:
  auto_push: true
  remote: "origin"
  branch: "main"
  ssh_key: "/path/to/deploy_key"

Arka Plan Servisi Olarak Çalıştırma

Watch sürecini production ortamında sürekli çalışması için bir servis olarak yapılandırmalısın.

systemd ile

# Servisi oluştur (detaylar için deployment/systemd rehberine bak)
sudo systemctl enable consul-guardian
sudo systemctl start consul-guardian

Docker ile

docker run -d \
  --name consul-guardian-watch \
  --restart always \
  -e CONSUL_GUARDIAN_CONSUL_ADDRESS=http://consul:8500 \
  -v /data/consul-backup:/home/guardian/repo \
  ghcr.io/consul-guardian/consul-guardian:latest \
  watch --prefix "config/,env/"

Kubernetes ile

Deployment olarak çalıştır. Detaylar için Kubernetes deployment rehberi'ne bak.

Hata Durumunda Davranış

Watch süreci hata durumlarını şu şekilde ele alır:

• Consul erişim hatası: Exponential backoff ile yeniden deneme (1s, 2s, 4s, 8s, max 15s)
• Index geri gitmesi (Raft snapshot restore sonrası): Index sıfırlanır, tam sync yapılır
• Git commit hatası: Hata loglanır, sonraki değişiklikte tekrar denenir
• Network kesintisi: Bağlantı yeniden kurulana kadar backoff ile deneme

Gerçek Senaryo: Production Config İzleme

Diyelim ki bir e-ticaret uygulamanın var. Consul'da şu prefix'ler altında config saklıyorsun:

consul-guardian watch \
  --consul-addr http://consul.internal:8500 \
  --consul-token "$CONSUL_TOKEN" \
  --prefix "config/production/,config/staging/" \
  --exclude-prefix "config/production/ephemeral/" \
  --git-repo /data/consul-backup \
  --log-level info

Gece 3'te birisi config/production/payment-service key'ini değiştirirse:

1. Guardian değişikliği 5 saniye içinde yakalar
2. Git'e commit eder (zaman damgası + değişiklik detayı)
3. Slack'e bildirim gönderir (uyarı yapılandırıldıysa)
4. Ertesi gün git log ile kimin ne zaman ne değiştirdiğini görebilirsin