> 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/upstreams-targets.md). # Upstream ve target Upstream, adlandırılmış bir hedef havuzudur. Target'lar ise bu havuzdaki somut HTTP veya HTTPS endpoint'leridir. Bir service birden fazla backend, health bilgisi veya runtime target seçimi gerektiriyorsa upstream kullanın. Standart trafik zinciri şöyledir: ``` request -> route -> service -> upstream -> target ``` Tek ve sabit bir backend için doğrudan URL içeren bir service daha basittir. Bir havuz kullanacaksanız önce upstream ve target'ları oluşturun, ardından service'i upstream'e bağlayın. ## Başlamadan önce Şunlara ihtiyacınız vardır: * Bir gateway ve gateway ID'si. * Tenant ID'si ve Admin API bearer token'ı. * Kangal runtime tarafından erişilebilen en az bir backend URL'si. * Kimlik doğrulamasız `GET` health isteğini kabul eden bir target base URL'si. Örnekler versioned Admin API'yi kullanır: ```bash export KANGAL_ADMIN_URL="https://control.example.com" export KANGAL_TOKEN="replace-with-admin-token" export KANGAL_TENANT_ID="tenant_123" export KANGAL_GATEWAY_ID="gateway_123" ``` ## Upstream oluşturma ### Console adımları 1. Bir gateway açın ve **Upstreams** bölümünü seçin. 2. **Create upstream** seçeneğini seçin. 3. Backend havuzunu tanımlayan bir ad girin. 4. İsteğe bağlı olarak bir fallback URL girin. 5. Upstream'i kaydedin ve target eklemek için açın. ### Admin API ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/upstreams" \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tenant_id": "'"$KANGAL_TENANT_ID"'", "name": "checkout-pool", "url": "https://checkout-fallback.internal.example" }' ``` Aynı tenant ve gateway içinde aynı upstream adıyla yinelenen oluşturma isteği, mevcut upstream'i döndürür. Bu davranış tekrarlanabilir provisioning işlemlerini güvenli kılar. URL'yi değiştirmek için update işlemini kullanın. ## Upstream alanları | Alan | Zorunlu | Davranış | | ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------ | | `tenant_id` | Oluşturmada evet | Tenant sahipliğini ve yetkilendirme kapsamını belirler. | | `name` | Evet | Tenant ve gateway içinde benzersiz addır. Service'ler upstream'e ad veya ID ile başvurabilir. | | `url` | Hayır | Tam HTTP veya HTTPS fallback URL'sidir. Havuzda kullanılabilir target yoksa trafik bu URL'ye gönderilebilir. | | `labels` | Hayır | Otomasyon ve envanter için update API tarafından kabul edilen metadata'dır. | Oluşturma ve güncelleme akışları target seçiminde round-robin kullanır. ## Target ekleme Oluşturma response'undan veya listeleme işleminden upstream ID'sini alın ve bir ya da daha fazla target ekleyin. ```bash export KANGAL_UPSTREAM_ID="upstream_123" curl -sS -X POST \ "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/targets" \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "upstream_id": "'"$KANGAL_UPSTREAM_ID"'", "name": "https://checkout-a.internal.example" }' ``` İkinci target'ı aynı şekilde ekleyin: ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/targets" \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "upstream_id": "'"$KANGAL_UPSTREAM_ID"'", "target": "https://checkout-b.internal.example" }' ``` `name` ve `target`, target adresi için kabul edilen eşdeğer alanlardır; en az biri zorunludur. Adres `http://` veya `https://` ile başlayan tam bir URL olmalıdır. `10.0.1.5:8000` gibi yalnızca host ve port içeren bir değer yerine `http://10.0.1.5:8000` gönderin; aksi halde runtime `502` döndürür. Aynı upstream içinde mevcut bir adres yeniden oluşturulduğunda duplicate kayıt yerine mevcut target döndürülür. ## Target durumu Yeni target'lar şu değerlerle başlar: * `status: active` * `health_status: healthy` * sıfır başarı ve hata sayısı * ilk ölçüm öncesinde boş latency değeri Başlangıçtaki `healthy` değeri yönetimsel varsayılandır. Readiness doğrulaması için health monitor güncellemesini bekleyin ve gateway üzerinden gerçek bir istek gönderin. ## Health check'ler Birleşik Kangal deployment'ında health monitor yaklaşık 30 saniyede bir çalışır ve her target'ın base URL'sine beş saniye timeout ile `GET` gönderir. Herhangi bir `2xx` veya `3xx` response sağlıklı kabul edilir. Yinelenen hatalarda sonraki probe'dan önce backoff uygulanır. ### Health-check gereksinimleri * Probe, target base URL'sine gönderilen kimlik doğrulamasız bir `GET` isteğidir. Bu URL'nin hızlı, yan etkisiz bir `2xx` veya `3xx` response döndürmesini sağlayın. * Base URL kimlik doğrulaması gerektiriyorsa uygulamanın önünde health-check ile uyumlu bir endpoint kullanın. * Geçersiz target adresleri `no_url` probe hatasıyla raporlanır. * Bağımsız data plane'in pasif gözlemleri ilgili serving process'te tutulur. Değerlendirme yaparken data plane status ve loglarını control-plane kayıtlarıyla birlikte kullanın. ## Hata sırasında target seçimi Varsayılan seçim, kullanılabilir target'lar arasında round-robin'dir. Sağlıklı target'lara öncelik verilir. Yeterli sağlıklı aday bulunmadığında runtime aday kümesini `degraded` ve `unhealthy` target'ları içerecek şekilde genişletebilir. Tüm aktif target'lar sağlıksızsa aktif bir target trafik almaya devam edebilir. Kesin izolasyon gerektiğinde hatalı target'ı havuzdan kaldırın veya yönetimsel olarak devre dışı bırakın. Health durumu tek başına her hata senaryosunda kesin trafik engeli olarak kullanılmamalıdır. Havuzda kullanılabilir target yoksa ve upstream geçerli bir `url` içeriyorsa runtime bu URL'yi fallback olarak kullanabilir. Seçilen target'ın adresi geçersizse istek `502` ile sonuçlanır; fallback URL bu target adresini değiştirmez. ## Service'i upstream'e bağlama `upstream_id` veya `upstream_name` kullanarak bir service oluşturun ya da güncelleyin: ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/services" \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tenant_id": "'"$KANGAL_TENANT_ID"'", "name": "checkout-service", "upstream_id": "'"$KANGAL_UPSTREAM_ID"'", "connect_timeout_ms": 5000, "read_timeout_ms": 30000, "write_timeout_ms": 30000 }' ``` Trafiğin yönlendirilmesi için service upstream'e, route da ilgili service veya upstream'e başvurmalıdır. ## Güncelleme ve target değiştirme Bir upstream `name`, `url` ve `labels` alanlarıyla güncellenebilir. Target adresini değiştirmek için: 1. Tam URL içeren yeni target'ı ekleyin. 2. Başarılı probe'u bekleyin ve test trafiği gönderin. 3. Eski target'ı ID ile silin. Bu sıra değişiklik sırasında havuz kapasitesini korur. Trafiği hemen kesmeniz gerekiyorsa önce eski target'ı kaldırın ve geçici kapasite azalmasını hesaba katın. ## Güvenli silme sırası Bir upstream'i silmeden önce bağımlılıkları şu sırayla kaldırın: 1. Upstream ID'sine veya adına başvuran service'leri bulun. 2. Bu service'leri ve route'larını başka bir upstream'e yönlendirin veya silin. 3. Upstream'e bağlı target'ları silin. 4. Upstream'i silin. Çözümlenemeyen service veya route bağımlılığı request sırasında `502 Bad Gateway` sonucuna yol açabilir. Target silindiğinde dış envanter kayıtlarını da kullandığınız envanter sürecine göre güncelleyin. ## Sorun giderme ### Target oluşturuldu ancak trafik `502` döndürüyor Kayıtlı target'ın `http://` veya `https://` ile başladığını, data-plane ağından çözümlenebildiğini ve route tarafından yeniden yazılan path'i kabul ettiğini doğrulayın. Service'in doğru upstream ID'sine veya adına başvurduğunu da kontrol edin. ### Yeni target erişilebilir olmadan `healthy` görünüyor Bu değer başlangıçtaki yönetimsel durumdur. En az bir health interval bekleyin, son probe metadata'sını inceleyin ve gateway üzerinden istek gönderin. ### Sağlıksız target istek almaya devam ediyor Sağlıklı adaylar tükendiğinde runtime aktif ve sağlıksız target'ları seçebilir. Kesin izolasyon için target'ı kaldırın veya yönetimsel olarak devre dışı bırakın. ### Health check başarısız, uygulama istekleri başarılı Monitor base URL'ye kimlik doğrulamasız `GET` gönderir. Base URL'yi bu isteği başarıyla karşılayacak şekilde düzenleyin veya uyumlu bir ön endpoint kullanın. ### Upstream silindikten sonra route çalışmıyor Upstream/service bağımlılığını yeniden oluşturun veya doğru kaynağa yönlendirin. Ardından yeni configuration bundle'ın serving data plane tarafından uygulandığını doğrulayın. --- # 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/upstreams-targets.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.