# 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 `07-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:

```text
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:

```text
prod/locks/prod-deploy.lock
```

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

Ornek akış:

```bash
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