Gateway API’yi kind ile Yerelde Deneme Rehberi

Gateway API’yi öğrenmek ve denemek için üretim ortamının karmaşıklığına girmek şart değil; yerel makinede çalışan bir kind kümesi hızlı bir başlangıç sağlar. Bu yazıda kind ile Kubernetes kümesi oluşturmayı, cloud-provider-kind üzerinden hem LoadBalancer Servislerini hem de Gateway API denetleyicisini devreye almayı, ardından bir Gateway ve HTTPRoute tanımlayarak örnek uygulamaya trafik yönlendirmeyi adım adım göreceksiniz.

Bu kurulum yalnızca öğrenme ve deneme amaçlıdır. Üretim iş yükleri için uygun değildir; gerçek ortamlar için Gateway API uygulama listesinden ihtiyacınıza uyan bir denetleyici seçmelisiniz.

Ön koşullar

Başlamadan önce yerel makinede şu araçların kurulu olması gerekir:

• Docker: kind ve cloud-provider-kind için gereklidir.
• kubectl: Kubernetes komut satırı aracı.
• kind: Docker içinde Kubernetes çalıştırmak için.
• curl: Rotaları test etmek için.

kind ile küme oluşturma

Tek düğümlü bir Kubernetes kümesini Docker konteyneri içinde çalıştırmak için şu komutu kullanın:

kind create cluster

cloud-provider-kind kurulumu

cloud-provider-kind, bu kurulumun iki temel bileşenini sağlar:

• LoadBalancer tipindeki Servislere adres atayan bir LoadBalancer denetleyicisi.
• Gateway API özelliklerini karşılayan bir Gateway API denetleyicisi.

Bunlara ek olarak Gateway API için gereken Custom Resource Definition (CRD) tanımlarını da otomatik olarak kümeye kurar. Kind bir bulut sağlayıcısı olmasa da proje bulut ortamındaki özellikleri simüle ettiği için bu adı taşıyor.

Kind kümesini oluşturduğunuz ana makinede cloud-provider-kind’ı bir Docker konteyneri olarak çalıştırın:

VERSION="$(basename $(curl -s -L -o /dev/null -w '%{url_effective}' https://github.com/kubernetes-sigs/cloud-provider-kind/releases/latest))"
docker run -d --name cloud-provider-kind --rm --network host -v /var/run/docker.sock:/var/run/docker.sock registry.k8s.io/cloud-provider-kind/cloud-controller-manager:${VERSION}

Bazı sistemlerde Docker soketine erişmek için yükseltilmiş yetkiler gerekebilir. Konteynerin çalıştığını doğrulamak için:

docker ps --filter name=cloud-provider-kind
docker logs cloud-provider-kind

Gateway tanımlama

cloud-provider-kind, cloud-provider-kind adında bir GatewayClass’ı otomatik olarak sağlar. Aşağıdaki manifest, gateway-infra adlı yeni bir namespace oluşturur, 80 numaralı porttan dinleyen bir Gateway kurar ve *.exampledomain.example desenine uyan hostname’leri kabul eder. Örnekte tüm namespace’lerden route eklenmesine izin verildi; gerçek kümelerde allowedRoutes.namespaces alanında Same veya Selector değerlerini tercih ederek eklemeleri sınırlandırmak daha güvenli.

---
apiVersion: v1
kind: Namespace
metadata:
name: gateway-infra
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: gateway
namespace: gateway-infra
spec:
gatewayClassName: cloud-provider-kind
listeners:
- name: default
hostname: "*.exampledomain.example"
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: All

Gateway’in doğru şekilde programlandığını ve adres aldığını kontrol edin:

kubectl get gateway -n gateway-infra gateway

PROGRAMMED sütunu True, ADDRESS alanı da bir IP değeri içermelidir.

Örnek uygulamanın dağıtımı

Yapılandırmayı test etmek için 3000 portunda dinleyen ve istekleri (path, header, ortam değişkenleri) geri döndüren basit bir echo uygulaması dağıtılır. Uygulama demo adlı namespace’te çalışır:

apiVersion: v1
kind: Namespace
metadata:
name: demo
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: echo
name: echo
namespace: demo
spec:
ports:
- name: http
port: 3000
protocol: TCP
targetPort: 3000
selector:
app.kubernetes.io/name: echo
type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: echo
name: echo
namespace: demo
spec:
selector:
matchLabels:
app.kubernetes.io/name: echo
template:
metadata:
labels:
app.kubernetes.io/name: echo
spec:
containers:
- env:
- name: POD_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.name
- name: NAMESPACE
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.namespace
image: registry.k8s.io/gateway-api/echo-basic:v20251204-v1.4.1
name: echo-basic

HTTPRoute oluşturma

Sırada Gateway’den echo uygulamasına trafik yönlendirecek HTTPRoute var. Bu route, some.exampledomain.example hostname’ine gelen istekleri yakalar ve gateway-infra namespace’indeki Gateway’e bağlanır:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: echo
namespace: demo
spec:
parentRefs:
- name: gateway
namespace: gateway-infra
hostnames: ["some.exampledomain.example"]
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: echo
port: 3000

Rotayı test etmek

Gateway’in IP adresini alıp curl ile some.exampledomain.example hostname üzerinden istek gönderebilirsiniz. Aşağıdaki komut POSIX kabuklar için verildi; gerekirse ortamınıza göre uyarlayın:

GW_ADDR=$(kubectl get gateway -n gateway-infra gateway -o jsonpath='{.status.addresses[0].value}')
curl --resolve some.exampledomain.example:80:${GW_ADDR} http://some.exampledomain.example

Başarılı bir yanıtta, isteğin path, host, method, header ve pod bilgilerini içeren bir JSON çıktısı görürsünüz. Bu, Gateway API kurulumunun doğru çalıştığı anlamına gelir.

Sorun giderme

Beklenen sonuç alınamıyorsa ilk adım kaynakların durumunu incelemektir.

Gateway durumu

kubectl get gateway -n gateway-infra gateway -o yaml

status altında şu koşulların sağlanması beklenir:

• Accepted: True — Gateway denetleyici tarafından kabul edildi.
• Programmed: True — Gateway başarıyla yapılandırıldı.
• .status.addresses alanı bir IP adresi ile doldurulmuş olmalı.

HTTPRoute durumu

kubectl get httproute -n demo echo -o yaml

status.parents altındaki koşullara bakın. Sık karşılaşılan durumlar:

• ResolvedRefs değeri False ve BackendNotFound nedeni: Backend Servis yok ya da adı yanlış.
• Accepted değeri False: Route Gateway’e bağlanamadı; namespace izinlerini veya hostname eşleşmesini kontrol edin.

Backend bulunamadığında görülen tipik bir hata şöyledir:

status:
parents:
- conditions:
- lastTransitionTime: "2026-01-19T17:13:35Z"
message: backend not found
observedGeneration: 2
reason: BackendNotFound
status: "False"
type: ResolvedRefs
controllerName: kind.sigs.k8s.io/gateway-controller

Denetleyici logları

Kaynak durumları sorunu göstermiyorsa cloud-provider-kind loglarını canlı izleyin:

docker logs -f cloud-provider-kind

Bu çıktı, hem LoadBalancer hem de Gateway API denetleyicisinin ayrıntılı loglarını içerir.

Temizlik

Deneyler bittiğinde kaynakları temizleyebilirsiniz. Önce namespace’leri silin:

kubectl delete namespace gateway-infra
kubectl delete namespace demo

Ardından cloud-provider-kind konteynerini durdurun. Konteyner --rm ile başlatıldığı için durdurulunca otomatik silinir:

docker stop cloud-provider-kind

Son olarak kind kümesini silin:

kind delete cluster

Sonraki adımlar

Yerel ortamda Gateway API ile pratik yaptıktan sonra üretime hazır uygulamalara geçebilirsiniz. Gateway API implementasyonları sayfasından ihtiyacınıza uygun bir denetleyici seçebilir; TLS, trafik bölme veya header manipülasyonu gibi ileri konuları resmi dokümantasyondan çalışabilirsiniz. Path tabanlı yönlendirme, header eşleştirme ve istek yansıtma gibi özellikler için kullanıcı rehberleri iyi bir referanstır.

Tekrar hatırlatalım: kind üzerindeki bu kurulum yalnızca geliştirme ve öğrenme amaçlıdır. Gerçek iş yükleri için üretime uygun bir Gateway API implementasyonu tercih edin.

Kaynaklar ve İleri Okuma

• kubernetes.io

• Kubernetes Blog: Experimenting with Gateway API using kind
• Gateway API resmi dokümantasyonu
• Gateway API implementasyonları
• Gateway API başlangıç rehberleri
• Gateway API API referansı
• kind projesi
• kind hızlı başlangıç rehberi
• cloud-provider-kind deposu
• kubectl kurulum belgeleri
• Docker kurulumu
• curl
• Gateway API v1.5: Altı Özellik Stable Oldu, Ne Değişiyor?
• Gateway API v1.6: TCPRoute ve UDPRoute Standard Oldu
• Ingress2Gateway 1.0: Ingress’ten Gateway API’ye Geçiş