Kubernetes Gateway API ile Ingress’ten Modern Trafik Yönetimine Geçiş (Adım Adım Rehber)

Kubernetes üzerinde uygulama trafiğini yönetirken yıllardır Ingress nesnelerine güvendik. Ancak mikro servisler büyüdükçe, L7/L4 kombinasyonları, çok kiracılı mimariler ve gelişmiş yönlendirme ihtiyaçları için Ingress’in sınırları daha görünür hale geldi. Gateway API, bu boşluğu kapatmak için tasarlanmış, açık standartlara dayanan ve birden fazla sağlayıcı tarafından desteklenen modern bir trafik yönetim modelidir. Bu yazıda, Gateway API’nin ne sunduğunu, nasıl kurulacağını ve Ingress’ten geçişi adım adım anlatıyorum.

Gateway API nedir? Kısa ve net

Gateway API; GatewayClass, Gateway, HTTPRoute, GRPCRoute, TCPRoute gibi özelleştirilmiş kaynak türleri (CRD) sunar. İki ana fark öne çıkar: Birincisi, rollerin ayrımı. Platform ekibi Gateway’leri tanımlayıp kimin kullanacağını belirlerken, uygulama ekipleri yalnızca Route nesneleriyle trafik kurallarını yönetir. İkincisi, zengin eşleşme ve filtre seti sayesinde başlık, yol, hostname, mTLS, oran sınırlama ve header manipülasyonu gibi gelişmiş senaryolar standartlaştırılmıştır.

Önkoşullar ve kurulum

Başlamadan önce Kubernetes 1.25+ sürümünde bir kümeniz ve bir Gateway API uygulaması (NGINX, Istio, Traefik, Cilium vb.) kurulu olmalı. CRD’leri yüklemek için yönetilen küme kullanıyorsanız çoğu sağlayıcıda ön tanımlı gelebilir; değilse CRD’leri kendiniz uygulayabilirsiniz. Örnek: kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0". Ardından seçtiğiniz kontrolcünün Gateway API desteğini etkinleştirin; örneğin NGINX için GatewayClass genelde nginx veya nginx-experimental olarak gelir, Istio’da istio adıyla görünür.

Adım 1: GatewayClass ve Gateway oluşturma

GatewayClass, kümede hangi kontrolcünün dinleyici oluşturacağını belirler. Platform ekibi tek bir GatewayClass atayıp çoklu Gateway’lere hizmet verebilir. Basitçe söylemek gerekirse, Ingress’teki ingressClassName’in yerini daha güçlü bir kavram alıyor. Gateway ise yük dengeleyicinizin gerçekte nasıl dışa açılacağını tanımlar: portlar, TLS, SNI, HTTP/2, hatta (destek varsa) HTTP/3. Örnek bir yaklaşım: gatewayclass.name: nginx olan bir prod-gateway’i 80 ve 443 portlarında dinleyecek şekilde oluşturun ve AllowedRoutes politikasıyla yalnızca belirli isim alanlarından route kabul edin.

Adım 2: HTTPRoute ile trafiği yönlendirme

Uygulama ekipleri için asıl iş HTTPRoute’ta başlar. Burada hostnames, path eşleşmeleri ve header filtreleriyle kuralları tanımlarsınız. Örneğin api.ornek.com alan adındaki /v1/* yollarını demo-svc:80 servisine yönlendirin, X-Canary: true başlığı geldiğinde trafiğin %10’unu canary sürümüne gönderin. Ek olarak RequestHeaderModifier filtresi ile giden isteklere bir X-Trace-Id eklemek mümkün. Bu tür politikalar, Ingress anotasyonlarına bağımlı olmanıza gerek kalmadan, standart ve taşınabilir bir şekilde tanımlanır.

Adım 3: TLS sonlandırma ve güvenlik

TLS sonlandırmayı Gateway nesnesi üzerinde yönetmek daha tutarlı bir model sunar. certificateRefs ile bir Secret referansı vererek SNI üzerinden birden fazla alan adı için sertifika tanımlayabilirsiniz. mTLS gerekiyorsa, destekleyen uygulamalarda TLSMode: Terminate yerine TLSMode: Passthrough veya karşılıklı TLS doğrulaması yapılandırılabilir. Güvenlik tarafında iki güçlü özellik daha var: AllowedRoutes ile hangi isim alanlarının Gateway’e bağlanabileceği, ReferencePolicy ile hangi kaynakların birbirini görebileceği belirlenir. Böylece çok kiracılı ortamlarda izolasyon korunur.

Ingress’ten Gateway API’ye geçiş

Geçiş için basit bir eşleştirme stratejisi işe yarar: Ingress’teki ingressClassName → GatewayClass, rules.host ve paths → HTTPRoute.rules, tls → Gateway.listeners.tls. İlk aşamada mevcut Ingress’i koruyup paralelde bir Gateway + Route tanımı oluşturun. ExternalDNS kullanıyorsanız, yeni yük dengeleyicinin dış IP’si oluşunca DNS’i aşamalı olarak Gateway’e yönlendirin. Canlı geçişte hata oranını düşürmek için HTTPRoute üzerinde ağırlıklandırılmış backend’lerle kademeli trafik geçişi (canary) uygulayın. Son adımda Ingress’i kapatıp gereksiz anotasyonları temizleyebilirsiniz.

Gözlem ve hata giderme

Gateway API, durum ve koşul (conditions) alanlarını zenginleştirerek sorunları teşhis etmeyi kolaylaştırır. kubectl get gatewayclass ile sınıfın Accepted olup olmadığını, kubectl describe gateway ile Programmed ve atanan Addresses değerini kontrol edin. kubectl describe httproute çıktısında Accepted ve ResolvedRefs koşullarını görün; bir kural kabul edilmediyse nedenini burada bulursunuz (ör. izin verilmeyen hostname veya eşleşen Gateway yok). Olaylar (events) sıklıkla eksik Secret, yanlış referans veya port çakışmalarını ele verir.

Performans, uyumluluk ve farklar

Gateway API standarttır fakat her uygulamanın destek seviyesi farklı olabilir. Üretime çıkmadan önce seçtiğiniz kontrolcünün Conformance matrisini inceleyin. HTTP/2 ve (destek varsa) HTTP/3 kullanımında bağlantı ömrü ve yeniden deneme politikalarını gözden geçirin. Varsayılan timeout ve retry davranışları uygulamadan uygulamaya değişebilir; uzun süreli akışlar (streaming) için uygun ayarları HTTPRoute üzerindeki timeouts ve filtrelerle netleştirin. Ayrıca, L4 trafiği için TCPRoute/UDPRoute kullanarak veritabanı veya özel protokoller için aynı yönetişim modelinden faydalanabilirsiniz.

Yaygın hatalar ve pratik ipuçları

En yaygın hatalardan biri, Route’ların Gateway’e bağlanmasına izin vermeyi unutmak. Gateway üzerinde AllowedRoutes.namespaces ayarını netleştirin. İkinci hata, eski Ingress anotasyonlarının aynısını Gateway API’de aramak; çoğu senaryo artık filters ile standartlaştırıldı. Eğer dışa açık bir LoadBalancer bekliyorsanız ancak adres gelmiyorsa, kontrolcünün bulut sağlayıcısı entegrasyonunu ve servis tiplerini doğrulayın. Son olarak, üretim öncesi bir staging Gateway’inde tüm host ve TLS kombinasyonlarını duman testi (smoke test) ile deneyin; SNI yanlışlıkları genelde burada yakalanır.

Sonuç

Gateway API, Kubernetes’te trafik yönetimini bir üst seviyeye taşıyor: net rol ayrımı, güçlü politika dili ve çok sağlayıcılı ekosistem. Ingress’ten görece zahmetsiz bir geçişle başlamak ve ilk kazanımları (daha iyi görünürlük, canary, header bazlı yönlendirme) kısa sürede görmek mümkün. Kümenizde standart, taşınabilir ve güvenli bir ağ katmanı istiyorsanız, Gateway API’yi denemenin tam zamanı.

Kubernetes Gateway API Rehberi: Ingress’ten Geçiş, Kurulum ve En İyi Uygulamalar

Kubernetes dünyasında trafik yönlendirme denince yıllardır akla ilk gelen nesne Ingress oldu. Ancak karmaşık topolojiler, çoklu tenant ihtiyaçları ve servis mesh ile entegrasyonlar arttıkça, Ingress’in sınırları da görünür hâle geldi. Tam bu noktada CNCF destekli Gateway API, daha esnek modelleme, tutarlı CRD’ler ve güçlü uzatılabilirlik ile yeni standart olarak öne çıkıyor. Bu yazıda Gateway API nedir, nasıl kurulur ve Ingress’ten geçiş nasıl yapılır ayrıntılı ama sade bir dille anlatıyorum.

Gateway API nedir? Ingress’ten farkları

Gateway API, Kubernetes üzerinde L4/L7 trafiğini tanımlamak için Ingress’e göre daha zengin bir şema sunar. Temel bileşenleri GatewayClass, Gateway ve Route (ör. HTTPRoute, GRPCRoute) nesneleridir. Bu ayrım sayesinde, platform ekibi altyapıyı (GatewayClass/Gateway) yönetirken, uygulama ekipleri yalnızca route’ları tanımlayabilir. Bu da yetki ayrımı, çoklu kiracı desteği ve politika yönetimi açısından büyük avantaj sağlar.

Ingress tek bir kaynak türüyle pek çok ihtiyacı aynı dosyada toplamaya çalışırken, Gateway API yönlendirme mantığını daha modüler ve tutarlı CRD’lere böler. Örneğin birden fazla host, path tabanlı kurallar, TLS sonlandırma, rate limit veya header manipülasyonu gibi gelişmiş özellikler daha net ifade edilebilir. Üstelik aynı manifest’ler farklı sağlayıcılarla daha taşınabilir çalışır.

Hangi uygulamalar destekliyor?

Gateway API bir spesifikasyon; uygulaması ise farklı projeler tarafından sağlanıyor. En popülerleri: Envoy Gateway, NGINX Gateway Fabric ve Istio (mesh senaryolarında doğrudan destekler). Üretim ortamında biriyle başlayıp, mimari ihtiyaçlar değiştiğinde diğerine geçebilmek büyük esneklik sunar. Bu da kilitlenme riskini azaltır.

Kurulum: Hızlı başlangıç

Öncelikle Kubernetes sürümünüzün güncel olduğundan emin olun (en az 1.26+ önerilir). Ardından seçtiğiniz uygulamanın CRD’lerini ve kontrol düzlemini kurun. Örnek olarak Envoy Gateway ile başlamak oldukça rahattır. Resmî manifest’ler ile CRD kurulumu yapılır; akabinde bir GatewayClass ve bir Gateway tanımlanır. Basit bir sınıf tanımı şu şekilde olabilir: apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: eg-class spec: controllerName: gateway.envoyproxy.io/gatewayclass-controller Sonrasında bu sınıfa bağlı bir Gateway oluşturup trafiğe bir giriş noktası tanımlarsınız: apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: eg-gw spec: gatewayClassName: eg-class listeners: - name: http port: 80 protocol: HTTP

Artık uygulama ekipleri kendi namespace’lerinde HTTPRoute tanımlayabilir. Örnek bir route: apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: web-route spec: parentRefs: - name: eg-gw rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: web-svc port: 8080 Bu tanım, / ile başlayan tüm istekleri web-svc:8080 servisine iletir.

Ingress’ten Gateway API’ye geçiş

Mevcutta Ingress kullanan ekipler için geçiş adımları özetle şu şekilde ilerler: Önce mevcut Ingress kurallarınızı listeleyin ve host/path/TLS mantığını çıkarın. Ardından bir GatewayClass ve Gateway oluşturup, her Ingress kuralını karşılayacak HTTPRoute nesnelerine dönüştürün. Örneğin Ingress’te host: app.example.com ve /api path’i vardıysa, HTTPRoute içinde matches.path ile benzer kuralı tanımlar ve parentRefs ile hedef Gateway’e bağlarsınız.

TLS için Ingress anotasyonları yerine Gateway/Route içinde doğrudan TLS blokları kullanabilirsiniz. Örneğin: listeners: - name: https port: 443 protocol: HTTPS tls: mode: Terminate certificateRefs: - name: app-cert namespace: certs Bu, sonlandırmayı Gateway üzerinde yapar. Eğer uçtan uca TLS istiyorsanız, backend’te de TLS terminasyonu uygulayıp uygun SNI/ALPN ayarlarını yapan bir yapılandırma seçmelisiniz.

Gelişmiş senaryolar: Canary ve mavi-yeşil

Gateway API’de trafik bölme senaryoları sadeleşir. Bir HTTPRoute altında birden çok backendRef tanımlayıp weight ile isteklerin yüzdesini kontrol edebilirsiniz. Örneğin yeni sürüme yüzde 10 trafik göndererek canary testleri yapmak mümkündür. Ayrıca header tabanlı yönlendirme ile yalnızca belirli kullanıcı gruplarını yeni sürüme taşıyarak riskinizi daha da düşürebilirsiniz.

Politikalar, güvenlik ve çoklu tenant

Policy ekosistemi Gateway API’nin güçlü taraflarından. Kuralları namespace sınırlarına göre kısıtlamak, yalnızca belirli ekiplerin belirli listener’lara bağlanmasını sağlamak veya mTLS zorunluluğu getirmek mümkün. Çoğu uygulama, oran sınırlama (rate limit), WAF veya authZ entegrasyonları için ek CRD’ler sunar. Böylece güvenlik ekibi politikaları merkezi tanımlar, uygulama ekipleri ise yalnızca yönlendirme kurallarını yazar.

Sorun giderme: Neleri kontrol etmeli?

Önce CRD ve controller pod’larının sağlığını kontrol edin. Gateway ve HTTPRoute nesnelerinin status alanlarını mutlaka inceleyin; hangi parent’a bağlandığı ve programlama durumunu açıkça gösterir. DNS ve LoadBalancer IP/hostname atamalarını doğrulayın. Trafik gelmiyorsa listener portu, güvenlik grupları ve network policy ayarlarına bakın. Ingress’ten geçişte unutulan en yaygın nokta, TLS terminasyonunun yeri ve sertifika referanslarının namespace’ler arası erişimidir; certificateRefs ve RBAC izinlerini iki kez kontrol edin.

Ne zaman Gateway API’ye geçmeliyim?

Eğer birden çok takım aynı kümede çalışıyor, birden fazla ingress controller’ı yönetmekten yoruluyor veya servis mesh ile uyumlu bir giriş katmanı istiyorsanız, Gateway API güçlü bir aday. Yeni projelerde doğrudan Gateway API ile başlamak, taşınabilirlik ve geleceğe dönük uyumluluk açısından avantaj sağlar. Mevcut Ingress’leriniz basit ve kararlıysa acele etmeye gerek yok; kademeli bir geçiş planı hazırlamak daha sağlıklı olur.

Son söz: Gateway API yalnızca yeni bir CRD seti değil, Kubernetes’te trafik yönetimine bakış açımızı güncelleyen bir standart. Doğru uygulama ve iyi tanımlanmış sorumluluklar ile hem platform ekiplerinin yönetim yükünü azaltıyor hem de uygulama ekiplerine daha net, öngörülebilir bir deneyim sunuyor.

Kubernetes Gateway API ile Ingress’ten Geçiş: Adım Adım Rehber ve En İyi Uygulamalar

Özet: Kubernetes’te trafiği yönetmek için yıllardır varsayılan seçenek olan Ingress, karmaşık senaryolarda yetersiz kalabiliyor. Gateway API, modern trafik yönetimi için daha esnek bir model sunuyor: roller ayrımı, zengin yönlendirme kuralları, taşınabilirlik ve genişletilebilirlik. Bu yazıda, Ingress’ten Gateway API’ye geçişi adım adım anlatıyor, örnek tanımlar ve en iyi uygulamalarla destekliyoruz.

Gateway API Nedir ve Neden Geçmeliyim?

Gateway API, Kubernetes’in ağ katmanında kaynak türlerini genişleterek standartlaştırılmış, sağlayıcıdan bağımsız bir trafik yönetim modeli sunar. Başlıca avantajları:

- Rollerin ayrımı: GatewayClass, Gateway ve HTTPRoute/GRPCRoute/TCPRoute nesneleriyle altyapı ve uygulama ekipleri sorumlulukları net şekilde paylaşır.
- Zengin ifade gücü: Header tabanlı yönlendirme, ağırlıklı trafik bölümü, mTLS, yeniden deneme/politikalar için geniş kapsam.
- Taşınabilirlik ve uyumluluk: Birçok sağlayıcı (NGINX, Kong, Istio, Cilium vb.) aynı API’yi destekler.
- Geleceğe uyum: Topluluk tarafından aktif geliştirilen ve conformance testleriyle doğrulanan bir standart.

Ön Koşullar ve Kurulum

Geçişe başlamadan önce Kubernetes 1.26+ ve seçtiğiniz bir Gateway sağlayıcısı (ör. NGINX, Kong, Istio) kurulu olmalı. CRD’leri etkinleştirmek için aşağıdaki komutu uygulayabilirsiniz (sürüm numarasını güncel olanla değiştirin):

kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0"

Sağlayıcınıza bağlı olarak bir GatewayClass gelir veya siz tanımlarsınız. Sağlayıcı dökümantasyonunda “GatewayClass name” önemlidir; az sonra Gateway nesnesinde bu ismi kullanacağız.

Ingress’ten Gateway API’ye Geçiş: Adım Adım

1) Mevcut Ingress haritasını çıkarın: Kümelerde hangi alan adları, yollar (path), TLS sertifikaları, backend servisleri ve ağırlıklandırmalar kullanılıyor? Bunları listeleyin. Bu, HTTPRoute’lara dönüşümde yol gösterici olacaktır.

2) GatewayClass ve Gateway tanımlayın: Altyapı ekibi bir GatewayClass sağlar. Ardından trafiğin dinleneceği Gateway nesnesi oluşturulur. Örnek bir Gateway mantığı şöyle olabilir:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: edge-gw
spec:
  gatewayClassName: nginx
  listeners:
  - name: web
    port: 80
    protocol: HTTP
  - name: web-tls
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: site-cert

3) HTTPRoute ile yönlendirme oluşturun: Ingress’teki host ve path kurallarını HTTPRoute’a taşıyın. Örnek bir kurgu:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-route
spec:
  parentRefs:
  - name: edge-gw
  hostnames:
  - shop.ornek.com
  rules:
  - matches:
    - path:
      type: PathPrefix
      value: /api
    backendRefs:
    - name: shop-api
      port: 8080

4) Trafik geçişini risksiz yönetin: Canlı geçişte aynı hostname altında iki servis arasında ağırlıklandırma kullanabilirsiniz. Örnek: eski servis %90, yeni servis %10.

- Ağırlıklandırma: backendRefs altında weight alanını kullanın (ör. weight: 90 ve weight: 10).
- Header tabanlı yönlendirme: Sadece belirli kullanıcı grubuna test için X-Canary: true başlığıyla yeni sürümü gösterin.
- Trafik yansıtma (mirror/tee) özelliği sağlayıcıya göre değişir; destekleniyorsa üretim verisini gölgeleme için kullanın.

5) TLS ve güvenlik: Sertifikaları Secret üzerinden terminate edin. Gateway seviyesinde mTLS veya HTTPRoute bazlı politika tanımlarıyla hassas uç noktaları koruyun. Bazı sağlayıcılar ReferenceGrant ile namespace’ler arası güvenli referanslamayı şart koşar.

6) Gözlemlenebilirlik ve hata ayıklama: Gateway ve Route’ların status alanlarını inceleyin. Olay kayıtları (kubectl describe), metrikler (Prometheus), loglar ve sağlayıcı panellerini birlikte kullanın. Uyuşmayan host veya listener isimleri en sık karşılaşılan kaynaklardır.

Ingress ve Gateway API Arasındaki Farkların Özeti

- Ingress tek bir kaynakla çok şeyi yapmaya çalışır; gelişmiş senaryolarda anotasyon bağımlılığı artar. Gateway API ise modülerdir: Gateway (giriş noktası), Route (uygulama yönlendirmesi) ve Policy (davranış) ayrıdır.
- Birden fazla ekip aynı Gateway’i paylaşabilir; uygulama ekipleri sadece kendi HTTPRoute’larını yönetir.
- Trafik türleri (HTTP, TCP, gRPC) için ayrı Route kaynaklarıyla net ayrımlar sağlanır.

En İyi Uygulamalar

- Adım adım geçiş: Tüm Ingress’leri tek seferde taşımak yerine domain veya mikroservis bazlı fazlara bölün.
- İsimlendirme stratejisi: Gateway, listener ve host adlarını tutarlı belirleyin. Ortak bir etiketleme şeması kullanın (ör. environment, team, cost-center).
- Politikaları merkezileştirin: Zorunlu güvenlik ve hız sınırlama (rate limit) kurallarını gateway seviyesinde; uygulama bazlı esnemeleri route seviyesinde yönetin.
- Conformance kontrolü: Sağlayıcınızın Gateway API uyumluluk seviyesi ve desteklediği ek özellikleri önceden doğrulayın.
- Geri dönüş planı: Canary ve header tabanlı yönlendirmeyle geri alma senaryolarını pratik edin.

Yaygın Hatalar ve Çözümler

- 404/Hostname uyuşmazlığı: HTTPRoute içindeki hostnames listesi, gelen isteğin SNI/Host başlığıyla birebir eşleşmelidir.
- Listener uyuşmazlığı: Route’un parentRefs alanındaki isim, ilgili Gateway listener’ı ile aynı port/protokole uygun olmalı.
- Namespace erişimi: Route’un referans verdiği Service farklı namespace’teyse ReferenceGrant gerektirebilir.
- TLS Secret formatı: tls.crt ve tls.key anahtarları doğru yerleştirilmelidir; yanlış format sertifika yüklenmesini engeller.

Sonuç

Gateway API, Kubernetes’te trafik yönetimini modernleştiriyor. İnce ayarlı yönlendirme, ekipler arası sınırların netleşmesi ve sağlayıcı bağımsızlığı sayesinde büyük ve regüle ortamlarda dahi güvenle ölçeklenebiliyor. Mevcut Ingress’lerinizi envanterleyip küçük adımlarla HTTPRoute’lara taşıyarak, TLS ve politikaları sistematik şekilde uyguladığınızda kesintisiz bir geçiş mümkün. Uzun vadede sade operasyon, daha öngörülebilir davranış ve standart bir ağ katmanı kazanırsınız.