> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/production-operasyonlari/multiregion.md).

# Multi-region

Kangal tenant-scoped, active-passive disaster recovery kontrolünü destekler. Region, federation üyeliği, gateway policy, health ve replication evidence, promotion generation, fencing confirmation, audit event ve drill sonuçlarını kaydeder.

Kangal database replication yapmaz, global trafiği yapılandırmaz, database writer'ı fence etmez ve otomatik failover çalıştırmaz. API `automatic_failover=true` değerini reddeder. Bu infrastructure işlemlerini external ve onaylı bir orchestrator yürütmeli, ardından güncel ve doğrulanabilir evidence göndermelidir.

## Desteklenen güvenlik modeli

Promotion iki aşamalı bir işlemdir:

1. **Başlatma:** Kangal tenant scope, target membership, current generation, target health, replication status, evidence yaşı ve yapılandırılmış lag threshold değerini doğrular. Yeni generation ve fence token üretir; effective region'ı değiştirmez.
2. **External işlem:** Controller'lar önceki writer'ı fence eder, health-check kullanan trafik geçişini yapar, immutable evidence saklar ve tam confirmation envelope'u imzalar.
3. **Onay:** Kangal pending generation, fence token, target, evidence, expiry, previous-primary-fenced beyanı, controller allowlist, HMAC imzaları ve quorum'u doğrular. Effective region ancak bundan sonra değişir.

Eksik veya eski prerequisite `412`; concurrent, expired ya da eşleşmeyen işlem `409` döndürür. Idempotency key yalnızca aynı input ile tekrar kullanılabilir.

## Infrastructure topology

Her region'da ayrı release ve namespace kullanın. Her control plane şunları kullanmalı:

* aynı externally managed, cross-region MongoDB replica set veya sharded cluster;
* regional runtime state için bölgesel, authenticated Redis endpoint'i;
* durable background job'lar için tek, ortak ve failover-capable Redis endpoint'i;
* aynı federation tanımı ve controller allowlist;
* benzersiz `KANGAL_REGION_ID`, regional API URL, ingress, DNS ve label'lar;
* aynı uyumlu release'ten immutable image'lar.

Multi-region için bundled MongoDB veya Redis açmayın. Global database'e karşı her region'da ayrı değil, tek authoritative backup schedule çalıştırın.

## Sorumluluk sınırı

| Kangal'ın doğruladıkları                            | External operator/controller sorumluluğu      |
| --------------------------------------------------- | --------------------------------------------- |
| Tenant isolation ve region membership               | Database replication ve write concern         |
| Evidence schema, digest, yaş ve lag limitleri       | Gerçek health probe ve replication checkpoint |
| Promotion generation ve idempotency                 | Eski primary writer fencing                   |
| Pending confirmation expiry                         | DNS/load-balancer trafik geçişi               |
| Controller allowlist, benzersiz key, imza ve quorum | Controller key saklama ve rotation            |
| Effective region state ve immutable audit           | Evidence object retention ve incident onayı   |

API'de `stable` görmek global trafik ile database writer state'in hâlâ doğru olduğunu kanıtlamaz. Üç görünümü de sürekli reconcile edin.

## Controller key dağıtımı

`KANGAL_DR_FENCING_CONTROLLERS_JSON` değerini runtime Secret üzerinden her regional API deployment'a verin. Her controller ID ve key benzersiz olmalı; her key en az 32 byte entropy içermelidir. Map'i values, source control, ticket veya release artifact'a koymayın. Quorum'u bir controller outage sırasında karşılanabilir, fakat tek bir ortak credential ile sağlanamaz şekilde ayarlayın.

## Resource bootstrap

Hedef tenant scope'una sahip admin token kullanın. Unversioned ve versioned admin base path aynı resource işlemlerini sunar.

1. `POST /admin/regions` ile en az iki region oluşturun.
2. `POST /admin/regions/{region_id}/health-evidence` ile health evidence gönderin.
3. `POST /admin/federations` ile federation oluşturup izinli controller ID'lerini yazın.
4. `PUT /admin/gateways/{gateway_id}/dr-policy` ile active-passive policy tanımlayın.
5. `POST /admin/gateways/{gateway_id}/replication-evidence` ile source-to-target replication evidence gönderin.
6. `GET /admin/gateways/{gateway_id}/dr-status` üzerinden readiness ve blocker'ları okuyun.

Örnek policy body:

```json
{
  "tenant_id": "acme",
  "federation_id": "<federation-id>",
  "primary_region_id": "<primary-region-id>",
  "failover_order": ["<secondary-region-id>"],
  "mode": "active_passive",
  "max_replication_lag_seconds": 30,
  "evidence_max_age_seconds": 300,
  "require_healthy_target": true,
  "require_caught_up_replication": true,
  "automatic_failover": false
}
```

Evidence immutable monitoring event, database checkpoint, signed object veya saklanan controller log'una referans vermelidir. `digest_sha256` bu object'in digest'idir. `observed_at` ve `expires_at` gerçek observation window'u anlatmalıdır. API request'inden uydurma digest üretmeyin.

## Promotion runbook

### 1. İlan ve hazırlık

* Incident/change record açın; incident commander, database, traffic, application ve security owner'larını belirleyin.
* İlgisiz deployment ve configuration rollout'larını dondurun.
* Current generation, effective region, trafik dağılımı, database writer, replication checkpoint, error rate ve backup reference kaydedin.
* Target'ın tam kapasiteyi taşıyabildiğini ve rollback kriterlerinin açık olduğunu doğrulayın.

### 2. Evidence yenileme

Güncel target-health ve source-to-target replication evidence gönderin. Başlatmadan hemen önce DR status okuyun. Herhangi bir blocker, bilinmeyen writer state veya onaydan önce süresi dolacak evidence varsa devam etmeyin.

### 3. Promotion başlatma

```bash
curl -fsS -X POST \
  "$API/admin/gateways/$GATEWAY_ID/promotions" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d @promotion-request.json
```

Request `tenant_id`, target region, current `expected_generation`, benzersiz `idempotency_key` ve onaylı reason içermelidir. Dönen fence token'ı yalnızca güvenli orchestration workflow içinde tutun; CI log veya ticket'a yazdırmayın.

Bu aşamada phase `awaiting_external_confirmation` olur; effective region değişmemiştir.

### 4. Fence ve trafik geçişi

External workflow şunları yapmalıdır:

1. önceki primary'de write'ları reddetmek veya durdurmak;
2. yeni database writer ve gerekli replication checkpoint'i kanıtlamak;
3. global trafiği health-check kullanan, sınırlandırılmış adımlarla geçirmek;
4. target'ta representative read ve write trafiğini doğrulamak;
5. tek bir immutable evidence object saklamak;
6. canonical confirmation envelope'u farklı allowlisted controller'lara imzalatmak.

İmza controller, tenant, gateway, source, target, generation, fence token, previous-primary-fenced state ve tam evidence object'i kapsar. Yalnızca evidence digest'ini imzalamak yeterli değildir.

### 5. Onay

Pending confirmation süresi dolmadan `POST /admin/gateways/{gateway_id}/promotions/confirm` çağrısı yapın. Acceptance için `phase=stable`, eşleşen effective/desired region ID, değişmemiş generation, eski primary'de reddedilen write, yeni region'da sağlıklı trafik ve her promotion stage için tek immutable audit entry gerekir.

## Failback

Failback bir geri alma düğmesi değil, yeni promotion'dır. Tercih edilen region'ı onarıp catch up edin, ters yönde yeni evidence toplayın, yeni idempotency key kullanın, current writer'ı fence edin, trafiği geçirin ve aynı quorum ile onaylayın. Eski failover evidence'ını tekrar kullanmayın.

## Drill ve alert

Drill kayıtlarını `/admin/dr-drills` altında oluşturun. `passed` veya `failed` biten kayıtlar external evidence ve completion timestamp gerektirir. Ölçülen RPO/RTO, trafik etkisi, writer-fencing proof ve cleanup sonucunu kaydedin.

Eski veya unhealthy region evidence, policy üzeri replication lag, unknown replication state, expiry'ye yaklaşan pending confirmation, quorum'u karşılayacak controller key'i olmayan region, shared job Redis failure, kaçırılmış backup ve gecikmiş restore/failover drill için alert üretin.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/tr/production-operasyonlari/multiregion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.