Vault HA Cluster Bootstrap (Shamir & Docker Secret)

Bu dizin, Docker Swarm üzerinde Shamir mühürleme (seal) ve Docker secret'ları kullanarak yüksek kullanılabilirliğe (HA) sahip bir Vault kümesinin kurulumunu ve yönetimini içerir. Mevcut yapı, otomatik unseal işlemi için ayrı bir transit vault ihtiyacını ortadan kaldırarak Shamir anahtarını güvenli bir Docker secret'ı olarak kullanır.

---

🏗️ Mimari Yapı

• Düğümler: 3 replika (vault-1, vault-2, vault-3)
• Depolama: Raft entegre depolama
• Unseal: vault_unseal_key isimli Docker secret'ı
• Otomasyon: vault-bootstrap.sh betiği üzerinden uçtan uca kurulum

---

🚀 Hızlı Başlangıç (Bootstrap)

Tüm küme kurulumunu, initialize işlemini ve unseal yapılandırmasını tek bir komutla gerçekleştirmek için:

chmod +x vault-bootstrap.sh
./vault-bootstrap.sh

Bu betik sırasıyla şu adımları izler:

ADIM 0 — Ön Koşullar

• Swarm manager node kontrolü.
• docker-stack-vault.yml dosyasının varlığı.

ADIM 1 — Yer Tutucu Secret

• vault_unseal_key için geçici bir "bootstrap" secret'ı oluşturur. Bu, servislerin çökmeden başlamasını sağlar.

ADIM 2 — Stack Deploy

• iklimco stack'ini ilgili konfigürasyonla yayına alır.

ADIM 3 — Servis Bekleme

• Vault servisinin 3/3 replika olarak ayağa kalkmasını bekler.

ADIM 4 — Durum Kontrolü

• Eğer küme zaten initialize edilmiş ve unsealed durumdaysa işlemi güvenli bir şekilde sonlandırır.

ADIM 5 — Initialize & Key Hazırlığı

• Vault henüz başlatılmadıysa vault operator init komutunu çalıştırır.
• Çıktıları /tmp/vault-bootstrap/main-vault-init.txt dosyasına kaydeder.

ADIM 6 — Secret Güncelleme

• Geçici secret'ı siler ve gerçek Shamir unseal anahtarı ile Docker secret'ını günceller.
• Servislerin bu yeni anahtarla rolling restart yapmasını sağlar.

ADIM 7 — Doğrulama

• Tüm düğümlerin (leader ve follower) başarıyla unseal edildiğini ve Raft kümesine katıldığını doğrular.

---

📂 Dizin İçeriği

• vault-bootstrap.sh: Küme kurulumunu otomatize eden ana betik.
• docker-stack-vault.yml: Vault HA kümesinin Docker Swarm stack tanımı.
• vault-template-v1.json: TLS doğrulamasının daha esnek olduğu (tls_skip_verify: true) konfigürasyon şablonu.
• vault-template-v2.json: Karşılıklı TLS (mTLS) doğrulamasının zorunlu olduğu, daha sıkı güvenlikli konfigürasyon şablonu.
• failover_scenarios.md: Hata durumları ve kurtarma senaryoları dökümantasyonu.

Neden iki versiyon var?

• v1 (İlk Kurulum): SWAG reverse proxy henüz wildcard sertifikaları üretmeden önce, self-signed (kendinden imzalı) sertifikalarla ilk kurulumu gerçekleştirebilmek için kullanılır. Bu sürümde TLS doğrulaması esnetilmiştir.
• v2 (Kalıcı Yapı): Geçerli wildcard sertifikalar üretildikten sonra, düğümler arası iletişimin tam sertifika doğrulaması (mTLS) ile yapıldığı güvenli ve kalıcı sürümdür. Mevcut bootstrap betiği varsayılan olarak v2 şablonunu kullanır.

---

⚠️ Önemli Güvenlik Notları

1. Init Dosyası: /tmp/vault-bootstrap/main-vault-init.txt dosyası root token ve unseal anahtarlarını içerir. Kurulum bittikten sonra bu dosyayı güvenli bir yere (Vault'un kendisi dışındaki bir şifre yöneticisine) yedekleyin ve Host Makine üzerinden silin!
2. Secret Yönetimi: vault_unseal_key secret'ına sadece vault servisinin erişimi vardır. Bu anahtarı Swarm dışında paylaşmayın.
3. SSL Sertifikaları: Host makinelerde /opt/iklimco/ssl/ dizininde gerekli wildcard sertifikaların mevcut olduğundan emin olun.

---

🛠️ Manuel Müdahaleler

Küme normal şartlarda kendi kendini iyileştirme (self-healing) yeteneğine sahiptir. Ancak yeni bir host makine eklendiğinde etiketleme yapmanız gerekir.

Düğüm kimliğini (Node ID) bulmak için:

docker node ls

Etiketleme örneği (ID veya Hostname ile):

# Node ID kullanarak
docker node update --label-add type=service 0z2qov6x078hghu88v0p7z6e7

# Veya Hostname kullanarak
docker node update --label-add type=service iklim-app-02

Detaylı hata kurtarma senaryoları için failover_scenarios.md dökümanını inceleyin.