> 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/configuration.md). # Configuration yaşam döngüsü Kangal Admin API bir tenant'ın declarative yapılandırmasını export edebilir, yerel veya sunucu tarafında doğrulayabilir, canlı durumla karşılaştırabilir, seçili kaynakları import edebilir, bundle senkronize edebilir ve tenant snapshot'ı oluşturup geri alabilir. Bu akışları kontrollü promotion ve recovery için kullanın; veritabanı yedeğinin yerine koymayın. Import işlemleri sırayla çalışır ve tek bir veritabanı transaction'ı içinde değildir. Import'ın sonlarında oluşan hata, önceki kaynakları uygulanmış bırakabilir. ## Yapılandırma bundle'ı Bundle, opsiyonel `tenant_id` ile kaynak dizileri içeren JSON veya YAML belgesidir: ```yaml tenant_id: tenant-acme gateways: [] services: [] routes: [] upstreams: [] targets: [] redis_configs: [] certificates: [] ca_certificates: [] snis: [] vaults: [] consumers: [] consumer_credentials: [] ai_gateway_configs: [] metrics: [] ``` Yalnızca yönetmek istediğiniz kaynak dizilerini ekleyin. Canlı bir kaynak bundle'da yok diye import tarafından silinmez. ## API iş akışı En güvenli promotion sırası: 1. Hedef tenant'ı export edin ve artifact'i güvenli saklayın. 2. Desired bundle'ı strict referans kontrolüyle doğrulayın. 3. Desired state ile canlı tenant arasında diff alın. 4. Sync'i dry-run çalıştırıp validation, count ve önerilen değişiklikleri inceleyin. 5. Pre-apply snapshot ve operatör notuyla sync apply yapın. 6. Yeniden export edip oluşan durumu karşılaştırın. 7. Snapshot ve secret sınırlarını anladıktan sonra gerektiğinde rollback yapın. Temel endpoint'ler: | Method ve path | Davranış | | --------------------------------------------------- | ------------------------------------------------------------------------ | | `GET /api/v1/admin/config/export` | Tenant bundle'ını JSON veya YAML export eder. | | `POST /api/v1/admin/config/validate` | Gönderilen JSON/YAML bundle'ı doğrular. | | `POST /api/v1/admin/config/diff` | Desired bundle ile canlı tenant durumunu karşılaştırır. | | `POST /api/v1/admin/config/import` | Eşleşen kaynakları ekler veya overwrite eder; API varsayılanı apply'dır. | | `POST /api/v1/admin/config/sync` | Doğrular, diff alır, opsiyonel snapshot oluşturur ve import eder. | | `POST /api/v1/admin/config/snapshots` | Desteklenen tenant configuration bundle'ının snapshot'ını oluşturur. | | `GET /api/v1/admin/config/snapshots` | Tenant snapshot özetlerini listeler. | | `POST /api/v1/admin/config/snapshots/{id}/rollback` | Snapshot import'ını doğrular veya uygular. | Tüm yapılandırma route'ları admin bearer token gerektirir. Validation, diff, dry-run, snapshot oluşturma ve rollback preview işlemleri `POST` olarak uygulandığı için canlı kaynak değiştirmese de writer rolü veya `admin:write` Admin API scope'u ister. Export ve snapshot listeleme için read erişimi yeterlidir. `tenant_id` değeri configuration hedefini açıkça seçer. Tenant-scoped token kullanın; query ve body tenant değerlerini hedef tenant ile eşleştirin ve her write öncesi aktif context'i doğrulayın. Sync, query/payload tenant uyuşmazlığını reddeder. ## JSON ve YAML YAML request body için `Content-Type: application/yaml` veya `?format=yaml` kullanın. YAML export için `Accept: application/yaml` ya da `?format=yaml` seçin. ```bash curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Accept: application/yaml' \ "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID" \ -o tenant-acme.yaml curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/yaml' \ "$KANGAL_URL/api/v1/admin/config/validate?strict=true" \ --data-binary @tenant-acme.yaml | jq ``` Bozuk JSON/YAML `400` döndürür. Yapısal olarak parse edilen fakat request modelini geçemeyen body normalde `422` döndürür. Yapılandırma validation veya diff önkoşulları ayrıntılı `400` üretebilir. ## Kimlik eşleştirme Import bir kaynağın mevcut olup olmadığını declarative identity alanlarıyla belirler: | Kaynak | Eşleşme kimliği | | ---------------------------------------------- | ---------------------------------- | | Gateway | tenant + name | | Service | tenant + gateway + name | | Route | tenant + gateway + path | | Upstream | tenant + gateway + name | | Target | tenant + gateway + upstream + name | | Redis config, certificate, CA certificate, SNI | tenant + gateway + name | | Vault | tenant + gateway + prefix | | Consumer | tenant + username | | Consumer credential | consumer + type + key | | AI gateway config | tenant + gateway + kind + name | | Metric | gateway ID | `overwrite: false` ise eşleşen canlı kaynak atlanır. `overwrite: true` ise eşleşen belge desired kaynakla değiştirilir; yoksa eklenir. Varsayılanları dikkatle inceleyin: doğrudan API import'unda `dry_run=false`, `overwrite=false`; API sync'te `dry_run=true`, `overwrite=true`, `strict=true`, `snapshot_before_apply=true` varsayılandır. ## Secret yönetimi Public export plaintext secret'ları redakte eder. Redakte placeholder inceleme için güvenlidir, ancak geri getirilebilir bir secret değildir. Importer'ın overwrite sırasında redakte placeholder'ı önceki değerle koruyacağına dair genel bir garanti yoktur. Bu nedenle: * Kontrollü secret referanslarını veya amaçlanan değerleri geri koymadan redakte export'u `overwrite=true` ile uygulamayın. * Bundle içinde plaintext yerine vault/secret referansı ve ayrı secret delivery tercih edin. * Redaksiyon sonrası bile export ve snapshot'ları hassas artifact olarak saklayın; topoloji, consumer kimlikleri, route ve certificate bilgileri operasyonel veridir. * Recovery için güvenmeden önce rollback'i temsili credential'larla non-production tenant'ta test edin. Configuration snapshot'ları bu sayfada listelenen exported bundle alanlarını saklar. Pre-apply sync snapshot'ı aynı export yolundan üretildiği için rollback'te aynı redaksiyon uyarısı geçerlidir. Diğer yönetim verilerini kendi API export ve veritabanı yedek prosedürüyle koruyun. ## Sınırlar ve davranış * Snapshot listesinde `limit` varsayılanı 20, üst sınırı 100'dür. Shared list pagination header'ı yerine düz dizi döner. * Snapshot version tenant içinde artar; SHA-256 checksum ve kaynak bazlı count içerir. * Strict validation eksik service/upstream referanslarını warning yerine error yapar. * Import dolu kaynak koleksiyonlarını sırayla işler ve desired bundle'da olmayan kaynakları silmez. * Snapshot rollback validation ve import davranışını yeniden kullanır; transactional veritabanı rewind değildir. ## Araç seçimi Context yönetimi, yerel validation, diff, export, import, sync ve CRUD için [`kangalctl`](/tr/configuration-ve-otomasyon/kangalctl.md) kullanın. Snapshot create/list/rollback için [Import, export ve rollback](/tr/configuration-ve-otomasyon/import-export-rollback.md) bölümündeki Admin API komutlarını kullanın. ## Operasyon kontrol listesi Apply öncesi: * API URL, aktif context, token scope ve tenant'ı doğrulayın. * Yapılandırma snapshot'ına ek olarak veritabanı yedeği tutun. * Desired artifact'e amaçlanan secret veya secret referanslarını ekleyin. * Local validation, server strict validation, diff ve sync dry-run çalıştırın. * Her `would_insert`, `would_update` ve `would_skip` sayısını inceleyin. * Bundle'da olmayan kaynakların bilinçli olarak korunacağını doğrulayın. Apply sonrası: * Canlı durumu export edip desired state ile karşılaştırın. * Değişen her gateway'de en az bir route'u deneyin ve yakın trafiği inceleyin. * Uygulama loglarını, Admin API hatalarını ve audit kayıtlarını kontrol edin. * Snapshot ID, operatör, kaynak revision ve doğrulama sonucunu kaydedin. ## Sorun giderme | Belirti | Çözüm | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Validation/diff read token ile `403` | Bunlar `POST` route'larıdır ve `admin:write` gerektirir. | | YAML, geçersiz JSON gibi parse ediliyor | `Content-Type: application/yaml` gönderin veya `?format=yaml` ekleyin. | | Strict validation bir referansta başarısız | Referans verilen service/upstream'i bundle'a ekleyin veya kimliği düzeltin. | | Import mevcut kaynağı güncellemedi | `overwrite=true` ayarlayın; önce preview alın. | | Dosyada olmayan kaynaklar silinmedi | Beklenen davranış: import pruning yapmaz, ekler/değiştirir. Kaynakları kendi Admin API'siyle açıkça silin. | | Sync tenant mismatch reddi veriyor | Query ve body `tenant_id` değerlerini eşitleyin, aktif token tenant'ını doğrulayın. | | Rollback secret yerine `[redacted]` getiriyor | Etkilenen entegrasyon trafiğini durdurup kontrollü secret değerini/referansını geri yükleyin; snapshot secret yedeği değildir. | | Apply yarıda hata verdi | Durumu kısmen uygulanmış sayın, canlı export alın, diff yapın ve forward fix veya test edilmiş rollback seçin. | --- # 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/configuration.md?ask=&goal= ``` `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.