> 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/configuration-ve-otomasyon/import-export-rollback.md).

# Import, export, diff ve rollback

Bu runbook tam Admin API akışını kapsar. Örnek kimlikleri değiştirin ve bearer token'ları mümkün olduğunca shell history dışında tutun.

```bash
export KANGAL_URL='https://kangal.example.com'
export KANGAL_TOKEN='kangaladm_...'
export TENANT_ID='tenant-acme'
```

## 1. Canlı state'i export etme

JSON:

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Accept: application/json' \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID&format=json" \
  -o "${TENANT_ID}-before.json"
```

YAML:

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Accept: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID&format=yaml" \
  -o "${TENANT_ID}-before.yaml"
```

Export tenant gerektirir ve plaintext secret'ları redakte eder. Artifact'in parse edildiğini doğrulayın, operasyonel olarak hassas saklayın ve credential yedeği saymayın.

## 2. Desired state'i doğrulama

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/validate?strict=true&format=yaml" \
  --data-binary @desired.yaml | tee validation.json | jq
```

Validation request şeması sorunlarını, tekrarlanan declarative identity'leri, plugin configuration hatalarını ve kaynak referanslarını bulur. `strict=false` iken eksik service/upstream referansı warning olabilir; `strict=true` iken error olur.

Validation bir `POST` işlemidir; canlı kaynağı değiştirmese de write izni ister.

## 3. Desired ve live state diff'i

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/diff?tenant_id=$TENANT_ID&strict=true&format=yaml" \
  --data-binary @desired.yaml | tee diff.json | jq
```

Yanıt her kaynak türünü added, removed ve changed olarak gruplar; before/after değerlerini, değişen alanları ve özeti içerir. Desired kaynak canlıda yoksa added, canlı kaynak desired'da yoksa removed görünür. Ancak import/sync bunu otomatik silmez.

Diff için query veya bundle içinde `tenant_id` gerekir. Boş olmayan `removed` kümesini silme planı değil, inceleme uyarısı olarak değerlendirin.

## 4. Import preview ve apply

`POST /config/import`, bundle alanlarını ve `overwrite` değerini en üst seviyede kabul eder. Query'deki `dry_run` varsayılanı `false` olduğu için otomasyonda değeri her zaman açıkça yazın.

JSON request örneği:

```bash
jq '. + {overwrite: true}' desired.json > import-request.json

curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/import?dry_run=true" \
  --data-binary @import-request.json | tee import-preview.json | jq
```

Validation sonucunu, bundle fingerprint'ini, kaynak sayılarını, diff'i ve `would_insert`, `would_update`, `would_skip` sayılarını inceleyin. Ardından aynı artifact'i uygulayın:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/import?dry_run=false" \
  --data-binary @import-request.json | tee import-result.json | jq
```

`overwrite=false` eşleşen kaynakları atlar. `overwrite=true` eşleşen belgeleri değiştirir. Import sıralı, non-transactional ve non-pruning çalışır.

## 5. Promotion için sync tercih etme

Sync; strict validation, live export, diff, preview, opsiyonel snapshot ve import'ı birleştirir. API varsayılanları dry-run, overwrite, strict validation ve pre-apply snapshot'tır.

YAML body örneği:

```yaml
tenant_id: tenant-acme
overwrite: true
dry_run: true
strict: true
snapshot_before_apply: true
snapshot_note: release 2026.07.17
created_by: change-1842
gateways: []
services: []
routes: []
upstreams: []
targets: []
```

Preview:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/sync?tenant_id=$TENANT_ID&format=yaml" \
  --data-binary @sync-request.yaml | tee sync-preview.json | jq
```

Apply için incelenmiş bir kopyada `dry_run` değerini `false` yapıp aynı endpoint'e gönderin. Endpoint query ile payload tenant ID uyuşmazlığını reddeder.

Production değişikliğinde yalnızca zaman kazanmak için `snapshot_before_apply=false` yapmayın. Snapshot yararlı yapılandırma kanıtıdır; yine de redaksiyon ve non-transactional rollback sınırlarına tabidir.

## 6. Snapshot oluşturma ve listeleme

Manuel snapshot oluşturma:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots?tenant_id=$TENANT_ID" \
  -d '{"note":"certificate rotation öncesi","created_by":"change-1842"}' \
  | tee snapshot.json | jq

SNAPSHOT_ID=$(jq -r '.id' snapshot.json)
```

En yeni version'ları önce listeleme:

```bash
curl -fsS -G \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  --data-urlencode "tenant_id=$TENANT_ID" \
  --data-urlencode 'limit=20' \
  "$KANGAL_URL/api/v1/admin/config/snapshots" | jq
```

Listede `limit` aralığı `1..100`, varsayılan 20'dir. Her snapshot tenant'a göre version, checksum, count, note, creator ve oluşturma zamanı içerir.

## 7. Rollback preview

Rollback veritabanı rewind değil, seçilen snapshot'ın import edilmesidir. Önce preview alın:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots/$SNAPSHOT_ID/rollback?tenant_id=$TENANT_ID" \
  -d '{"overwrite":true,"dry_run":true}' \
  | tee rollback-preview.json | jq
```

Snapshot lookup tenant-scoped'dur; bilinmeyen ID veya yanlış tenant `404` döndürür. Rollback öncesi strict validation çalışır.

Apply öncesi doğrulayın:

* Snapshot tenant, timestamp, checksum, note ve kaynak sayıları.
* Hangi canlı kaynakların değişeceği ve hangilerinin korunacağı.
* Snapshot redakte değer içeriyorsa secret/credential'ların nasıl geri yükleneceği.
* Veritabanı yedeği ve forward-recovery planı.
* Bakım penceresi ve route bazlı smoke test'ler.

## 8. Rollback apply

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots/$SNAPSHOT_ID/rollback?tenant_id=$TENANT_ID" \
  -d '{"overwrite":true,"dry_run":false}' \
  | tee rollback-result.json | jq
```

Rollback API varsayılanı `overwrite=true`, `dry_run=false`'dur; açık değerler operatör niyetini incelenebilir yapar. Uygulama sıralı olduğu için istek başarılı dönse bile sonucu ve canlı export'u inceleyin.

## 9. Doğrulama

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID" \
  -o "${TENANT_ID}-after.json"

curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/gateways/gw-production/overview" | jq

curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/gateways/gw-production/traffic/recent?limit=20" | jq
```

Değişen route'lardan sentetik istek geçirin, yakın trafik ile uygulama hatalarını inceleyin ve son export'u amaçlanan bundle ile karşılaştırın. Before/after artifact'leri ve API sonuçlarını değişiklik kaydıyla birlikte saklayın.

## Hata yönetimi

| Hata                         | Eylem                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| Parse veya schema hatası     | JSON/YAML yapısını düzeltin; `400` parse/config hatası ile `422` request validation farkını ayırın.  |
| Strict referans hatası       | Referansı düzeltin veya dependency'yi ekleyin; incelemeden strict modu kapatmayın.                   |
| Apply sırasında timeout      | Kısmi uygulama ihtimalini kabul edin. Tekrar denemeden canlı export alın.                            |
| Kısmi import                 | Live state ile desired state diff'i alın; forward fix veya test edilmiş snapshot rollback uygulayın. |
| Redakte credential uygulandı | Etkilenen entegrasyon trafiğini durdurun ve yetkili secret sisteminden credential'ı geri yükleyin.   |
| Snapshot bulunamadı          | Tenant ve ID'yi doğrulayın; snapshot başka tenant lookup kapsamında alınamaz.                        |
| Beklenmeyen kaynaklar kaldı  | Non-pruning import için beklenen davranıştır. Dependency incelemesinden sonra açıkça silin.          |


---

# 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/configuration-ve-otomasyon/import-export-rollback.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.