> 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/gateway/services-routes.md). # Service ve route Service'ler trafiğin nereye gideceğini, route'lar ise hangi isteklerin bu hedefi kullanacağını tanımlar. Bu ayrım sayesinde birden fazla route; timeout, retry ve upstream havuzu ayarlarını hedef yapılandırmasını tekrarlamadan paylaşabilir. ## Service hedef modunu seçin | Mod | Kullanım amacı | Zorunlu alanlar | | --------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Doğrudan URL | Tek ve sabit bir HTTP endpoint'i yeterli olduğunda. | `url` veya `protocol` ile `host`; isteğe bağlı `port`/`path`. | | Upstream havuzu | Service birden fazla target, sağlık durumu veya load balancing gerektirdiğinde. | `upstream_id` veya `upstream_name`. | Admin API; `url`, `host`, `upstream_id` veya `upstream_name` alanlarından en az birini gerektirir. Konsolda bu seçim **Doğrudan URL / host** veya **Upstream havuzu** olarak sunulur. ## Konsolda service oluşturun 1. Bir gateway açın ve **Service'ler** bölümünü seçin. 2. **Service oluştur** seçeneğini belirleyin. 3. Bu gateway içinde benzersiz bir service adı girin. 4. Hedef modunu seçin. 5. Doğrudan hedef için tam URL veya host bileşenlerini girin. 6. Havuz kullanmak için mevcut bir upstream seçin. 7. Retry ile bağlantı, okuma ve yazma timeout değerlerini ayarlayın. 8. Kaydedin ve ardından service'e başvuran bir route oluşturun. Aynı tenant ve gateway içinde aynı service adını yeniden oluşturma isteği, duplicate kaynak üretmek yerine mevcut kaynağı döndürür. ## Service alanları | Alan | Varsayılan | Anlam ve doğrulama | | -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- | | `tenant_id` | yok | Zorunludur ve yönetici tenant'ıyla eşleşmelidir. | | `name` | yok | Zorunludur. Konsol değerin boş olmadığını doğrular. | | `url` | yok | `http://` veya `https://` içeren tam temel URL. URL'deki mevcut path korunur. | | `protocol` | `http` | `host` ile kullanılır; desteklenen değerler `http` ve `https`'tir. | | `host` | yok | Hostname veya adres. Bu alandaki tam URL de runtime tarafından kabul edilir. | | `port` | şema varsayılanı | Konsolda pozitif tam sayı. Birleştirilmiş URL'de `80` ve `443` portları gösterilmez; diğer portlar eklenir. | | `path` | yok | Birleştirilmiş host URL'ine eklenen temel path. Kangal gerektiğinde başına `/` ekler. | | `upstream_id` | yok | Aynı gateway'deki bir upstream'e tercih edilen sabit referans. | | `upstream_name` | yok | Upstream'i çözümlemek için kullanılan ad alternatifi. | | `retries` | `5` | İlk denemeden sonra desteklenen runtime aralığı 0-5 retry'dır. | | `connect_timeout_ms` | `60000` | Konsol aralığı 100-300000 ms. Upstream bağlantısını kurmak için tanınan süre. | | `read_timeout_ms` | `60000` | Konsol aralığı 100-300000 ms. Ayrı `timeout_ms` yoksa genel timeout olarak da kullanılır. | | `write_timeout_ms` | `60000` | Konsol aralığı 100-300000 ms. İsteği upstream'e yazmak için tanınan süre. | | `labels` | `{}` | API filtreleme ve otomasyonda kullanılan metadata. | İçe aktarılan yapılandırmada timeout ve retry değerleri mevcut olduğunda route, service, ardından upstream sırasıyla değerlendirilir. Konsol, service düzeyindeki değerleri düzenler. ### Retry davranışı Runtime varsayılan olarak yalnızca replay açısından güvenli `GET`, `HEAD`, `OPTIONS`, `PUT` ve `DELETE` isteklerinde dönen `502`, `503` ve `504` yanıtlarını yeniden dener. Yapılandırılan `retries` değeri ilk denemeden sonraki tekrar sayısıdır; `retries: 2` en fazla üç denemeye izin verir. Retry'ı yalnızca isteğin tamamı güvenle replay edilebiliyorsa etkinleştirin. Güvenilmeyen request body'leri için retry'ı açmadan önce hem herkese açık edge'de hem de route üzerinde açık bir request-size politikası zorunlu kılın. İş operasyonlarında idempotency stratejisi uygulayın. ## Konsolda route oluşturun 1. Gateway'in **Route'lar** bölümünü açın ve **Yeni route** seçeneğini belirleyin. 2. Herkese açık path'i girin. 3. Bir service seçin. Service ile temsil edilmeyen doğrudan upstream adı veya URL için **Legacy upstream** kullanın. 4. Virgülle ayrılmış HTTP method'larını ve isteğe bağlı host'ları girin. 5. `exact`, `prefix` veya `regex` path eşleştirmesini seçin. 6. Eşleşen path'in çıkarılıp çıkarılmayacağını ve gelen host'un korunup korunmayacağını belirleyin. 7. Route'lar çakışıyorsa açık bir priority değeri ayarlayın. 8. Route plugin'lerini atayın ve kaydedin. ## Route alanları | Alan | Varsayılan | Anlam ve doğrulama | | ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tenant_id` | yok | Zorunludur ve tenant kapsamındadır. | | `name` | yok | İsteğe bağlı görünen ad. | | `path` | yok | Zorunludur. Öngörülebilir görüntüleme ve yeniden yazma için başına `/` ekleyin. | | `path_type` | `exact` | `exact`, `prefix` veya `regex`. `~` ile başlayan path de matcher tarafından regex olarak değerlendirilir. | | `methods` | `["GET"]` | Büyük/küçük harfe duyarsızdır. `GET` izni olan route, `HEAD` ile de eşleşir. `*` ve `ANY` tüm method'larla eşleşir. | | `hosts` | `[]` | Büyük/küçük harfe duyarsız host kalıpları. Port numaraları dikkate alınmaz. `*` wildcard desteklenir. Boş liste tüm host'ları kabul eder. | | `snis` | `[]` | Wildcard destekli, büyük/küçük harfe duyarsız TLS server name kalıpları. Boş liste tüm SNI değerlerini kabul eder. | | `headers` | `{}` | Adı verilen her header, izin verilen değerlerden biriyle eşleşmelidir. Header adları ve değerleri büyük/küçük harfe duyarsız karşılaştırılır; `*`, header mevcutsa tüm değerleri kabul eder. | | `query_params` | `{}` | Adı verilen her query parameter, izin verilen değerlerden biriyle eşleşmelidir. Query değerleri büyük/küçük harfe duyarlıdır; `*`, parameter mevcutsa tüm değerleri kabul eder. | | `service_id` / `service_name` | yok | Aynı tenant ve gateway içindeki bir service'i çözümler. ID'yi tercih edin; okunabilirlik için adı da ekleyin. | | `upstream` | yok | Mantıksal upstream ID/adı veya tam HTTP/HTTPS URL'i. Tek bir hedef stratejisi kullanın. | | `strip_path` | `true` | Request path'i hedef temel path ile birleştirmeden önce eşleşen route prefix'ini kaldırır. | | `preserve_host` | `false` | `true` olduğunda özgün `Host` header'ını iletir; aksi durumda HTTP client upstream host'unu belirler. | | `priority` | `0` | Tam sayı. Konsol 0-1.000.000 aralığını kabul eder. Yüksek değerler özgüllük puanından önce kazanır. | | `plugins` | `[]` | Doğrulanmış route plugin atamaları. Bu alan güncellendiğinde route'un plugin dizisinin tamamı değiştirilir. | | `labels` | `{}` | Ownership ve otomasyon metadata'sı. | Create API; `upstream`, `service_id` veya `service_name` alanlarından en az birini gerektirir. Oluşturmadan önce başvurulan kaynakların aynı tenant ve gateway'e ait olduğunu doğrulayın. Çözümlenemeyen bir referans, istek yolunda `502` döndürür. ## Gelişmiş API örneği Bu route, yalnızca host, version header'ı ve query parameter birlikte eşleştiğinde `GET` isteğini kabul eder: ```json { "tenant_id": "tenant-acme", "name": "orders-v2-read", "path": "/orders", "path_type": "prefix", "methods": ["GET"], "hosts": ["api.example.com"], "snis": ["api.example.com"], "headers": {"X-API-Version": ["2"]}, "query_params": {"region": ["eu", "us"]}, "service_id": "service-id", "service_name": "orders-service", "strip_path": true, "preserve_host": false, "priority": 200, "plugins": [], "labels": {"version": "v2"} } ``` ```bash curl -sS -X POST \ "$KANGAL_API_URL/api/v1/admin/gateways/$GATEWAY_ID/routes" \ -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d @route.json ``` Yapılandırılan tüm eşleştirme boyutları AND ile birleştirilir. Tek bir header, query, host, SNI veya method boyutundaki liste değerleri alternatiflerdir. ## Route seçimi nasıl çalışır? Kangal, isteğin tenant ve gateway kapsamındaki etkin route'ları yükler, tüm yapılandırılmış matcher'ları değerlendirir ve eşleşmeleri şu sırayla sıralar: 1. Daha yüksek açık `priority`. 2. Path türü: önce exact, ardından regex, sonra prefix. 3. Daha uzun eşleşen path. 4. Host kısıtlaması bulunan route. 5. SNI kısıtlaması bulunan route. 6. Daha fazla header ve query kısıtlaması. 7. Wildcard yerine belirli bir method. 8. Son deterministik eşitlik bozucu olarak sabit route kimliği. Açık priority ilk sırada olduğundan geniş kapsamlı ve yüksek priority'li bir route, daha özgül ancak düşük priority'li bir route'un önüne geçebilir. Priority'yi yalnızca çakışmanın bilinçli olduğu durumlarda kullanın. ### Path davranışı | Route | İstek | Eşleşme | | ----------------------- | -------------------- | ----------------------------------------------------------------------------- | | `exact /orders` | `/orders` | evet | | `exact /orders` | `/orders/42` | hayır | | `prefix /orders` | `/orders` | evet | | `prefix /orders` | `/orders/42` | evet | | `prefix /orders` | `/orders-old` | hayır | | `regex ^/orders/[0-9]+` | `/orders/42/details` | evet; regex eşleştirmesi baştan başlar ve path'in tamamını tüketmesi gerekmez | Geçersiz saklanmış regular expression'lar caller'a hata döndürmek yerine eşleştirme sırasında atlanır. Yazım hatasının `404` sonucuna yol açmaması için regex'leri rollout öncesinde doğrulayın. ## Path yeniden yazma örnekleri Hedef service URL'i: `https://orders.internal/api` | Route path | Request path | `strip_path` | Upstream path | | ---------- | ------------ | ------------ | ---------------- | | `/orders` | `/orders/42` | `true` | `/api/42` | | `/orders` | `/orders/42` | `false` | `/api/orders/42` | | `/` | `/orders/42` | `true` | `/api/orders/42` | Gelen query string, temel URL'de bulunan query'ye eklenir. Her iki konuma da kalıcı secret koymayın. ## Güvenli değişiklik akışı 1. Path, host veya priority değiştirmeden önce route'ları listeleyin ve çakışmaları belirleyin. 2. Yalnızca hedeflenen alanları patch edin. Boş patch `400` döner. 3. Plugin değişikliklerinde hedeflenen plugin dizisinin tamamını gönderin. 4. Her matcher boyutu için bir pozitif ve bir negatif istek test edin. 5. Path yeniden yazmayı route kökünde ve en az bir alt path'te test edin. 6. Bağımsız deployment'ta yeni route'un tüm düğümlerde etkin olduğunu kabul etmeden önce rollout'u tamamlayın ve ACK'leri doğrulayın. 7. Request ID'leri, status code'ları, upstream latency'yi ve hata oranını izleyin. ## Silme davranışı Service ve route silme işlemleri, kapsamlı Admin API'de kalıcı silme uygular. Service silmeden önce bağımlı route'ları başka bir hedefe yönlendirin veya silin. Aksi durumda bu route'lar `502 Route service not resolved` döndürür. ## Sorun giderme ### `404 Route not found` Tenant ve gateway kapsamını, path türünü, port numarası çıkarılmış host'u, SNI iletimini, header değeri büyük/küçük harfini, query değeri büyük/küçük harfini ve route etkinlik durumunu doğrulayın. Özel domain için edge'in Kangal tarafından çözümlenebilen bir host veya kapsam ilettiğini de kontrol edin. ### `405 Method not allowed for route` Path ve method dışındaki matcher'lar eşleşmiştir. Gerekli method'u bilinçli olarak ekleyin; hatayı gizlemek için listeyi `*` ile değiştirmeyin. ### Yanlış route seçiliyor Önce açık priority değerlerini karşılaştırın. Ardından exact/regex/prefix türünü ve eşleşen path uzunluğunu inceleyin. Geniş route'un priority'sini azaltın veya matcher'larını daraltın. ### Upstream path'i yanlış Service temel path'ini ve `strip_path` değerini inceleyin. Kangal path'leri birleştirir ve service URL'indeki mevcut path'i korur. ### Özgün host beklenmedik biçimde backend'e ulaşıyor `preserve_host` etkindir. Backend herkese açık host'a göre bilinçli olarak route etmiyorsa bu ayarı kapatın. ### Güncellenen timeout değerleri etkin değil Etkin veri düzlemi paketinin güncel service'i içerdiğini ve içe aktarılan route veya upstream düzeyi değerinin öncelik almadığını doğrulayın. Proxy runtime, beşin üzerindeki retry değerlerini beş ile sınırlar. --- # 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/gateway/services-routes.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.