> 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/gateways-data-planes.md). # Gateway ve data plane Gateway, Kangal'ın tenant kapsamındaki yapılandırma sınırıdır. Veri düzlemi düğümü ise tek bir gateway'e kaydedilmiş runtime örneğidir. Gateway oluşturma, hedef barındırma ve plan metadata'sını tanımlar. Trafik hazırlığı için runtime düğümünü ve herkese açık listener'ı da doğrulayın. ## Deployment profili seçin Konsol, her profili bir plan code ile eşleştirir: | Deployment profili | Konsol plan code | Hedef işletim modeli | | --------------------- | ---------------------- | ----------------------------------------------------------------------------- | | `serverless` | `serverless_starter` | Paylaşılan veya yönetilen runtime. | | `dedicated_cloud` | `dedicated_enterprise` | Ayrılmış, yönetilen kapasite. | | `self_managed_hybrid` | `hybrid_scale` | Kangal kontrol düzlemine bağlı, müşteri tarafından işletilen veri düzlemleri. | | `kubernetes_ingress` | `kic_readonly` | Kubernetes odaklı yapılandırma görünümü. | Konsol bu eşleşmeyi senkronize tutar. API otomasyonu, listelenen `deployment_profile` değerlerinden birini onaylı `plan_code` ile birlikte göndermelidir. Profil, hedef barındırma metadata'sıdır. Runtime kapasitesinin, Kubernetes controller'ın ve veri düzlemi kaydının hazırlanması deployment iş akışı kapsamında yürütülür. ## Konsolda gateway oluşturun 1. **API Gateway** sayfasını açın ve **Yeni** seçeneğini belirleyin. 2. Deployment profilini seçin. 3. Adı ve isteğe bağlı açıklamayı girin. 4. Ownership, environment, arama veya otomasyon için label gerekiyorsa gelişmiş bölümü açın. 5. Gateway'i oluşturun ve ayrıntı sayfasını açın. 6. Gateway ID'sini kaydedin; üretilen proxy ve workspace metadata'sını inceleyin. 7. Trafiği açmadan önce **Veri düzlemi düğümleri** bölümünü kontrol edin. Konsolda gateway adı en az üç karakter olmalıdır. İlk karakter küçük harf veya rakam olmalı; sonraki karakterler `-`, `_` ve `.` de içerebilir. Açıklama, Konsolda en fazla 512 karakter olabilir. ## Gateway alanları | Alan | Anlamı | Notlar | | -------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `tenant_id` | Sahip tenant. | Oluşturma sırasında zorunludur ve yönetici kapsamıyla karşılaştırılır. Gateway update ile değiştirilemez. | | `name` | İnsanlar ve otomasyon için tanımlayıcı. | Sabit ve DNS uyumlu bir değer kullanın. Ad değişikliği saklanan proxy metadata'sını yeniden üretmez. | | `description` | Operatör bağlamı. | Bu alana secret koymayın. | | `deployment_profile` | Hedef barındırma modeli. | Yukarıdaki dört değerden biri. | | `plan_code` | Entitlement/billing ilişkisi. | Konsolda seçilen profille uyumlu tutun. | | `labels` | Serbest biçimli metadata. | Konsol değerleri string olarak kaydeder ve profil ile ilgili label'ları kendi görüntüleme mantığı için ayırır. | | `proxy_host`, `proxy_url` | Üretilen proxy kimliği. | DNS, edge routing ve TLS ile birlikte doğrulanır. Gateway update API'sinde salt okunurdur. | | `workspace_id`, `workspace_name` | Üretilen workspace metadata'sı. | Gateway update API'sinde salt okunurdur. | Gateway oluşturma işlemi `gateway.manage` entitlement'ını kullanır. JSON geçerli olsa bile plan veya entitlement doğrulaması oluşturma isteğini reddedebilir. ## Gateway'leri `kangalctl` ile yönetin ```bash kangalctl get gateways --tenant-id tenant-acme ``` JSON veya YAML payload'ından oluşturun: ```bash kangalctl create gateways -f gateway.yaml ``` Yalnızca desteklenen değiştirilebilir alanları güncelleyin: ```yaml description: Production orders traffic labels: environment: production owner: platform ``` ```bash kangalctl update gateways "$GATEWAY_ID" -f gateway-update.yaml ``` Gateway silmeden önce route, service, upstream, target, certificate ve diğer kapsamlı kaynakları silin ya da başka bir hedefe yönlendirin. Silme işlemi gateway kaydını ve entitlement kullanımını kaldırır; bağlı kaynaklar bağımlılık sırasıyla yönetilir. ## Veri düzlemi düğümü kaydedin Kayıt bir yönetici işlemidir. Sabit bir `node_id` kullanın. Aynı tenant, gateway ve node ID ile yeniden gönderim, ikinci bir düğüm oluşturmak yerine mevcut kaydı günceller. ```bash curl -sS -X POST \ "$KANGAL_API_URL/api/v1/admin/gateways/$GATEWAY_ID/data-planes" \ -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tenant_id": "tenant-acme", "node_id": "dp-eu-1", "name": "EU production 1", "hostname": "kangal-dp-01.internal", "version": "1.0.0", "labels": {"region": "eu-central", "environment": "production"}, "capabilities": ["http", "plugins"], "issue_token": true }' ``` Response, yalnızca token oluşturulduğunda `node_token` içerir. Token'ı hemen düğümün secret store'una kaydedin; sonraki list ve get response'larında görüntülenmez. Kangal, token'ın SHA-256 hash'ini saklar. Token rotation için aynı `node_id` değerini `issue_token: true` ile yeniden kaydedin ve düğüm bir sonraki kontrol düzlemi çağrısını yapmadan önce secret'ı değiştirin. Rotation tamamlandığında eski token ile kimlik doğrulaması sona erer. Deployment certificate pinning gerektiriyorsa şu alanları da gönderin: * `client_cert_sha256`: doğrulanmış client certificate'ın SHA-256 fingerprint'i; * `client_cert_subject`: bilgilendirme amaçlı certificate subject metadata'sı. Fingerprint saklanmadan önce normalize edilir. Kangal, fingerprint'e sabitlenmiş bir düğüm için node token'ına ek olarak güvenilir TLS terminator'ın eklediği eşleşen fingerprint'i zorunlu kılar. Certificate doğrulaması güvenilir bir TLS terminator'da yapılmalıdır. Terminator; istemciden gelen `X-Kangal-DP-Client-Cert-SHA256` header'ını veya yapılandırılmış eşdeğerini kaldırmalı, client certificate'ı doğrulamalı ve SHA-256 fingerprint'ini kendisi eklemelidir. Terminator'ı atlayan istekleri önlemek için uygulama endpoint'lerine doğrudan erişimi engelleyin. Kangal, güvenilir biçimde eklenen bu değeri node token'ıyla birlikte kayıtlı fingerprint ile karşılaştırır. ## Runtime'ı bağlayın Düğümü kontrol düzlemi URL'i, `tenant_id`, `gateway_id`, sabit `node_id` ve oluşturulan token ile yapılandırın. Deployment'ın desteklediği secret injection yöntemini kullanın; token'ı manifest'e veya image'a commit etmeyin. Bağımsız runtime şu endpoint'leri sunar: * process sağlığı ve mevcut mod için `GET /health`; * yapılandırma hazırlığı için `GET /ready`; * ayrıntılı son bilinen iyi durum ve bağlantı bilgisi için `GET /status`; * istek trafiği için `/proxy/{path}`, `/api/proxy/{path}` ve şeffaf `/{path}`. Yönetim trafiği Admin API üzerinden kontrol düzleminde kalır; bağımsız runtime MongoDB bağlantısı kullanmaz. Düğüm, kontrol düzleminde `X-Kangal-DP-Token` ile kimliğini doğrular. Deployment mTLS'i etkinleştirdiğinde doğrulanmış certificate fingerprint'ini yukarıda açıklandığı gibi güvenilir TLS terminator sağlar. ## Düğüm durumunu anlayın | Alan veya durum | Anlamı | Operatör eylemi | | -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `registered` | Düğüm kaydı oluşturuldu ve canlı heartbeat bekleniyor. | Runtime başlangıcını, kapsam ID'lerini, token'ı ve ağ erişimini kontrol edin. | | `online` | Son heartbeat normal çalışmayı raporladı. | Mevcut ve hedef sürümleri de karşılaştırın. | | `degraded` | Düğüm, hata veya bekleyen raporla birlikte son bilinen iyi paketi sunuyor. | `last_telemetry.mode`, bekleyen raporlar ve NACK ayrıntılarını inceleyin. | | `offline` | Kontrol düzlemi heartbeat'i eski olarak işaretledi. | Düğümün kapalı mı olduğunu yoksa yerel status endpoint'iyle çevrimdışı hizmet mi verdiğini belirleyin. | | `draining` | Düğüm normal trafik hizmetinden çıkması gerektiğini raporluyor. | Dış load balancer'ın da düğümü trafiğin dışına aldığını doğrulayın. | | `current_config_version` | Düğüm tarafından raporlanan etkin paket sürümü. | Tamamlandıktan sonra hedeflenen rollout sürümüyle eşleşmelidir. | | `desired_config_version` | Kontrol düzleminin düğümde çalıştırmak istediği paket sürümü. | Farklılık; bekleyen teslim, erteleme veya hata durumunu gösterir. | | `config_sync_status` | `pending`, `success`, `failed` veya `partial`. | Gerekli production düğümlerinde `success` dışındaki durumları inceleyin. | | `last_config_ack_status` | En son `ACK` veya `NACK`. | NACK, paketin etkinleştirilmediğini gösterir. | | `last_known_good_config_version` | Son onaylanmış rollback adayı. | Otomatik rollback'e güvenmeden önce mevcut olduğunu doğrulayın. | | `last_seen_at` | Kimliği doğrulanmış son düğüm etkinliği. | Heartbeat yaşıyla birlikte değerlendirin. | Düğümün kendi runtime modları daha ayrıntılıdır: * `online`: kontrol düzlemine erişiliyor ve bekleyen yerel hata yok; * `degraded-lkg`: etkinleştirme veya raporlama sorunu bulunan geçerli son bilinen iyi yapılandırma; * `offline-lkg`: kontrol düzlemine erişilemezken imzalı cache kullanılıyor; * `stale-lkg`: cache'teki paket yapılandırılmış maksimum yaşı aşmış; * `not-ready`: geçerli yapılandırma yok; proxy istekleri `503` döner. ## Yapılandırmayı rollout ile dağıtın **Veri düzlemi düğümleri** sayfası; etkin rollout'u, node ACK/NACK durumunu, mevcut ve hedef sürümleri, dalgayı, son bilinen iyi sürümü ve son görülme zamanını gösterir. Bir production değişikliği için: 1. Hedeflenen her düğümün kayıtlı ve yakın zamanda görülmüş olduğunu doğrulayın. 2. Yüksek riskli değişiklikte **canary**, rutin değişiklikte **staged** başlatın. 3. Canary veya batch boyutunu ayarlayın; katılımı özellikle istenmediği sürece offline düğümleri hariç tutun. 4. Otomatik rollback eşiklerini yapılandırın. 5. Etkin dalganın tamamlanmasını bekleyin. Düğümler çalışırken ilerletmeyin. 6. İlerletmeden önce tüm NACK durumlarını çözün. 7. Rollout tamamlanana kadar sonraki dalgayı ilerletin. 8. Gerekli tüm düğümlerde mevcut ve hedef sürümlerin eşleştiğini doğrulayın. Konsol, canary dağıtımını bir düğümle; staged dalgaları beş düğümlük batch ile başlatır. Her iki varsayılan ayar da etkin dalgada bir başarısız düğüm veya %50 hata oranından sonra otomatik rollback uygular. Bu değerler fleet boyutunuza ve risk düzeyinize uymuyorsa API payload'ını ayarlayın. API stratejileri `immediate`, `staged` ve `canary` değerleridir. `batch_size` ve `canary_size`, 1 ile 100 arasındaki değerleri kabul eder. Offline düğümler varsayılan olarak hariç tutulur. ```bash curl -sS -X POST \ "$KANGAL_API_URL/api/v1/admin/gateways/$GATEWAY_ID/data-planes/config-rollout?tenant_id=$KANGAL_TENANT_ID" \ -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "strategy": "canary", "canary_size": 1, "batch_size": 5, "reason": "orders-route-change", "include_offline": false, "policy": { "automatic_rollback": true, "failure_count_threshold": 1, "failure_rate_threshold_percent": 50 } }' ``` Durumu incelemek, duraklatmak, sürdürmek, ilerletmek veya rollback yapmak için ilgili endpoint'leri kullanın: ``` GET /api/v1/admin/gateways/{gateway_id}/data-planes/config-rollout/status POST /api/v1/admin/gateways/{gateway_id}/data-planes/config-rollout/pause POST /api/v1/admin/gateways/{gateway_id}/data-planes/config-rollout/resume POST /api/v1/admin/gateways/{gateway_id}/data-planes/config-rollout/promote POST /api/v1/admin/gateways/{gateway_id}/data-planes/config-rollout/rollback ``` Her istek tenant query parameter'ını ve yetkili yönetici kimliğini gerektirir. Mevcut rollout durumuna uymayan geçişler `409` döner. ## Operasyon kontrolleri * Kayıt işlemi `(tenant_id, gateway_id, node_id)` bileşimine göre upsert yapar. Bir node ID'nin yeniden kullanılması token rotation'a ve görünen durumun `registered` olarak güncellenmesine neden olabilir. * Heartbeat ile ACK farklı sinyallerdir. Düğüm `online` raporlarken hedef paket hâlâ bekliyor olabilir. * Kontrol düzlemi eski bir kaydı offline olarak işaretlediğinde düğümü dış load balancer'ın kendi kontrol sistemi üzerinden drain edin veya kaldırın. * Rollback, yakalanmış ve kullanılabilir bir snapshot gerektirir. Konsol, otomatik rollback sonucunu rollout durumunda gösterir. * Çevrimdışı hizmet için geçerli imzalı cache ve anti-rollback durumu gerekir; process sağlığına ek olarak `/ready` endpoint'ini ve runtime modunu doğrulayın. * Yapılandırma senkronizasyonu gateway runtime kaynaklarını kapsar. External DNS, ingress, cloud load balancer ve herkese açık certificate etkinleştirmesini deployment iş akışınızda uygulayın. ## Sorun giderme ### Düğüm `registered` durumunda kalıyor Tenant, gateway ve node ID değerlerinin tam eşleştiğini; kontrol düzlemi temel URL'ini, token rotation'ı, TLS güvenini ve düğümün heartbeat ile config endpoint'lerine erişebildiğini doğrulayın. ### Node endpoint'lerinden `401` Token'ın güncel ve doğru düğümle ilişkili olduğunu doğrulayın. Certificate pinning yapılandırılmışsa güvenilir TLS terminator'ın client certificate'ı doğruladıktan sonra beklenen SHA-256 fingerprint'ini eklediğini de kontrol edin. ### Mevcut ve hedef sürümler farklı Rollout ertelemesini, node dalgasını, `config_available` değerini, son pull zamanını ve NACK ayrıntılarını kontrol edin. Staged rollout'ta `waiting`, `paused` veya `blocked` durumundaki düğüm hedef generation'ı kendi dalgasında alır. ### Düğüm `NACK` raporluyor `last_config_nack_message` ve `last_config_nack_errors` alanlarını inceleyin. İlerletmeden önce kapsam, checksum, imza, hatalı collection veya anti-rollback hatalarını düzeltin. Reddedilen paket etkin snapshot'ın yerini almaz. ### Rollout ilerletilemiyor Etkin dalganın durumunu yenileyin. İlerletme için dalga çalışır durumda olmalı, devam eden veya başarısız düğüm içermemeli ve bekleyen düğümler bulunmalıdır. ### Rollback kullanılamıyor Gerekli düğümlerde onaylanmış son bilinen iyi generation ve sabitlenmiş snapshot'ın kullanılabilirliğini kontrol edin. Mevcut rollout'u kararlı duruma getirin ve sonraki değişiklikten önce bilinen iyi bir durum yakalayı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/gateways-data-planes.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.