Murat ÖZDEMİR
483bd40cc4
Updates README.md with the new Shamir-based auto-unseal process using Docker secrets, eliminating the need for a separate transit vault. Adds `failover_scenarios.md` to detail the Vault cluster's resilience under various failure conditions. Translates `vault-bootstrap.sh` messages and step titles from Turkish to English, and aligns its execution flow with the updated documentation.
97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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:**
|
||
```bash
|
||
docker node ls
|
||
```
|
||
|
||
**Etiketleme örneği (ID veya Hostname ile):**
|
||
```bash
|
||
# 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.
|