Kubernetes Gateway API Rehberi: Ingress NGINX'ten Göç ve Zabbix Örneği

NGINX Ingress'e Ne Oldu?

2026 yılında Kubernetes dünyasında önemli bir değişiklik yaşanacak: NGINX Ingress Controller artık yeni özellik güncellemeleri almayacak. Panik yapmaya gerek yok - mevcut kurulumlarınız çalışmaya devam edecek. Ancak yeni özellikler için artık başka bir çözüme bakmamız gerekiyor.

İşte burada Kubernetes Gateway API devreye giriyor.

Gateway API Nedir ve Neden Önemli?

Gateway API, Kubernetes'in resmi olarak desteklediği yeni nesil routing çözümü. Ingress'ten temel farkı şu: modüler yapısı.

Ingress'te her şey tek bir YAML dosyasında toplanıyordu. Gateway API ise işleri üç parçaya ayırıyor:

1. GatewayClass

Cluster genelinde hangi gateway controller'ın kullanılacağını belirler. Bunu bir kere tanımlıyorsunuz ve tüm cluster için geçerli oluyor.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cluster-gateway-class
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller

GatewayClass seçenekleri:

• NGINX Gateway Fabric (NGINX Inc.)
• Istio Gateway (Google/IBM)
• Cilium Gateway (eBPF tabanlı)
• Kong Gateway (Enterprise)
• Envoy Gateway (CNCF)

Her birinin kendine göre avantajları var. NGINX Gateway Fabric hafif ve basit, Istio daha gelişmiş service mesh özellikleri sunuyor, Cilium performans odaklı.

2. Gateway

Asıl trafiği dinleyen ve yönlendiren bileşen. HTTP, HTTPS, TCP gibi farklı protokolleri destekliyor.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cluster-gateway
  namespace: nginx-gateway
spec:
  gatewayClassName: cluster-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All  # TÜM namespace'lerden route kabul et

3. HTTPRoute

Her servis için ayrı tanımlanıyor. Hangi hostname'den gelen trafiğin hangi servise gideceğini belirliyor.

Gateway API'nin Sağladığı Kolaylıklar

1. Rol Ayrımı:

• Cluster admin: GatewayClass ve Gateway'i yönetir
• Geliştirici: Sadece kendi HTTPRoute'unu yönetir

2. Namespace İzolasyonu:
Gateway başka namespace'de olsa bile HTTPRoute kendi namespace'inden bağlanabiliyor.

3. Daha Detaylı Routing:

• Header-based routing
• Query parameter routing
• Method-based routing (GET, POST, etc.)
• Weight-based traffic splitting

4. Backend Seçenekleri:
Ingress'te sadece Service'e yönlendirme vardı. Gateway API ile:

• Multiple backends
• Traffic weighting (A/B testing)
• Request/response header değiştirme

Gerçek Dünya Örneği: Zabbix Deployment

Şimdi pratiğe geçelim. Zabbix monitoring sistemini Gateway API ile nasıl expose ediyoruz?

Adım 1: GatewayClass Oluşturma

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cluster-gateway-class
  annotations:
    description: "Cluster-wide gateway class for all services"
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller
  description: "NGINX Gateway Fabric for cluster infrastructure"

Bu dosyayı cluster'da bir kere deploy ediyoruz. Tüm servisler bunu kullanacak.

Adım 2: Gateway Oluşturma

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cluster-gateway
  namespace: nginx-gateway
  annotations:
    description: "Cluster-wide gateway for all services"
spec:
  gatewayClassName: cluster-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: cluster-tls-secret

Önemli detay: allowedRoutes.namespaces.from: All

Bu satır olmadan Gateway sadece kendi namespace'indeki route'ları kabul eder. All yaparak tüm namespace'lerdeki servislerin bu gateway'i kullanmasına izin veriyoruz.

Adım 3: Zabbix için HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: zabbix-route
  namespace: zabbix
spec:
  parentRefs:
    - name: cluster-gateway
      namespace: nginx-gateway
      sectionName: http
    - name: cluster-gateway
      namespace: nginx-gateway
      sectionName: https
  hostnames:
    - "zabbix"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: zabbix-zabbix-web
          port: 80

Dikkat edilmesi gerekenler:

1. Cross-namespace referans: HTTPRoute zabbix namespace'inde ama nginx-gateway namespace'indeki gateway'e bağlanıyor.

2. parentRefs: Hem HTTP hem HTTPS listener'a bağlandık. Böylece her iki protokol de çalışıyor.

3. sectionName: Gateway'deki hangi listener'a bağlanacağımızı belirtiyoruz.

4. hostnames: Browser'da http://zabbix yazınca bu route devreye girecek.

Deployment

# 1. NGINX Gateway Fabric kur
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml
kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.5.0/deploy/default/deploy.yaml

# 2. Gateway controller'ı yapılandır
kubectl patch deployment nginx-gateway -n nginx-gateway --type='json' \
  -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/args/2", "value": "--gatewayclass=cluster-gateway-class"}]'

# 3. Gateway infrastructure'ı deploy et
kubectl apply -f gatewayclass.yaml
kubectl apply -f gateway.yaml

# 4. Zabbix HTTPRoute'u deploy et
kubectl apply -f zabbix-httproute.yaml

# 5. Kontrol et
kubectl get gateway -A
kubectl get httproute -A

Sık Karşılaşılan Sorunlar ve Çözümleri

Problem 1: HTTPRoute "Not Allowed by Listeners" hatası

Çözüm: Gateway'de allowedRoutes.namespaces.from: All ekleyin.

---

Problem 2: Gateway EXTERNAL-IP pending kalıyor

Çözüm: On-premise kurulumda MetalLB kullanın veya manuel IP atayın: (Bu komut, MetalLB gibi bir LoadBalancer servisi olmayan Lab/Test ortamlarında manuel IP atamak içindir. Production ortamında Cloud Provider veya MetalLB bu IP'yi otomatik verir.)

kubectl patch svc nginx-gateway -n nginx-gateway \
  -p '{"spec":{"externalIPs":["10.67.67.217"]}}'

---

Problem 3: Backend HTTPS çalışmıyor

Çözüm: NGINX Gateway Fabric, backend TLS konusunda çok katı standartlara sahip. Self-signed sertifikalarla uğraşmak yerine, SSL Offloading (Termination) yapıp arkada HTTP kullanmak şu an için en stabil ve hızlı yöntem.

Önemli Trickler ve Best Practices

1. Gateway Namespace Seçimi

Gateway'i infrastructure namespace'ine (nginx-gateway) koyun, uygulama namespace'ine değil. Böylece:

• Merkezi yönetim sağlanır
• Uygulama namespace'leri silinse bile gateway ayakta kalır
• Rol ayrımı net olur

2. Gateway İsimlendirme

zabbix-gateway gibi servise özel isim yerine cluster-gateway gibi neutral isim kullanın. Gateway tüm cluster'a hizmet ediyor.

3. LoadBalancer External IP

Cloud sağlayıcı kullanmıyorsanız:

kubectl patch svc nginx-gateway -n nginx-gateway \
  -p '{"spec":{"externalIPs":["YOUR_IP"]}}'

4. Multiple Listeners

Hem HTTP hem HTTPS için ayrı listener tanımlayın:

listeners:
  - name: http
    port: 80
  - name: https
    port: 443

HTTPRoute her ikisine de bağlanabilir:

parentRefs:
  - name: cluster-gateway
    sectionName: http
  - name: cluster-gateway
    sectionName: https

5. Debugging

Gateway durumunu kontrol etmek için:

# Gateway programmed mı?
kubectl get gateway -n nginx-gateway

# Route accepted mı?
kubectl describe httproute zabbix-route -n zabbix

# NGINX Gateway Fabric logları
kubectl logs -n nginx-gateway deployment/nginx-gateway -f

Gateway API vs Ingress: Özet Karşılaştırma

Özellik	Ingress	Gateway API
Modüler yapı	❌	✅
Rol ayrımı	❌	✅
Advanced routing	Sınırlı	✅
Multiple protocols	❌	✅
Vendor-neutral	Kısmen	✅
Production-ready	✅	✅ (v1.0+)

Kubectl Alias'ları (Bonus)

Gateway API ile çalışırken işinizi kolaylaştıracak alias'lar:

# ~/.bash_aliases dosyasına ekleyin
alias kgg='kubectl get gateway'
alias kgh='kubectl get httproute'
alias kgc='kubectl get gatewayclass'
alias kdg='kubectl describe gateway'
alias kdh='kubectl describe httproute'
alias kdc='kubectl describe gatewayclass'

# Hepsini görmek için
alias kgg-all='kubectl get gateway -A'
alias kgh-all='kubectl get httproute -A'

Kullanım:

kgg -n nginx-gateway        # Gateway'leri listele
kgh-all                     # Tüm HTTPRoute'ları göster
kdh zabbix-route -n zabbix  # Route detaylarını göster

Sonuç

Gateway API, Kubernetes routing'in geleceği. 2026'da NGINX Ingress'in güncelleme almaması ile birlikte Gateway API'ye geçiş kaçınılmaz hale geliyor.

Modüler yapısı sayesinde:

• Cluster admin'ler altyapıyı yönetiyor
• Geliştiriciler sadece kendi route'larını düşünüyor
• Farklı namespace'ler izole çalışıyor
• Controller değiştirmek kolay

Eğer yeni bir proje başlıyorsanız veya mevcut Ingress yapınızı modernize etmek istiyorsanız, Gateway API doğru seçim.

Önemli Not: Bu yazıda kullanılan yapı production-ready. Ancak backend HTTPS gibi bazı özellikler NGINX Gateway Fabric v1.5.0'da henüz tam desteklenmiyor. Bu özellikler 2025 Q3-Q4'te gelecek güncellemelerle eklenecek.

---

Kaynaklar

• Kubernetes Gateway API Docs
• NGINX Gateway Fabric GitHub
• Gateway API v1.1.0 Release
• NGINX Ingress Deprecation Announcement

---

Bu makale, gerçek bir production deployment deneyimine dayanarak yazılmıştır. Zabbix monitoring sistemi üzerinde test edilmiş ve çalışır durumda olan yapılandırmalar kullanılmıştır.