H.Ozgan
a.k.a netologist

Kong API Gateway — Kapsamlı Geliştirici Rehberi

13 Ağustos 2026 · netologist · 23 dakika, 4691 kelime · #api-gateway #ingress #kong #microservices #note #plugins

Kong Gateway ile API geliştirme, güvenlik ve operasyon süreçleri için derinlemesine, uygulamaya dönük bir kaynak — temel kavramlar, eklentiler (plugin), dağıtım modelleri, Kubernetes entegrasyonu, özel eklenti geliştirme, performans ve üretim (production) desenlerini kapsar.

İçindekiler

  1. Giriş ve Mimari
  2. Temel Varlıklar (Entities)
  3. Dağıtım Modelleri
  4. Kurulum ve Hızlı Başlangıç
  5. Admin API
  6. Bildirimsel (Declarative) Yapılandırma ve decK
  7. Kubernetes Ingress Controller (KIC)
  8. Kimlik Doğrulama Eklentileri
  9. Trafik Kontrol Eklentileri
  10. Dönüştürme (Transformation) Eklentileri
  11. Loglama ve Gözlemlenebilirlik
  12. Yük Dengeleme ve Sağlık Kontrolleri
  13. Özel Eklenti Geliştirme (Lua)
  14. Güvenlik En İyi Uygulamaları
  15. Performans Ayarlama (Tuning)
  16. Üretim Desenleri (Patterns)
  17. CI/CD ve GitOps
  18. Sorun Giderme
  19. CLI ve Admin API Hızlı Referans

1. Giriş ve Mimari

Kong; NGINX ve OpenResty (NGINX + LuaJIT) üzerine inşa edilmiş, bulut-native ve platform bağımsız bir API Gateway‘dir. İstemciler ile arka uç (upstream) servisler arasında konumlanır ve kimlik doğrulama, hız sınırlama (rate limiting), dönüştürme, loglama, yük dengeleme ve trafik şekillendirme gibi ortak sorumlulukları mikroservislerin her birinde tekrar tekrar yazmak zorunda kalmadan merkezi biçimde ele alır.

1.1 Neden Gateway Kullanılır?

1.2 Üst Düzey Mimari

                     ┌────────────────────┐
İstemci İstekleri ──▶│   Kong Gateway      │
                     │  (OpenResty/NGINX)  │
                     │  - Router            │
                     │  - Plugin Pipeline   │
                     │  - Load Balancer     │
                     └─────────┬───────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                 ▼
        Upstream A       Upstream B         Upstream C

Kong’un istek yaşam döngüsü, NGINX/OpenResty fazlarını yansıtan fazlar üzerinden ilerler ve eklentiler bu fazlara bağlanır:

FazAmaç
certificateSSL/TLS el sıkışmasını yönetir (SNI’ye göre sertifika seçimi)
rewriteYönlendirme kararından önce isteği yeniden yazar
accessKimlik doğrulama, yetkilendirme, hız sınırlama — çoğu eklenti burada çalışır
header_filterYanıt gönderilmeden önce header’ları değiştirir
body_filterYanıt gövdesi parçalarını (chunk) değiştirir
logFire-and-forget loglama, analitik

Fazları anlamak, özel eklenti yazarken veya sıralarken kritiktir — yanıt gövdesini değiştiren bir eklenti access değil, body_filter fazını uygulamalıdır.

1.3 Kong Ürün Ailesi

2. Temel Varlıklar (Entities)

Kong’daki her şey bir varlık olarak modellenir; Admin API, declarative YAML veya Kubernetes CRD’leri üzerinden yapılandırılır.

2.1 Service

Bir upstream API/mikroservisi temsil eder.

curl -i -X POST http://localhost:8001/services \
  --data name=orders-service \
  --data url=http://orders.internal:8080

2.2 Route

İsteklerin nasıl eşleştirileceğini ve bir Service’e nasıl yönlendirileceğini tanımlar (path, host, method, header, SNI’ye göre).

curl -i -X POST http://localhost:8001/services/orders-service/routes \
  --data 'paths[]=/orders' \
  --data name=orders-route \
  --data strip_path=false

Önemli route alanları:

2.3 Upstream ve Target

Upstream, bir Target (backend IP:port girdileri) havuzunu temsil eden sanal bir hostname’dir; yük dengeleme ve sağlık kontrollerini mümkün kılar.

curl -i -X POST http://localhost:8001/upstreams --data name=orders-upstream
curl -i -X POST http://localhost:8001/upstreams/orders-upstream/targets \
  --data target=10.0.0.11:8080 --data weight=100
curl -i -X POST http://localhost:8001/upstreams/orders-upstream/targets \
  --data target=10.0.0.12:8080 --data weight=100

Ardından bir Service’in host alanını ham bir IP yerine upstream adına (orders-upstream) yönlendirin.

2.4 Consumer

Kong’un kimlik bilgisi (credential), ACL grubu ve hız sınırlama kotası bağlayabileceği bir API istemcisini (kullanıcı, uygulama veya iş ortağı) temsil eder.

curl -i -X POST http://localhost:8001/consumers --data username=mobile-app

2.5 Plugin

Bir davranışı (kimlik doğrulama, hız sınırlama, dönüştürme, loglama) bir Service, Route, Consumer’a veya global olarak ekler.

curl -i -X POST http://localhost:8001/services/orders-service/plugins \
  --data name=rate-limiting \
  --data config.minute=100 \
  --data config.policy=local

Kapsam önceliği (en özelden en genele): Route + Consumer > Route > Service > Consumer > Global. Bu önceliği anlamak, belirli bir istek için hangi eklenti örneğinin gerçekten tetikleneceğini öngörmek açısından şarttır.

2.6 Certificate ve SNI

TLS sertifikaları ve bunlara bağlı Server Name Indication hostname’leri; edge’de SNI tabanlı yönlendirme ve TLS sonlandırma için kullanılır.

2.7 Vault (Enterprise / 3.x+)

Secret referansları ({vault://...}) sayesinde hassas yapılandırma değerlerini (API anahtarları, TLS anahtarları) Kong yapılandırmasında düz metin olarak tutmak yerine HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager veya ortam değişkenlerinde saklayabilirsiniz.

2.8 Varlık İlişki Diyagramı (Kavramsal)

Consumer ──credential──▶ (key-auth / jwt / oauth2 / basic-auth / hmac / mtls)
Consumer ──üyedir──────▶ ACL Grubu
Service  ──çoklu içerir▶ Route
Service  ──çoklu içerir▶ Plugin
Route    ──çoklu içerir▶ Plugin
Service  ──işaret eder─▶ Upstream ──çoklu içerir──▶ Target

3. Dağıtım Modelleri

3.1 Geleneksel (DB Destekli)

Kong node’ları yapılandırmayı PostgreSQL‘den okur/yazar. Admin API üzerinden sık sık dinamik değişiklik gerektiren senaryolarda (self-servis developer portal, sık consumer/plugin değişimi) uygundur.

3.2 DB’siz (Declarative)

Kong tüm yapılandırmasını başlangıçta statik bir YAML/JSON dosyasından (kong.yml) yükler veya Admin API’nin /config endpoint’i üzerinden alır. Veritabanı gerekmez.

Bu, günümüzde çoğu ekip için önerilen varsayılan yaklaşımdır — özellikle decK ile birlikte kullanıldığında (bkz. Bölüm 6).

3.3 Hibrit Mod (Control Plane / Data Plane Ayrımı)

Faydaları: DP’ler her biri DB bağlantısına ihtiyaç duymadan yatayda ölçeklenebilir ve trafiğe yakın (çok bölgeli) dağıtılabilir; sadece CP hassas kimlik bilgilerine dokunduğu için saldırı yüzeyi azalır.

        ┌───────────────┐
        │ Control Plane │──── Postgres
        │ (Admin API)   │
        └───────┬───────┘
        mTLS üzerinden websocket, config senkronizasyonu
   ┌────────────┼────────────┐
   ▼             ▼            ▼
 DP (us-east)  DP (eu-west)  DP (ap-south)

3.4 Konnect (SaaS Control Plane)

Kong tarafından hosted control plane; siz yalnızca data plane’leri (self-hosted veya Kong-hosted “Serverless”) çalıştırırsınız; yapılandırma, analitik ve developer portal yönetimini Konnect’in UI/API/Terraform provider’ı üzerinden yaparsınız.

4. Kurulum ve Hızlı Başlangıç

4.1 Docker (DB’siz, en hızlı yol)

mkdir -p ~/kong-declarative
cat > ~/kong-declarative/kong.yml << 'EOF'
_format_version: "3.0"
services:
  - name: example-service
    url: https://httpbin.org
    routes:
      - name: example-route
        paths:
          - /example
EOF

docker run -d --name kong \
  -v ~/kong-declarative:/kong/declarative \
  -e "KONG_DATABASE=off" \
  -e "KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
  -p 8000:8000 -p 8443:8443 -p 8001:8001 \
  kong:3.7

Test edin:

curl http://localhost:8000/example/get

4.2 Docker Compose (DB destekli, dinamik Admin API ile lokal geliştirme için)

version: "3.8"
services:
  kong-database:
    image: postgres:15
    environment:
      POSTGRES_USER: kong
      POSTGRES_DB: kong
      POSTGRES_PASSWORD: kongpass
    volumes:
      - kong_data:/var/lib/postgresql/data

  kong-migrations:
    image: kong:3.7
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
    depends_on:
      - kong-database

  kong:
    image: kong:3.7
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: 0.0.0.0:8001
    ports:
      - "8000:8000"
      - "8443:8443"
      - "8001:8001"
    depends_on:
      - kong-migrations

volumes:
  kong_data: {}

4.3 Helm (Kubernetes)

helm repo add kong https://charts.konghq.com
helm repo update
helm install kong kong/kong \
  --namespace kong --create-namespace \
  --set ingressController.installCRDs=false \
  --set admin.enabled=true

5. Admin API

Admin API (varsayılan port 8001) Kong’un kontrol yüzeyidir. Her varlığın bir REST kaynağı vardır.

5.1 Temel Endpoint’ler

# Service oluşturma
curl -X POST :8001/services -d name=svc -d url=http://backend:80

# Service listeleme
curl :8001/services

# Güncelleme (kısmi PATCH)
curl -X PATCH :8001/services/svc -d url=http://backend:8081

# Silme
curl -X DELETE :8001/services/svc

# İç içe oluşturma (bir service altında route)
curl -X POST :8001/services/svc/routes -d 'paths[]=/api'

# Global olarak bir eklenti etkinleştirme
curl -X POST :8001/plugins -d name=prometheus

# Uygulamadan önce yapılandırmayı doğrulama (şema kontrolü)
curl -X POST :8001/schemas/plugins/validate -d name=rate-limiting -d config.minute=10

5.2 Admin API’yi Güvenli Hale Getirme

8001 portunu asla açık internete maruz bırakmayın. Üretimde:

5.3 Admin API ile kong.conf Farkı

Çalışma zamanı varlıkları (service, route, plugin) Admin API veya declarative config üzerinden yönetilir. Node seviyesi ayarlar (worker süreç sayısı, listen adresleri, log seviyeleri, plugin allowlist) kong.conf içinde veya KONG_* ortam değişkenlerinde tanımlanır ve reload/restart gerektirir.

6. Bildirimsel (Declarative) Yapılandırma ve decK

6.1 Neden decK

decK (deck), Kong yapılandırmasını kod olarak yönetmek için kullanılan CLI aracıdır — çalışan bir Kong (veya Konnect) örneğine karşı kong.yml dosyalarını diff’ler, senkronize eder ve doğrular. Kong için GitOps iş akışlarının belkemiğidir.

# Mevcut durumu bir dosyaya aktar
deck gateway dump -o kong.yml

# Lokal dosyayı canlı Kong ile karşılaştır
deck gateway diff -s kong.yml

# Lokal dosyayı uygula (eşleşecek şekilde oluşturur/günceller/siler)
deck gateway sync -s kong.yml

# Yalnızca sözdizimi/şema doğrulaması, ağ çağrısı yok
deck file validate -s kong.yml

# Özel kural kümelerine (naming convention, zorunlu tag vb.) göre lint
deck file lint -s kong.yml -r ruleset.yml

6.2 Örnek kong.yml

_format_version: "3.0"
_transform: true

services:
  - name: catalog-service
    url: http://catalog.internal:8080
    tags: [team-catalog, prod]
    routes:
      - name: catalog-route
        paths: ["/catalog"]
        strip_path: false
    plugins:
      - name: rate-limiting
        config:
          minute: 300
          policy: local
      - name: key-auth
        config:
          key_names: ["apikey"]

consumers:
  - username: partner-a
    keyauth_credentials:
      - key: "abc123-partner-a"
    acls:
      - group: partners

acls: []

upstreams:
  - name: catalog-upstream
    algorithm: round-robin
    healthchecks:
      active:
        http_path: /health
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 5
          http_failures: 3
    targets:
      - target: 10.0.1.10:8080
        weight: 100
      - target: 10.0.1.11:8080
        weight: 100

6.3 decK En İyi Uygulamaları

7. Kubernetes Ingress Controller (KIC)

KIC, Kubernetes kaynaklarını izler ve bunları otomatik olarak Kong yapılandırmasına çevirir — K8s ortamında manuel Admin API çağrısına gerek kalmaz.

7.1 Standart Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: orders-ingress
  annotations:
    konghq.com/strip-path: "true"
  labels:
    konghq.com/plugins: rate-limit-orders
spec:
  ingressClassName: kong
  rules:
    - http:
        paths:
          - path: /orders
            pathType: Prefix
            backend:
              service:
                name: orders-svc
                port:
                  number: 80

7.2 Kong CRD’leri

Kong, düz Ingress’in ifade edemediği yetenekler için Kubernetes’i Custom Resource Definition’larla genişletir:

CRDAmaç
KongPlugin / KongClusterPluginBir plugin yapılandırması tanımlar, annotation veya label ile bağlanır
KongConsumerBir K8s kimliğini Kong Consumer’ına eşler
KongIngressAyrıntılı routing/upstream yapılandırması (legacy, büyük ölçüde yerini aldı)
KongCredentialKimlik bilgilerini (key-auth, jwt vb.) bir KongConsumer‘a bağlar
TCPIngress / UDPIngressHTTP olmayan TCP/UDP trafiğini yönlendirir
KongVaultHarici secret backend’lerine referans verir
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit-orders
plugin: rate-limiting
config:
  minute: 100
  policy: local
---
apiVersion: v1
kind: Service
metadata:
  name: orders-svc
  annotations:
    konghq.com/plugins: rate-limit-orders

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: mobile-app
  annotations:
    kubernetes.io/ingress.class: kong
username: mobile-app
credentials:
  - mobile-app-apikey
---
apiVersion: v1
kind: Secret
metadata:
  name: mobile-app-apikey
type: Opaque
stringData:
  kongCredType: key-auth
  key: mobile-secret-key

7.3 Gateway API Desteği

Modern KIC sürümleri, Ingress‘e alternatif olarak Kubernetes Gateway API‘yi (Gateway, HTTPRoute, TCPRoute, GRPCRoute) destekler — K8s ekosisteminin daha ifade gücü yüksek, taşınabilir trafik yönlendirmesi (header eşleştirme, canary için ağırlıklı backend’ler, namespace’ler arası routing) için yöneldiği doğrultudur.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: orders-route
spec:
  parentRefs:
    - name: kong
  rules:
    - matches:
        - path: { type: PathPrefix, value: /orders }
      backendRefs:
        - name: orders-svc
          port: 80
          weight: 90
        - name: orders-svc-canary
          port: 80
          weight: 10

8. Kimlik Doğrulama Eklentileri

8.1 Key Authentication

En basit yöntem — istemciler bir header, query parametresi veya body içinde API anahtarı gönderir.

curl -X POST :8001/services/svc/plugins -d name=key-auth -d config.key_names=apikey
curl -X POST :8001/consumers/alice/key-auth -d key=alice-secret-key

İstemci çağrısı: curl -H "apikey: alice-secret-key" https://api.example.com/svc

8.2 JWT

Kong, istek başına harici bir auth sunucusuna çağrı yapmadan, istemcinin issuer’ı tarafından imzalanmış bir JWT’yi (RS256/HS256) doğrular.

curl -X POST :8001/services/svc/plugins -d name=jwt
curl -X POST :8001/consumers/alice/jwt \
  -d algorithm=RS256 \
  -d rsa_public_key="$(cat pubkey.pem)"

Not: Kong’un jwt eklentisi imza/geçerlilik süresini doğrular — bir OIDC sağlayıcısının introspection endpoint’ini çağırmaz. Token introspection içeren tam OAuth2/OIDC akışları için bunun yerine OpenID Connect eklentisini (Enterprise) kullanın.

8.3 OAuth2

OAuth2 çerçevesini doğrudan Kong içinde uygular (authorization code, client credentials, implicit, password grant’ler).

curl -X POST :8001/services/svc/plugins -d name=oauth2 \
  -d config.enable_authorization_code=true \
  -d config.scopes=read,write

Çoğu modern kurulumda ekipler, OAuth2/OIDC’yi harici bir IdP’de (Auth0, Okta, Keycloak) sonlandırıp token doğrulama, discovery/introspection/JWKS işlemleri için Kong’un OpenID Connect eklentisini kullanmayı tercih eder.

8.4 Basic Auth / LDAP / HMAC / mTLS

8.5 Çoklu Kimlik Doğrulama Deseni (OR Mantığı)

Aynı route’ta hem key-auth hem de JWT’yi ya-ya da mantığıyla kabul etmek için her iki eklentiyi de uygulayıp her birinde config.anonymous‘u ortak bir anonim consumer’a ayarlayın. Kong 3.x’te native anonim consumer OR-auth zincirleme kullanın: her auth eklentisine aynı config.anonymous=<uuid> verilir; ilk eklenti başarısız olursa istek anonim olarak devam eder ve ikinci eklentiye gerçek bir kimlik doğrulama şansı verilir — ikisi de başarısız olursa istek genellikle anonim grubu engelleyen bir ACL eklentisi tarafından reddedilir.

9. Trafik Kontrol Eklentileri

9.1 Rate Limiting (Hız Sınırlama)

curl -X POST :8001/services/svc/plugins -d name=rate-limiting \
  -d config.minute=60 \
  -d config.hour=1000 \
  -d config.policy=redis \
  -d config.redis.host=redis.internal

Rate-limiting-advanced (Enterprise), sliding-window algoritmaları, eklenti örneği başına birden fazla limit ve maliyet tabanlı (cost-based) sınırlama ekler.

9.2 ACL (Erişim Kontrol Listeleri)

Route başına Consumer gruplarını whitelist/blacklist yapmak için herhangi bir auth eklentisiyle birleştirin.

curl -X POST :8001/consumers/alice/acls -d group=partners
curl -X POST :8001/routes/orders-route/plugins -d name=acl -d config.allow=partners

9.3 IP Restriction

curl -X POST :8001/services/svc/plugins -d name=ip-restriction \
  -d config.allow=10.0.0.0/8 -d config.allow=203.0.113.5

9.4 Request Size Limiting

curl -X POST :8001/services/svc/plugins -d name=request-size-limiting \
  -d config.allowed_payload_size=10

9.5 Proxy Caching

Cache edilebilir GET endpoint’leri için backend yükünü azaltmak amacıyla upstream yanıtlarını (method/status/vary bazında) önbelleğe alır.

curl -X POST :8001/services/svc/plugins -d name=proxy-cache \
  -d config.content_type="application/json" \
  -d config.cache_ttl=300 \
  -d config.strategy=memory

9.6 Circuit Breaker Desenleri

Kong, “circuit breaker” adında birinci taraf bir eklenti sunmaz; ancak bu deseni şu yollarla sağlar:

10. Dönüştürme (Transformation) Eklentileri

10.1 Request Transformer

curl -X POST :8001/routes/orders-route/plugins -d name=request-transformer \
  -d config.add.headers=X-Request-Source:kong \
  -d config.remove.headers=X-Internal-Debug \
  -d config.rename.headers=X-Old-Name:X-New-Name

10.2 Response Transformer

curl -X POST :8001/routes/orders-route/plugins -d name=response-transformer \
  -d config.remove.json=internal_id \
  -d config.add.headers=X-Powered-By:Kong

10.3 Correlation ID

Dağıtık izleme (tracing) korelasyonu için istek başına benzersiz bir ID enjekte eder/yayar.

curl -X POST :8001/services/svc/plugins -d name=correlation-id \
  -d config.header_name=X-Correlation-ID \
  -d config.generator=uuid \
  -d config.echo_downstream=true

10.4 gRPC Transcoding

grpc-gateway ve grpc-web eklentileri sırasıyla HTTP/JSON istemcilerinin gRPC backend’leriyle konuşmasına ve tarayıcı gRPC-Web istemcilerinin standart gRPC servisleriyle konuşmasına olanak tanır — dahili gRPC mikroservislerini yeniden yazmadan yalnızca REST destekleyen tüketicilere açmak istediğinizde kullanışlıdır.

11. Loglama ve Gözlemlenebilirlik

11.1 Prometheus Metrikleri

curl -X POST :8001/plugins -d name=prometheus \
  -d config.status_code_metrics=true \
  -d config.latency_metrics=true \
  -d config.bandwidth_metrics=true

Admin API portu üzerinde (veya KONG_STATUS_LISTEN ile yapılandırılmış ayrı bir 8100 status portunda) GET /metrics‘i scrape edin. Önemli metrikler: kong_http_requests_total, kong_latency_bucket, kong_bandwidth_bytes, kong_upstream_target_health.

11.2 Yapılandırılmış Loglama

EklentiHedef
file-logYerel dosya (JSON satırları)
http-logHTTP endpoint (log toplayıcınızın ingest API’si)
tcp-log / udp-logSyslog tarzı yönlendiriciler
syslogYerel syslog
datadogDatadog metrikleri + logları
zipkin / opentelemetryDağıtık izleme span’leri
curl -X POST :8001/services/svc/plugins -d name=http-log \
  -d config.http_endpoint=https://logs.example.com/ingest \
  -d config.timeout=5000 \
  -d config.keepalive=5000

11.3 OpenTelemetry

opentelemetry eklentisi, izleri (isteğe bağlı olarak log/metrikleri de) OTLP formatında herhangi bir OTel uyumlu backend’e (Jaeger, Tempo, Honeycomb, Datadog vb.) aktarır — yeni dağıtımlarda eski Zipkin eklentisinin yerini alan, dağıtık izleme için modern varsayılan seçenektir.

curl -X POST :8001/plugins -d name=opentelemetry \
  -d config.endpoint=http://otel-collector:4318/v1/traces \
  -d config.resource_attributes.service.name=kong-gateway

11.4 Dashboard’lar

Kong, Prometheus eklenti çıktısı için resmi Grafana dashboard’ları yayınlar — istek oranı, p99 gecikme, upstream sağlığı ve consumer bazlı kullanım izlenebilir. kong_upstream_target_health geçişleri ve 5xx oranı sıçramaları için alerting ile birlikte kullanın.

12. Yük Dengeleme ve Sağlık Kontrolleri

12.1 Yük Dengeleme Algoritmaları

AlgoritmaDavranış
round-robinEşit döngü, target weight‘ine saygı gösterir
consistent-hashingIP, header, cookie veya query parametresi üzerinden hash — server-side session olmadan sticky routing
least-connectionsTrafiği en az aktif bağlantısı olan target’a gönderir
curl -X PATCH :8001/upstreams/orders-upstream \
  -d algorithm=consistent-hashing \
  -d hash_on=header \
  -d hash_on_header=X-Session-ID

12.2 Aktif Sağlık Kontrolleri

Kong, target’ları belirli aralıklarla proaktif olarak yoklar (probe).

curl -X PATCH :8001/upstreams/orders-upstream \
  -d healthchecks.active.http_path=/health \
  -d healthchecks.active.healthy.interval=5 \
  -d healthchecks.active.healthy.successes=2 \
  -d healthchecks.active.unhealthy.interval=5 \
  -d healthchecks.active.unhealthy.http_failures=3 \
  -d healthchecks.active.unhealthy.tcp_failures=3

12.3 Pasif Sağlık Kontrolleri

Kong gerçek proxy trafiğini gözlemler — bir target yeterli sayıda ardışık hata (5xx, timeout) döndürürse, özel bir probe olmadan sağlıksız olarak işaretlenir.

curl -X PATCH :8001/upstreams/orders-upstream \
  -d healthchecks.passive.unhealthy.http_failures=5 \
  -d healthchecks.passive.unhealthy.timeouts=3

En iyi uygulama: ikisini birden kullanın. Aktif kontroller, çökmüş bir target’ı canlı trafik almadan önce yakalar; pasif kontroller ise aktif probe’ların kaçırabileceği hataları yakalar (örn. /health sağlıklı görünse de gerçek API path’inin bozuk olması).

12.4 Kesintisiz Backend Değişimi

Yeni target’ı aynı veya daha yüksek weight ile ekleyin, sağlık/hata oranlarını izleyin, ardından eski target’ın weight’ini 0’a indirip kaldırın — herhangi bir route/service değişikliği veya istemci etkisi olmadan.

13. Özel Eklenti Geliştirme (Lua)

13.1 Eklenti Anatomisi

Bir Kong eklentisi, handler.lua (mantık) ve schema.lua (config doğrulama) içeren bir Lua modülüdür.

my-plugin/
├── kong/plugins/my-plugin/
│   ├── handler.lua
│   └── schema.lua
└── my-plugin-1.0.0-1.rockspec

schema.lua

return {
  name = "my-plugin",
  fields = {
    { config = {
        type = "record",
        fields = {
          { header_name = { type = "string", default = "X-My-Plugin" } },
          { header_value = { type = "string", required = true } },
        },
      },
    },
  },
}

handler.lua

local MyPluginHandler = {
  PRIORITY = 1000, -- diğer eklentilere göre çalışma sırası
  VERSION = "1.0.0",
}

function MyPluginHandler:access(conf)
  kong.service.request.set_header(conf.header_name, conf.header_value)
end

function MyPluginHandler:header_filter(conf)
  kong.response.set_header("X-Processed-By", "my-plugin")
end

return MyPluginHandler

13.2 Eklenti Önceliği (Priority)

PRIORITY bir tam sayıdır; aynı fazda daha yüksek olan önce çalışır. Yerleşik eklentilerden referans noktaları:

EklentiPriorityFaz kaygısı
pre-function1000000+Neredeyse her şeyden önce çalışır
cors2000Preflight’ta header ayarlamak için auth’tan önce çalışmalı
key-auth/jwt/oauth2~1000-1200Kimlik doğrulama
acl~950Auth’tan sonra, kimliği doğrulanmış consumer’a ihtiyaç duyar
rate-limiting~900Auth’tan sonra, consumer bazlı limitler için consumer kimliğine ihtiyaç duyar
request-transformer~800Auth/rate-limiting kararları verildikten sonra
post-function-1000000Neredeyse her şeyden sonra çalışır

13.3 Plugin Development Kit (PDK)

PDK (kong.* namespace’i), eklentilerin ham NGINX/OpenResty API’lerine dokunmak yerine kullanması gereken kararlı API yüzeyidir — kong.request, kong.response, kong.service, kong.log, kong.client, kong.ctx, kong.vault. PDK kullanımı, eklentinizi Kong’un sürümler arası dahili değişikliklerinden izole eder.

13.4 Serverless Fonksiyonlar (Derlenmiş Eklenti Gerektirmez)

Tam bir eklenti paketlemeden hızlı mantık için, Admin API üzerinden istek anında satır içi Lua enjekte eden pre-function / post-function (OSS) veya serverless-functions (Enterprise, birden fazla dili destekler) eklentilerini kullanın.

curl -X POST :8001/routes/orders-route/plugins -d name=pre-function \
  --data-urlencode 'config.access[1]=kong.service.request.set_header("X-Injected", "yes")'

13.5 Eklenti Testi

Kong, eklenti geliştiricileri için Docker tabanlı bir geliştirme/test ortamı olan Pongo‘yu sunar:

pongo run        # tek kullanımlık Kong + bağımlılıklarını başlat
pongo lint        # luacheck
pongo run spec/   # busted birim/entegrasyon testleri

14. Güvenlik En İyi Uygulamaları

  1. Admin API’yi kilitleyin — yalnızca dahili ağ, mTLS veya RBAC (bkz. 5.2). Bu, tek başına en yüksek etkiye sahip güvenlik kontrolüdür.
  2. Her yerde TLS — TLS’i Kong’da sonlandırın, genel route’larda protocols: [https] zorunlu kılın, HTTP → HTTPS yönlendirmesi yapın.
  3. Kimlik bilgilerini rotasyona sokun — key-auth anahtarları ve JWT imzalama anahtarları kesinti olmadan rotasyona sokulabilmelidir (yeni credential oluştur, istemcileri geçir, eskisini iptal et).
  4. Redis şifreleri, upstream kimlik bilgileri gibi eklenti config değerleri için kong.yml veya DB’de düz metin yerine Vault/secret manager kullanın.
  5. En az ayrıcalık RBAC’ı (Enterprise) — workspace/varlık erişimini ekip bazında sınırlayın; her mühendise global Admin API hakkı vermeyin.
  6. Bozuk payload’ları upstream’e ulaşmadan reddetmek için request-validator eklentisiyle (JSON Schema/OpenAPI tabanlı istek doğrulama) doğrulama ve temizleme yapın.
  7. Dahili servislerde bile rate limiting ve IP restriction’ı savunma amaçlı uygulayın — ağ çevresinin er ya da geç ihlal edileceğini varsayın (zero-trust duruşu).
  8. Genel API’lerde scraping ve credential stuffing’i azaltmak için bot-detection / ip-restriction / referrer restriction eklentilerini etkinleştirin.
  9. Yapılandırma değişikliklerinin izlenebilir olması için audit logging kullanın (Enterprise Admin API audit log veya Admin API çağrılarını yakalayan bir post-function).
  10. Kong ve eklenti sürümlerini sabitleyin, yükseltmeden önce changelog’ları gözden geçirin — Kong düzenli olarak CVE düzeltmeleri yayınlar; güncel kalın ama önce staging’de test edin.
  11. Kong tarafından açıkça temizlenmediği/üzerine yazılmadığı sürece istemci tarafından sağlanan header’lara kimlik için güvenmeyin — Kong proxy’lemeden önce bunları temizlemezse bir saldırgan X-Consumer-* tarzı header’ları taklit edebilir (Kong bunu kendi enjekte ettiği header’lar için varsayılan olarak yapar, ancak özel transformer yapılandırmalarında dikkatli olun).

15. Performans Ayarlama (Tuning)

15.1 Worker Süreçleri ve Bağlantılar

KONG_NGINX_WORKER_PROCESSES=auto
KONG_NGINX_WORKER_CONNECTIONS=16384

worker_processes‘i kullanılabilir CPU çekirdek sayısıyla eşleştirin (auto bunu otomatik yapar).

15.2 Veritabanı Önbelleği

DB destekli Kong, varlıkları paylaşımlı bellekte bir LRU cache’te tutar (mem_cache_size, varsayılan 128m) — küçük boyutlu cache’ler yük altında sık DB gidiş-dönüşlerine (cache miss) neden olur. Çok sayıda varlığı olan kümelerde bunu artırın.

KONG_MEM_CACHE_SIZE=512m

15.3 Ölçek için DB’siz/Hibrit

DB’siz data plane’ler, istek başına DB bağımlılığını tamamen ortadan kaldırır; bu, büyük ölçekte yüksek throughput ve düşük gecikmeli proxy’leme için tek başına en büyük kaldıraçtır — bu yüzden büyük üretim kümeleri için önerilen desen Hibrit moddur.

15.4 Eklenti Yükü (Overhead)

Etkinleştirilen her eklenti gecikme ekler. Kullanılmayan/global eklentileri düzenli olarak denetleyin. Mantığın evrensel olarak çalışmasına gerek yoksa, blanket global uygulama yerine eklentileri ihtiyaç duyan route/service’lere kapsamlandırmayı tercih edin. policy=redis ile rate-limiting istek başına bir ağ gidiş-dönüşü ekler — Redis’i Kong node’larına yakın konumlandırın veya mükemmel node’lar arası doğruluk gerekmiyorsa policy=local kullanın.

15.5 Keepalive ve Upstream Bağlantıları

Kong’un istek başına yeniden bağlanmak yerine backend bağlantılarını yeniden kullanması için upstream keepalive havuzlarını ayarlayın:

curl -X PATCH :8001/upstreams/orders-upstream \
  -d 'keepalive_pool_size=60' \
  -d 'keepalive_idle_timeout=60'

15.6 Yük Testi

k6, wrk veya hey ile gerçekçi, eklenti etkin bir yapılandırmaya karşı (çıplak passthrough değil) benchmark yapın — üretimde asıl önemli olan auth/rate-limiting overhead’idir, ham proxy baseline’ı değil.

16. Üretim Desenleri (Patterns)

16.1 API Versiyonlama

16.2 Canary / Blue-Green Dağıtımlar

Bir Upstream içindeki ağırlıklı target’lar, istemci tarafından görülebilir hiçbir değişiklik olmadan canary release’ler sağlar:

curl -X POST :8001/upstreams/orders-upstream/targets -d target=10.0.2.20:8080 -d weight=10   # canary, %10
curl -X PATCH :8001/upstreams/orders-upstream/targets/10.0.1.10:8080 -d weight=90            # stabil, %90

Güven arttıkça ağırlığı kademeli olarak canary target’a kaydırın; weight’i 0’a çekerek anında rollback yapın.

16.3 Backend-for-Frontend (BFF)

Her istemci türü için (/mobile/orders, /web/orders) ayrı Kong Service/Route’ları açığa çıkarın; her biri aynı veya farklı upstream kompozisyonuna işaret edebilir, her BFF yüzeyi için özel dönüştürme eklentileriyle (mobil için alan kırpma, web için genişletme) uyarlanabilir.

16.4 Çok Kiracılılık (Multi-Tenancy)

curl -X POST :8001/consumer_groups -d name=premium-tier
curl -X POST :8001/consumer_groups/premium-tier/consumers -d consumer=alice
curl -X POST :8001/consumer_groups/premium-tier/overrides/plugins/rate-limiting-advanced \
  -d config.limit=10000 -d config.window_size=60

16.5 API Kompozisyonu / Agregasyon

Kong’un kendisi yanıt agregasyonu yapmaz (birden çok backend çağrısını tek bir yanıtta birleştirme) — bu bir BFF/GraphQL-gateway meselesidir. Bunu bir Kong eklentisine zorlamak yerine, Kong’u özel bir agregasyon katmanıyla (veya protokol köprüleme için grpc-gateway eklentisiyle) birlikte kullanın.

16.6 Edge’de İstek Doğrulama

Geçersiz istekleri upstream compute’unu tüketmeden reddetmek için JSON Schema veya OpenAPI spesifikasyonuyla request-validator kullanın — özellikle genel, yüksek hacimli API’ler için değerlidir.

17. CI/CD ve GitOps

17.1 Önerilen Pipeline

1. Geliştirici kong.yml'i düzenler (veya OpenAPI spec → deck file openapi2kong)
2. PR açılır → CI `deck file validate` + `deck file lint` çalıştırır
3. CI, staging'e karşı `deck gateway diff` çalıştırır → diff'i PR yorumu olarak paylaşır
4. main'e merge edildiğinde → CD, staging'e karşı `deck gateway sync` çalıştırır
5. Manuel/otomatik promosyon → production'a karşı `deck gateway sync` çalıştırır

17.2 Örnek GitHub Actions Adımı

- name: Kong config doğrulama
  run: deck file validate -s kong.yml

- name: Staging'e karşı diff
  run: deck gateway diff -s kong.yml --kong-addr https://staging-admin.internal:8001

- name: Staging'e senkronizasyon
  if: github.ref == 'refs/heads/main'
  run: deck gateway sync -s kong.yml --kong-addr https://staging-admin.internal:8001

17.3 Terraform (Konnect Provider)

Konnect tarafından yönetilen control plane’ler için resmi Terraform provider’ı (kong/konnect), control plane’leri, service’leri, route’ları ve eklentileri Terraform kaynağı olarak yönetmenizi sağlar — Kong yapılandırmasının diğer infrastructure-as-code ile birlikte yaşadığı durumlarda kullanışlıdır.

17.4 Güvenli Rollout Disiplini

18. Sorun Giderme

BelirtiMuhtemel SebepÇözüm
no Route matched (404)Path/host/method uyuşmazlığı, yanlış strip_pathGET /routes yapılandırmasını kontrol edin, LB arkasındaysanız X-Forwarded-* header’larıyla test edin
Eklenti tetiklenmiyorYanlış kapsam (yanlış service/route’a bağlı), devre dışıKapsamı ve enabled: true‘yu doğrulamak için GET /plugins?service.id=
Kong’dan 502/504Upstream’e ulaşılamıyor, timeout çok düşük, DNS çözümlemesi başarısızupstream_connect_timeout‘u kontrol edin, Target sağlığını doğrulayın, Kong’un DNS resolver yapılandırmasını kontrol edin
Node’lar arası tutarsız rate limitÇok node’lu kümede policy=local kullanılıyorpolicy=redis veya cluster‘a geçin
Admin API değişiklikleri etkili olmuyorDB’siz mod — Admin API varlıklar için salt okunurTam declarative payload ile POST /config yapın veya deck sync kullanın
Eklentilerin eklediği yüksek gecikmeRedis gidiş-dönüşü, yavaş harici HTTP log endpoint’iAsenkron loglamaya geçin (http-log varsayılan olarak asenkrondur), Redis’i yakın konumlandırın, logları batch’leyin
SSL el sıkışma hatalarıYanlış SNI eşlemesi, eksik ara sertifika zinciriGET /certificates ve GET /snis‘i kontrol edin, zinciri openssl s_client ile doğrulayın
Data plane control plane’e bağlanmıyor (Hibrit)mTLS sertifika uyuşmazlığı, saat kayması, küme portunda ağ/firewall engelikong.conf‘ta cluster_cert/cluster_cert_key‘i kontrol edin, 8005/8006 portunun erişilebilir olduğunu doğrulayın
Özel eklenti deploy sonrası Cannot invoke handlerLua sözdizimi hatası, eklenti KONG_PLUGINS listesinde değilkong.conf/env’de plugins = bundled,my-plugin‘i kontrol edin, error log’u inceleyin

18.1 Kullanışlı Hata Ayıklama Komutları

kong config db_export         # mevcut DB destekli yapılandırmayı dosyaya aktarır
kong check kong.yml           # declarative dosya sözdizimini doğrular
kong health                   # lokal node'un temel sağlık kontrolü
curl :8001/status             # node durumu: bağlantılar, bellek, DB erişilebilirliği
curl :8001/status/ready       # readiness probe (K8s dostu)

19. CLI ve Admin API Hızlı Referans

# --- Kong CLI ---
kong start -c kong.conf
kong stop
kong reload -c kong.conf
kong migrations bootstrap      # ilk kez DB kurulumu
kong migrations up             # bekleyen migration'ları uygula
kong migrations finish         # kesintisiz yükseltmeden sonra finalize et
kong version

# --- Admin API: Service & Route ---
curl :8001/services
curl :8001/routes
curl -X POST :8001/services -d name=x -d url=http://x:80
curl -X POST :8001/services/x/routes -d 'paths[]=/x'

# --- Admin API: Plugin ---
curl :8001/plugins
curl :8001/plugins/enabled                 # bu node'a derlenmiş eklentilerin listesi
curl -X POST :8001/plugins -d name=cors    # global kapsam

# --- Admin API: Consumer & Credential ---
curl -X POST :8001/consumers -d username=bob
curl -X POST :8001/consumers/bob/key-auth -d key=bob-key
curl -X POST :8001/consumers/bob/acls -d group=default

# --- Admin API: Upstream & Target ---
curl :8001/upstreams
curl :8001/upstreams/my-upstream/health
curl -X POST :8001/upstreams/my-upstream/targets -d target=1.2.3.4:80

# --- decK ---
deck gateway dump -o kong.yml
deck gateway sync -s kong.yml
deck gateway diff -s kong.yml
deck file validate -s kong.yml
deck file openapi2kong -s openapi.yml -o kong.yml

# --- Node durumu ---
curl :8001/status
curl :8001/status/ready

Daha Fazla Kaynak

Bu rehber, Kong Gateway 3.x konvansiyonlarını yansıtır. Çalıştırdığınız sürüme göre eklenti/alan adlarını her zaman çapraz kontrol edin — isimler ve varsayılanlar ana sürümler arasında değişebilir.