> 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/pluginler/configuration-scopes.md). # Configuration ve attachment scope Collection eklenti örneği, ortak yerleşim ve yürütme alanlarını pakete özel `config` nesnesiyle birleştirir. ```json { "name": "acl_control", "tenant_id": "tenant-a", "enabled": true, "trigger": "before_request", "scope": "gateway", "gateway_id": "gateway-1", "labels": { "owner": "platform" }, "priority": 90, "execution": { "timeout_ms": 1000, "hook_timeouts_ms": { "before_request": 250 }, "failure_threshold": 3, "recovery_timeout_ms": 30000, "failure_mode": "inherit", "max_concurrency": 32 }, "config": { "allowed_groups": ["gold"] } } ``` ## Ortak alanlar | Alan | Davranış | | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | `name` | Kurulu paketin tam adı. | | `enabled` | Örneğin runtime zincirine yüklenip yüklenmeyeceğini belirler. | | `trigger` | `before_request`, `after_response`, `on_error`, `stream`, `tcp`, `both`, `request_response` veya `all`. | | `scope` | `global`, `tenant`, `gateway`, `workspace`, `service`, `route`, `consumer` veya `consumer_group`. | | Kapsam seçicileri | `gateway_id`, `workspace_id`, `service_id`, `service_name`, `route_id`, `route_name`, `consumer_id` veya `consumer_group`. | | `labels` | Trafik eşleşmesini etkilemeyen operatör metadata'sı. | | `priority` | `-100000` ile `100000` arasında integer; yüksek değer önce çalışır. | | `execution` | Örneğe ait timeout, circuit, failure mode ve concurrency denetimleri. | | `config` | Kalıcı depolamadan önce doğrulanan, pakete özel JSON. | ## Kapsam eşleşmesi | Kapsam | Seçici | Eşleşme gereksinimi | | ---------------------- | -------------------------------- | --------------------------------------------------------- | | `global` veya `tenant` | Yok | Çözümlenen tenant trafiğiyle eşleşir. | | `gateway` | `gateway_id` | İstek seçilen gateway'i kullanmalıdır. | | `workspace` | `workspace_id` | İstek seçilen workspace'e ait olmalıdır. | | `service` | `service_id` veya `service_name` | Seçilen route ilgili service'e çözülmelidir. | | `route` | `route_id` veya `route_name` | Seçilen route eşleşmelidir. | | `consumer` | `consumer_id` | Eklenti çalışmadan önce eşleşen consumer doğrulanmalıdır. | | `consumer_group` | `consumer_group` | Doğrulanmış consumer belirtilen gruba ait olmalıdır. | Birden fazla seçici gönderildiğinde tüm seçiciler eşleşmelidir. Örneğin hem `gateway_id` hem `service_id` içeren service kapsamlı örnek yalnızca ilgili gateway'deki ilgili service'e uygulanır. Consumer ve consumer-group kapsamları belirlenmiş kimliğe bağlıdır. Korunan trafiğe desteklenen bir kimlik doğrulama eklentisi ekleyin; ardından ACL veya kapsamlı politikaları belirlenen consumer'a uygulayın. Tenant ve gateway örnekleri aynı istekle eşleşebilir. Kangal, etkin ve eşleşen tüm örnekleri çalıştırır; dar kapsam geniş kapsamın yerine geçmez. ## Trigger seçimi * `before_request`, upstream proxy işleminden önce çalışır. * `after_response`, response kullanılabilir olduktan sonra çalışır. * `both` ve `request_response`, request ve response stage'lerini birlikte seçer. * `on_error`, eşleşen request hatalarında çalışır. * `all`, paketin sunduğu tüm stage'leri seçer. Paket için belgelenen trigger'ı kullanın. `before_request` eklentisi response döndürüp upstream proxy işlemini durdurabilir; eşleşen response-stage eklentileri bu response'u yine işler. ## Belirlenebilir çalışma sırası Aynı collection stage içindeki eşleşen örnekler şu sırayla çalışır: 1. yüksek `priority`; 2. artan sırada eklenti `name` değeri; 3. artan sırada örnek ID'si; 4. son eşitlik bozucu olarak kaynak sırası. Request ve response stage'leri aynı sıralama yönünü kullanır. Eklentiler birbirine bağlıysa açık öncelik belirleyin. Örneğin kararını kullanan bir observability emitter'ından önce `sampling` çalıştırın. ## Collection ve inline route eklentileri Collection request-stage eklentileri, seçilen route'un inline eklentilerinden önce çalışır. Response ve hatalarda route-inline eklentiler collection eklentilerinden önce çalışır. Öncelikler her zincirin içinde değerlendirilir. Inline eklentileri route oluşturma veya güncelleme payload'ına ekleyin: ```json { "tenant_id": "tenant-a", "name": "orders", "path": "/orders", "service_id": "service-orders", "methods": ["POST"], "plugins": [ { "name": "oas_validation", "enabled": true, "trigger": "before_request", "priority": 200, "config": { "spec": { "openapi": "3.0.3", "info": { "title": "Orders", "version": "1.0.0" }, "paths": {} } } } ] } ``` Inline kayıtlar `name`, `enabled`, `config`, trigger/stage alanları ve `priority` destekler. Collection kapsam alanları collection örneklerine aittir. ## Yürütme politikası | Alan | Varsayılan | Aralık veya değerler | | --------------------- | ---------- | -------------------------------- | | `timeout_ms` | `5000` | `10..30000` | | `hook_timeouts_ms` | `{}` | Hook başına `10..30000` | | `failure_threshold` | `3` | Art arda `1..100` altyapı hatası | | `recovery_timeout_ms` | `30000` | `100..3600000` | | `failure_mode` | `inherit` | `inherit`, `fail_open`, `strict` | | `max_concurrency` | `32` | Örnek ve hook başına `1..256` | Yapılandırılmış hata eşiği aşıldığında örnek circuit'i recovery süresi boyunca açık kalır ve ardından iyileşmeyi test eder. Kimlik doğrulama, erişim denetimi, rate-limit, request protection, contract ve enforcement eklentileri runtime altyapı hatalarında fail-closed kalır. ## Sorun giderme | Belirti | Kontrol | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Paket kurulumu `409` döndürüyor | İstenen sürümü ve tenant paket durumunu doğrulayın. | | Oluşturma veya yapılandırma güncellemesi `422` döndürüyor | `config` alanını `config_schema` ile karşılaştırın; tam alan adlarını ve zorunlu alternatifleri doğrulayın. | | Örnek çalışmıyor | `enabled`, tenant, trigger, kapsam seçicileri ve isteğin çözümlenen gateway, service, route veya consumer değerini doğrulayın. | | Birden fazla örnek çalışıyor | Eşleşen tüm kapsamları inceleyin; birlikte çalışmaması gereken örnekleri kapatın veya daraltın. | | Eklenti sırası yanlış | Açık öncelikler belirleyin; collection ve inline zincirlerini ayrı inceleyin. | | Circuit açık | Timeout, failure ve concurrency metriklerini inceleyin; bağımlılığı düzeltip recovery probe'unun çalışmasına izin verin. | --- # 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/pluginler/configuration-scopes.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.