Environment_Infrastructure/setup/00-genel-yol-haritasi.md

00 - Genel Yol Haritasi

Bu dosya, Environment_Infrastructure reposunda Terraform ve Ansible ile Hetzner Cloud uzerinde test/prod altyapisini kuracak ajanlar icin ana baglamdir. Her asama dosyasi kendi basina yeterli olacak sekilde yazilmistir; yine de bu dokuman genel karar kaydidir.

Hedef

Iklim.co altyapisi iki ayri Hetzner Cloud Project uzerinde kurulacak:

• test Hetzner Cloud Project
• prod Hetzner Cloud Project

Bu ayrim zorunlu kabul edilir. API token, network, firewall, placement group, server, maliyet ve yanlislikla silme riskleri ortam bazinda ayrilmis olur.

Terraform ve Ansible Sorumluluk Siniri

Terraform sadece IaaS kaynaklarini olusturur:

• Hetzner Cloud server
• Private network ve subnet
• Firewall
• SSH key
• Placement group
• Opsiyonel volume, floating IP, load balancer veya DNS kaydi
• Ansible inventory output

Ansible olusan Linux makineleri hazirlar:

• Linux base paketleri
• Security hardening
• Docker Engine kurulumu
• Docker Swarm init/join
• Gitea Actions act_runner systemd kurulumu
• Ortak klasorler ve deploy on kosullari

Terraform icinde Docker, Swarm, runner veya uygulama deploy'u yapilmayacak. Ansible icinde Hetzner Cloud kaynaklari yaratilmeyecek.

Ortam Topolojileri

Test

Test ortami minimum topoloji:

Node	Rol	Not
iklim-app-01	Swarm manager + app worker + Gitea runner	CI/CD test deploy bu node uzerinden calisir
iklim-db-01	DB node	DB altyapisi manuel kurulacak; Gitea CI/CD ile kurulmayacak

Test DB kurulumu Terraform/Ansible ile sadece makine ve OS hazirligina kadar getirilir. PostgreSQL/MongoDB cluster kurulumu bu asamanin disindadir.

Prod

Prod ortami HA topoloji:

Node grubu	Adet	Rol
iklim-app-*	3	Her biri Swarm manager + app worker
iklim-db-*	3	DB cluster node'lari

Prod DB altyapisi manuel kurulacak; Gitea CI/CD ile kurulmayacak. Terraform DB makinelerini ve network/firewall kurallarini hazirlar, Ansible OS hardening ve temel bagimliliklari kurar.

Public Port Politikasi

Public internete acik portlar sadece:

• 22/tcp SSH, sadece admin IP/CIDR kaynaklarindan
• 80/tcp HTTP
• 443/tcp HTTPS

8200/tcp Vault public internete acilmayacak. Vault sadece private network veya Docker overlay icinden erisilebilir olmalidir.

Mevcut uygulama stack dosyalarinda bazi servisler host port publish ediyor olabilir. Hetzner Cloud firewall public ingress'i engelleyecegi icin bu portlar public'ten erisilemez olmalidir. Ancak uzun vadede stack manifestleri de bu politikaya uyacak sekilde sadeleştirilmelidir.

Private Network Politikasi

Private network icinde acilmasi gereken portlarin ayrintili matrisi 01-private-network-port-matrisi.md dosyasindadir. Ajanlar firewall veya Ansible UFW kurali yazarken bu dosyayi kaynak kabul etmelidir.

Gitea Actions Runner Karari

act_runner Docker container olarak calistirilmayacak ve Docker socket container'a mount edilmeyecek.

Tercih edilen kurulum:

• act_runner Linux systemd servisi olarak kurulur.
• Runner icin ayri gitea-runner kullanicisi olusturulur.
• CI/CD job'lari gerekli oldugunda container olusturabilir; bunun icin runner host uzerinde Docker CLI/daemon erisimi gerekir.
• Docker group uyeligi root seviyesine yakin yetki verdigi icin sadece guvenilir Gitea repo/job'lari bu runner label'larini kullanmalidir.

Prod HA icin act_runner tek makineye degil, 3 Swarm manager node'unun tamamına kurulacaktir. Boylece bir manager/runner kaybedildiginde pipeline calismaya devam edebilir. Runner label'lari hem ortak hem node-spesifik olmalidir:

• Ortak: prod-runner
• Node spesifik: iklim-app-01, iklim-app-02, iklim-app-03

Test icin tek runner yeterlidir:

• Ortak: test-runner
• Node spesifik: iklim-app-01

Deploy Lock Karari

Prod ortaminda 3 runner HA icin gereklidir; ancak ayni anda birden fazla deploy job'u calistirabilir. Bu nedenle prod deploy islemleri StorageBox uzerinde otomatik lock ile tekillestirilmelidir.

Lock dosyalari/klasorleri manuel olusturulmayacak. Workflow basinda atomik mkdir ile olusturulacak, deploy bitince rmdir ile silinecek.

Onerilen StorageBox path'leri:

prod/locks/prod-deploy.lock
prod/locks/prod-infra.lock
prod/locks/services/<service-name>.lock

Baslangic icin en sade ve guvenli model tek global prod deploy lock'tur:

prod/locks/prod-deploy.lock

Bu model tum prod deploy'lari siraya sokar. Daha sonra ihtiyac olursa servis bazli lock modeline gecilebilir.

Ornek akış:

ssh storagebox 'mkdir -p prod/locks && mkdir prod/locks/prod-deploy.lock'
# deploy islemleri
ssh storagebox 'rmdir prod/locks/prod-deploy.lock'

mkdir atomik oldugu icin lock zaten varsa komut fail olur; bu durumda job beklemeli veya temiz bir hata ile cikmalidir. Workflow fail olsa bile cleanup adimi lock'u silmeye calismalidir. Eski kalmis lock'lari tespit etmek icin lock klasoru icine timestamp, runner adi ve workflow bilgisi yazilabilir.

Hetzner Fiziksel Host Ayrimi

Hetzner Cloud'da kabinet secimi dogrudan yapilmaz. Ayni fiziksel host'a dusmeme ihtiyaci icin Placement Group kullanilir. spread tipindeki placement group, gruptaki cloud server'lari farkli fiziksel host'lara yerlestirmeyi hedefler.

Kisitlar:

• Spread placement group, tek fiziksel host arizasinin etkisini azaltir.
• Ayni datacenter veya lokasyon icindeki daha genis bir arizaya karsi garanti vermez.
• Lokasyon bazli felaket kurtarma icin ileride farkli lokasyon/region dagilimi tasarlanmalidir.
• Hetzner dokumanina gore spread placement group basina en fazla 10 server limiti vardir.

Prod icin en az iki placement group onerilir:

• iklim-prod-app-spread: 3 Swarm manager/app node
• iklim-prod-db-spread: 3 DB node

Test icin opsiyonel:

• iklim-test-spread: iklim-app-01 ve iklim-db-01

Kaynaklar:

• 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 portlari: https://docs.docker.com/engine/network/drivers/overlay/
• Gitea act_runner: https://docs.gitea.com/usage/actions/act-runner