> 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/kavramlar/architecture.md). # Mimari Kangal, gateway yönetimini isteklerin işlenmesinden ayırır. Kontrol düzlemi, hedef yapılandırmayı ve operasyon geçmişini yönetir. Veri düzlemi ise bir gateway'in canlı istek yolunu işletir ve kabul ettiği yapılandırmayı uygular. ``` Operatörler ve otomasyon | | Konsol, Admin API, kangalctl v +---------------------- Kangal kontrol düzlemi -------------------+ | Gateway yapılandırması | Admin RBAC | Audit | Rollout | Worker | | MongoDB tabanlı hedef durum | Redis tabanlı runtime servisler| +-------------------------------+----------------------------------+ | | kapsamlı, checksum'lı config paketi | heartbeat, ACK/NACK, telemetry v +------------------------ Kangal veri düzlemi ---------------------+ | Route eşleştirme -> consumer belirleme -> plugin'ler -> target | | seçimi -> upstream proxy -> response plugin'leri -> telemetry | +-------------------------------+----------------------------------+ | v Müşteri servisleri ``` ## Ana bileşenler | Bileşen | Sorumluluk | Operasyon notu | | --------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Konsol | Müşterilerin gateway, route, policy, certificate, domain ve rollout iş akışlarını yürüttüğü arayüz. | Yönetim trafiği, herkese açık istek yolundan ayrı tutulur. | | Admin API | Tenant kapsamlı CRUD, doğrulama, entitlement kontrolleri, audit event'leri, snapshot'lar ve rollout koordinasyonu. | Her production değişikliğinden sonra veri düzlemi onayını doğrulayın. | | Yapılandırma deposu | Gateway, service, route, upstream, target, plugin, credential, certificate ve ilgili hedef durumu saklar. | Veri düzlemleri veritabanını sorgulamak yerine kendi kapsamlarına ait paketleri alır. | | Redis servisleri | Bunları kullanacak şekilde yapılandırılmış bileşenler için paylaşılan rate limit sayaçlarını ve job teslimini sağlar. | Her trafik policy'si, durumun paylaşımlı mı yoksa process başına mı olduğunu belirtir. | | Arka plan worker'ları | Entegrasyon job'larını ve özel domain certificate'larının oluşturulması, yenilenmesi ve uzlaştırılmasını yürütür. | Operatörler DNS sahiplik kayıtlarını yayınlar; doğrulama DNS üzerinde değişiklik yapmaz. | | Veri düzlemi | Kabul edilmiş gateway paketiyle trafiği eşleştirir ve proxy eder. | Bağımsız runtime yalnızca proxy trafiğini işler; yönetim endpoint'i veya MongoDB bağlantısı kullanmaz. | | Edge veya ingress | Herkese açık adresleri yayınlar, yapılandırıldığı yerde TLS'i sonlandırır ve trafiği veri düzlemine iletir. | Operatörler Kangal certificate ve domain binding'lerini seçilen edge üzerinde uygular. | ## Yapılandırma modeli Ana runtime grafiği şöyledir: ``` Gateway +-- Service --------------------------> doğrudan URL veya host | | | +-----------------------------> Upstream -> Target'lar | +-- Route -> Service veya Upstream | +-- istek eşleştirme kuralları +-- route düzeyindeki plugin'ler ``` * Bir **gateway**, tenant kapsamındaki yapılandırma ve runtime sınırıdır. * Bir **service**, bir uygulamaya nasıl ulaşılacağını tanımlar. Doğrudan URL kullanabilir veya bir upstream havuzuna başvurabilir. * Bir **route**, hangi isteklerin bir service veya upstream'i kullanacağını belirler. * Bir **upstream**, sağlık durumunu dikkate alan seçim için somut **target**'ları gruplar. * Bir **plugin**, istek yaşam döngüsünün bir veya daha fazla aşamasında çalışır. * Certificate, SNI, consumer, credential, Redis yapılandırmaları, vault ve AI Gateway ayarları da veri düzlemi paketlerine dahil edilir. Yapılandırma hem `tenant_id` hem de `gateway_id` ile kapsamlandırılır. Başka bir tenant veya gateway içinde aynı adın kullanılması, kaynakları birbiriyle eşdeğer hale getirmez. ## İstek yaşam döngüsü 1. Edge, isteği erişilebilir bir Kangal runtime'ındaki `/proxy/{path}` yoluna iletir. 2. `X-Tenant-ID` ve `X-Gateway-ID` birlikte gönderildiğinde kapsam seçiminde önceliklidir. Header'lardan biri eksikse eşlenmiş gateway host'u eksik kapsam değerini tamamlar. Host eşlenmemişse `X-Tenant-ID`; tenant'ın birden fazla gateway'i varsa `X-Gateway-ID` de gönderilmelidir. 3. Etkin route adayları path, method, host, SNI, header ve query parameter ölçütlerine göre değerlendirilir. 4. Birden fazla route eşleşirse Kangal önce açıkça tanımlanmış priority'yi, ardından path türü ve uzunluğunu; sonrasında host, SNI, header/query ve method özgüllüğünü karşılaştırır. 5. Seçilen route, service'ini ve gerektiğinde bir upstream target'ını çözümler. 6. `before_request` plugin'leri proxy işleminden önce isteğin kimliğini doğrulayabilir, isteği reddedebilir, dönüştürebilir veya ek bilgilerle zenginleştirebilir. 7. Kangal, hop-by-hop request header'larını kaldırır; yalnızca `preserve_host` etkinse özgün host'u korur ve upstream URL'ini `strip_path` ayarına göre oluşturur. 8. Response, yapılandırılmış response ve error aşamalarından geçer. Kangal; request veya response body'lerini analitik event yoluna eklemeden request, route, status, latency ve correlation metadata'sını kaydeder. Hiçbir route eşleşmezse `404` döner. HTTP method dışındaki tüm ölçütlerle eşleşen bir istek için `405` döner. Service veya target çözümlenemezse genellikle `502` gateway hatası döner. ## Kontrol düzlemi ile veri düzlemi senkronizasyonu Kayıtlı her düğümün sabit bir `node_id` değeri ve yalnızca oluşturulduğu anda görüntülenen bir node token'ı vardır. Düğüm heartbeat gönderir, yeni bir yapılandırmanın kullanılabilir olup olmadığını sorgular ve tam olarak bir tenant ile gateway'e ait paketi çeker. Kontrol düzlemi deterministik bir paket oluşturur, collection başına checksum ve paketin tamamı için SHA-256 checksum hesaplar. Herkese açık sürüm değeri, checksum'ın ilk 24 karakterinden türetilir. Düğüm; kapsamı, veri yapısını, checksum'ı, sürümü ve yapılandırılmışsa imzayı doğruladıktan sonra paketi atomik olarak etkinleştirir. Düğüm şu bilgileri raporlar: * Paket doğrulandıktan, cache'e alındıktan ve etkinleştirildikten sonra `ACK`; * paketi reddettiğinde doğrulama hatalarıyla birlikte `NACK`; * mevcut ve hedef sürümler; * heartbeat ve son görülme zamanları; * son bilinen iyi sürüm ve runtime modu. Bağımsız veri düzlemi, kontrol düzlemine erişilemediğinde imzalı son bilinen iyi cache ile çalışmaya devam edebilir. En az bir geçerli paket yüklenene kadar hazır duruma geçmez. Hazırlık kontrolünde cache'in güncelliği ve geçerliliği de doğrulanır. ## Rollout stratejileri | Strateji | Davranış | Tipik kullanım | | ----------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `immediate` | Generation'ı aşamalı dalgalar olmadan kullanıma açar. | Küçük ve düşük riskli düğüm grupları. | | `staged` | Operatörün ilerlettiği, boyutu sınırlandırılmış dalgalar halinde dağıtım yapar. | Rutin production değişiklikleri. | | `canary` | Küçük bir canary grubuyla başlar ve ilerletme onayını bekler. | Yüksek riskli route, plugin veya credential değişiklikleri. | Rollout'lar yakalanmış bir gateway snapshot'ını sabitler; böylece kontrol düzlemindeki sonraki düzenlemeler devam eden generation'ı değiştirmez. Hata sayısı ve hata oranı eşikleri etkin dalgaya göre değerlendirilir. Otomatik rollback etkinse ve kullanılabilir bir son bilinen iyi snapshot varsa Kangal, bu snapshot'ı rollback generation'ı olarak yayınlayabilir. Node özetinde bekleyen veya devam eden düğüm kalmadığında, gerekli tüm düğümler `ACK` verdiğinde ve mevcut sürümler rollout hedefiyle eşleştiğinde rollout operasyonel olarak tamamlanır. ## Deployment modelleri Kangal iki runtime modelini destekler: * Birleşik deployment'ta ana API process'i hem yönetim hem de proxy route'larını sunar. Bu model geliştirme ortamları ve daha küçük kurulumlar için uygundur. * Bağımsız deployment'ta yalnızca proxy işlevi gören veri düzlemi process'i, kontrol düzleminden ayrı çalışır ve MongoDB bağlantısı kullanmaz. Bu model production ortamları için güçlü bir izolasyon sınırı ve son bilinen iyi yapılandırmayla çalışmaya devam etme olanağı sağlar. Bir deployment profiliyle gateway oluşturulduğunda hedef ticari ve barındırma metadata'sı kaydedilir; proxy ve workspace metadata'sı üretilir. Trafiği açmadan önce veri düzlemi düğümünü, DNS kaydını, load balancer'ı ve TLS listener'ı ayrı ayrı doğrulayın. ## Güven sınırları * Admin API çağrıları, kimliği doğrulanmış bir yönetici ve tenant kapsamlı RBAC kullanır. * Runtime consumer kimlik doğrulamasını route veya global plugin'lerde uygulayın; Admin API token'ını consumer uygulamasına koymayın. * Herkese açık giriş noktalarında güvenilir edge, istemciden gelen `X-Tenant-ID` ve `X-Gateway-ID` değerlerini kaldırmalı ve bu yönetimsel kapsam header'ları kullanılıyorsa yetkili değerleri kendisi eklemelidir. Bu edge politikasını atlayan doğrudan runtime erişimini engelleyin. * Veri düzlemi node token'ları hash olarak saklanır ve düz metin halinde yalnızca oluşturma veya rotation sırasında döndürülür. * Bir düğüm, certificate doğrulamasından sonra güvenilir TLS terminator'ın eklediği client certificate fingerprint'ine de sabitlenebilir. * Yapılandırma paketleri ve yerel cache'ler imza ve anti-rollback kontrollerini destekler. Çevrimdışı başlatmanın güvenli çalışması için sabit cache güven materyalini koruyun. * Özel domain DNS ve issuer credential'ları response ve audit kayıtlarında maskelenir. ## Operasyon sorumlulukları * Üretilen `proxy_url` için DNS, ingress, TLS ve bir proxy isteğini doğrulayın. * Certificate veya SNI kaydını değiştirdikten sonra dış edge'in beklenen certificate'ı sunduğunu doğrulayın. * Özel domain binding'leri için deployment'a uygun edge reconciliation veya release sırasında ingress yapılandırması uygulayın. * Trafik policy'lerini, her plugin için belirtilen durum kapsamına göre boyutlandırın; process başına sayaçlar ve circuit'ler her worker'ı bağımsız olarak korur. * Gateway, service veya upstream silmeden önce bağımlı kaynakları kaldırın ya da başka bir hedefe yönlendirin; silme işlemleri bağımlılıklara otomatik olarak yayılmaz. Node kaydı ve rollout'lar için [Gateway'ler ve veri düzlemleri](/tr/gateway/gateways-data-planes.md), istek eşleştirme için [Service'ler ve route'lar](/tr/gateway/services-routes.md) sayfasıyla devam edin. --- # 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/kavramlar/architecture.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.