Environment_Infrastructure/README.md

🌍 Sunucu Ortam ve Altyapıları

iklim.co test ve prod ortamları için Hetzner Cloud üzerinde Infrastructure-as-code ve operasyonel runbook deposu.

Bu depo şunları kapsar:

• 🧱 Hetzner altyapısı için Terraform kaynakları (test ve prod)
• 🤖 Ansible bootstrap playbook'ları, paylaşımlı roller ve envanter hedefleri
• 📚 Uçtan uca kurulum rehberleri ve yol haritası dokümanları
• 📊 Boyutlandırma/maliyet analizi ve referans kaynakları

🎯 Kapsam

Temel amaç, sorumluluk sınırları net biçimde tanımlanmış, standart ve belgelenmiş bir altyapı provisioning süreci oluşturmaktır:

• 🧱 Terraform: bulut altyapısını oluşturur (sunucular, private ağlar, firewall'lar, placement group'lar, floating IP'ler, SSH key kaydı, envanter çıktısı)
• 🤖 Ansible: OS hazırlığı, güvenlik sertleştirme, Docker/Swarm, runner kurulumu ve StorageBox mount süreçlerini depodaki playbook ve paylaşımlı roller aracılığıyla yönetir
• 🚀 Uygulama/stack dağıtımı: yol haritası dokümanlarında referans verilen ilgili deployment workflow'ları ve stack manifest'leri tarafından yönetilir

📌 Mevcut Depo Durumu

Bu depo şu an ağırlıklı olarak şunları içermektedir:

• 🧱 Hazır Terraform kodu:
  • terraform/hetzner/test
  • terraform/hetzner/prod
• 🤖 Her iki ortam için Ansible otomasyon varlıkları:
  • ansible/test/test-bootstrap.yml
  • ansible/prod/prod-bootstrap.yml
  • ansible/roles/*
  • ansible/test/group_vars/* ve ansible/prod/group_vars/*
• 📦 Envanter çıktıları ve hedef yollar:
  • ansible/test/inventory/generated/test.yml (takip edilen örnek)
  • ansible/prod/inventory/generated/prod.yml (beklenen çıktı yolu)
• 📘 Detaylı kurulum aşamaları:
  • setup/00-genel-yol-haritasi.md — setup/09-prod-runner-ha-ve-swarm.md
• 🛣️ Ortam yol haritası adımları:
  • roadmap/test-env/*
  • roadmap/prod-env/*
• 📈 Kapasite planlama ve referans grafikler:
  • hetzner-sizing-report.md
  • test-app-graphs.png
  • test-db-graphs.png

🧭 Hedef Ortam Topolojisi

🧪 Test

Node	Rol	Private IP	Önerilen Tip
iklim-app-01	Swarm manager + app worker + test runner	10.10.10.11	cpx42
iklim-db-01	DB host (manuel/stack tabanlı DB kurulum yolu)	10.10.20.11	cpx42

🏭 Production

Node	Rol	Private IP	Önerilen Tip
iklim-app-01	Swarm manager + app worker + runner (birincil FIP hedefi)	10.20.10.11	cpx42
iklim-app-02	Swarm manager + app worker + runner	10.20.10.12	cpx42
iklim-app-03	Swarm manager + app worker + runner	10.20.10.13	cpx42
iklim-db-01	DB cluster node	10.20.20.11	cpx32
iklim-db-02	DB cluster node	10.20.20.12	cpx32
iklim-db-03	DB cluster node	10.20.20.13	cpx32

🔐 Güvenlik ve Ağ Temeli

Terraform ve kurulum dokümanlarına yansıtılan temel kararlar:

• Test ve prod, ayrı Hetzner Cloud proje ve token'larıyla birbirinden yalıtılmıştır.
• Kamuya açık gelen trafik şunlarla sınırlıdır:
  • 22/tcp (yalnızca admin CIDR'ları)
  • 80/tcp
  • 443/tcp
• Kritik servisler yalnızca private ağda erişilebilir (örneğin Vault 8200, PostgreSQL 5432, MongoDB 27017, iç gözlemlenebilirlik ve broker portları).
• Host dağılımı stratejisi için placement group'lar kullanılmaktadır.
• Sunucu kaynaklarında yanlışlıkla silinmeye karşı prevent_destroy = true etkinleştirilmiştir.
• Terraform state ve gizli dosyalar commit'lenmemelidir.

Ayrıca bkz.:

• facts/firewall.md — tüm firewall kurallarının araç bazında özet dökümantasyonu
• setup/01-private-network-port-matrisi.md
• terraform/hetzner/test/firewall.tf
• terraform/hetzner/prod/firewall.tf

🗂️ Depo Yapısı

Environment_Infrastructure/
├── ansible/
│   ├── prod/
│   │   ├── ansible.cfg
│   │   ├── group_vars/
│   │   └── prod-bootstrap.yml
│   ├── roles/
│   │   ├── base/
│   │   ├── docker/
│   │   ├── hardening/
│   │   ├── node_dirs/
│   │   ├── storagebox/
│   │   ├── storagebox_ssh_key/
│   │   └── swarm/
│   ├── test/
│   │   ├── ansible.cfg
│   │   ├── group_vars/
│   │   ├── inventory/
│   │   │   └── generated/
│   │   │       └── test.yml
│   │   └── test-bootstrap.yml
│   └── requirements.yml
├── roadmap/
│   ├── test-env/
│   └── prod-env/
├── setup/
│   ├── 00-genel-yol-haritasi.md
│   ├── 01-private-network-port-matrisi.md
│   ├── 02-test-terraform-iaac.md
│   ├── 03-test-ansible-bootstrap.md
│   ├── 04-test-db-docker-kurulum.md
│   ├── 05-test-runner-ve-deploy-onkosullari.md
│   ├── 06-prod-terraform-iaac.md
│   ├── 07-prod-ansible-bootstrap.md
│   ├── 08-prod-db-cluster-kurulum.md
│   └── 09-prod-runner-ha-ve-swarm.md
├── terraform/
│   └── hetzner/
│       ├── test/
│       └── prod/
├── facts/
│   └── firewall.md
├── hetzner-sizing-report.md
├── setup-vs-roadmap-map.md
├── test-app-graphs.png
└── test-db-graphs.png

✅ Ön Koşullar

• Terraform >= 1.6
• Hetzner Cloud hesabı ve ortam başına API token
• SSH anahtar çifti (public key yolu Terraform değişkenlerinde kullanılır)
• Linux/macOS kabuk araçları (bash, cp, sed veya tercih edilen metin editörü)
• İlerleyen aşamalarda gerekli: Ansible, Docker, Gitea/Harbor/StorageBox erişimi

🛠️ Terraform Kullanımı

1) 🧪 Test Altyapısı

cd terraform/hetzner/test
cp terraform.tfvars.example terraform.tfvars

terraform.tfvars değerlerini düzenle:

• hcloud_token
• admin_allowed_cidrs
• isteğe bağlı geçersiz kılmalar (location, image, sunucu tipleri, key yolu)

Ardından çalıştır:

terraform init
terraform plan
terraform apply
mkdir -p ../../../ansible/test/inventory/generated
terraform output -raw ansible_inventory_yaml > ../../../ansible/test/inventory/generated/test.yml

2) 🏭 Production Altyapısı

cd terraform/hetzner/prod
cp terraform.tfvars.example terraform.tfvars

terraform.tfvars değerlerini düzenle:

• hcloud_token (prod token)
• admin_allowed_cidrs
• isteğe bağlı geçersiz kılmalar

Ardından çalıştır:

terraform init
terraform plan
terraform apply
mkdir -p ../../../ansible/prod/inventory/generated
terraform output -raw ansible_inventory_yaml > ../../../ansible/prod/inventory/generated/prod.yml

🧱 Kurulum Akışı (Kanonik Sıra)

Kurulum dokümanlarını bu sırayla kullan:

1. setup/00-genel-yol-haritasi.md — genel kararlar ve sınırlar
2. setup/01-private-network-port-matrisi.md — private/public port politikası
3. setup/02-test-terraform-iaac.md — test Terraform aşaması
4. setup/03-test-ansible-bootstrap.md — test OS/bootstrap/sertleştirme
5. setup/04-test-db-docker-kurulum.md — test DB stack kurulumu (Swarm üzerinde)
6. setup/05-test-runner-ve-deploy-onkosullari.md — test runner ve deploy ön koşulları
7. setup/06-prod-terraform-iaac.md — prod Terraform aşaması
8. setup/07-prod-ansible-bootstrap.md — prod OS/bootstrap/sertleştirme
9. setup/08-prod-db-cluster-kurulum.md — prod DB cluster stack (MongoDB + Patroni/etcd)
10. setup/09-prod-runner-ha-ve-swarm.md — prod runner HA ve deploy kilit modeli

🛣️ Yol Haritası Dokümanları

Yol haritası klasörleri; Swarm stack'leri, SWAG, APISIX, pipeline güncellemeleri ve doğrulama kontrol listeleri için entegrasyon çalışmalarını takip eder:

• roadmap/test-env/*
• roadmap/prod-env/*

Bu dokümanlar zaman zaman ilgili repolardan (örneğin uygulama ana deposu workflow ve stack dosyaları) dosyalara referans verir. Bu altyapı temeliyle hizalanmış uygulama rehberleri olarak değerlendirilmelidir.

💰 Boyutlandırma ve Maliyet Özeti

Referans: hetzner-sizing-report.md

Önerilen temel yapı:

• Test: 2 x cpx42 (app + db)
• Prod: 3 x cpx42 (app) + 3 x cpx32 (db)

Rapordaki yaklaşık aylık toplam:

• Test: $59.98
• Prod: $139.44
• Toplam: $199.42

🔑 Gizli Bilgi ve State Yönetimi

Kesinlikle commit'lenmemeli:

• terraform.tfvars, *.tfvars, *.tfstate, .terraform/
• private key'ler, sertifikalar, .env gizli bilgileri
• runner token'ları ve vault parola dosyaları

Zorunlu kalıplar için .gitignore dosyasına bkz.

Önerilen:

• çalışma zamanı gizli bilgilerini güvenli gizli depolarda / şifreli vault dosyalarında tut
• üretilen çalışma zamanı artifakt'larını, açıkça temizlenmedikçe versiyon kontrolü dışında tut

⚠️ Bilinen Eksikler / Notlar

• ansible/prod/inventory/generated/prod.yml beklenen bir çıktı yoludur; üretilene kadar mevcut olmayabilir.
• Bazı yol haritası adımları, yalnızca bu depo değil, daha geniş kapsamlı iklim.co uygulama deposundaki dosyaları hedef alır.

✅ Hızlı Doğrulama Kontrol Listesi

Terraform apply sonrası:

• sunucular beklenen isimler ve private IP'lerle oluşturulmuş
• floating IP mevcut ve bağlı
• firewall'lar yalnızca amaçlanan public portları açıyor
• placement group'lar atanmış
• üretilen envanter YAML ansible/{test,prod}/inventory/generated/*.yml yoluna aktarılmış

Bootstrap/deploy aşamaları sonrası:

• Swarm durumu ve etiketleri dökümantasyonla eşleşiyor
• DB erişimi yalnızca private ağdan mümkün
• Vault/API gateway'leri public/private erişim kurallarına uyuyor
• Runner ve deploy kilit davranışı ortam politikasıyla örtüşüyor

🔗 Referanslar

• Hetzner Terraform Provider: https://registry.terraform.io/providers/hetznercloud/hcloud/latest
• Hetzner Networks: https://docs.hetzner.com/cloud/networks/overview/
• Hetzner Firewalls: https://docs.hetzner.com/cloud/firewalls/overview
• Hetzner Placement Groups: https://docs.hetzner.com/cloud/placement-groups/overview
• Docker Swarm overlay networking: https://docs.docker.com/engine/network/drivers/overlay/
• Gitea act_runner: https://docs.gitea.com/usage/actions/act-runner