Objek Inti: Service, Route, Upstream & Target — Belajar Kong API Gateway

🧱 Hubungan Antar Objek

Route  ──milik──>  Service  ──menunjuk──>  Upstream  ──berisi──>  Target
(apa yang         (ke mana            (kelompok           (host:port
 ditangkap)        diteruskan)         instance)           konkret)

Contoh:
  Route  : host api.contoh.com, path /pesanan
  Service: url http://upstream-pesanan
  Upstream: nama upstream-pesanan
  Target : pesanan-1:8080 (bobot 100)
           pesanan-2:8080 (bobot 100)

Untuk kasus sederhana, Anda cukup memakai Service + Route dan menunjuk langsung ke satu host. Upstream dan Target baru diperlukan ketika ada banyak instance yang perlu diseimbangkan.

🎯 Cara Route Dicocokkan

routes:
  - name: rute-pesanan
    paths: ["/pesanan"]
    hosts: ["api.contoh.com"]
    methods: ["GET", "POST"]
    headers:
      x-versi: ["v2"]
    protocols: ["https"]

Sebuah Route cocok hanya bila semua kriteria yang Anda isi terpenuhi. Kriteria yang tidak diisi dianggap bebas.

💡 Urutan prioritas

Ketika beberapa Route sama-sama cocok, Kong memilih yang paling spesifik — dihitung dari jumlah dan ketelitian kriteria yang cocok, bukan dari urutan penulisan di berkas. Route dengan host + path lebih diprioritaskan daripada yang hanya path. Ini berbeda dari Nginx yang sangat bergantung pada urutan blok.

⚠️ Jebakan strip_path

Service url : http://layanan-pesanan:8080
Route  path : /pesanan

strip_path: true  (BAWAAN)
  Klien meminta : /pesanan/123
  Upstream terima: /123          ← awalan DIBUANG

strip_path: false
  Klien meminta : /pesanan/123
  Upstream terima: /pesanan/123  ← utuh

🚫 Ini penyebab 404 paling sering pada Kong

Nilai bawaan strip_path: true membuang awalan path. Bila aplikasi Anda memang mendengarkan di /pesanan/123, permintaan akan tiba sebagai /123 dan aplikasi membalas 404 — sementara Kong tampak bekerja normal. Sebelum menyalahkan routing, periksa nilai strip_path lebih dulu.

⚖️ Upstream: Load Balancing

kong.yaml

upstreams:
  - name: upstream-pesanan
    algorithm: round-robin      # atau consistent-hashing, least-connections
    healthchecks:
      active:
        type: http
        http_path: /healthz
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 5
          http_failures: 3
          timeouts: 3
      passive:
        healthy:
          successes: 5
        unhealthy:
          http_failures: 5
    targets:
      - target: pesanan-1:8080
        weight: 100
      - target: pesanan-2:8080
        weight: 100

services:
  - name: layanan-pesanan
    host: upstream-pesanan      # menunjuk NAMA upstream, bukan URL
    port: 80
    protocol: http

Algoritma	Kapan dipakai
`round-robin`	Bawaan; instance setara dan tanpa state
`consistent-hashing`	Butuh permintaan dari klien sama selalu ke instance sama
`least-connections`	Durasi permintaan sangat bervariasi
`latency`	Mengutamakan instance yang paling responsif

⚠️ Health check aktif vs pasif

Aktif memanggil endpoint kesehatan secara berkala — mendeteksi instance sakit sebelum ada pengguna yang terkena. Pasif hanya mengamati hasil trafik nyata — lebih murah, tetapi berarti sebagian pengguna sudah terlanjur menerima error. Untuk produksi, aktifkan keduanya.

🔧 Penyetelan Timeout

services:
  - name: layanan-laporan
    url: http://layanan-laporan:8080
    connect_timeout: 3000     # ms — membuka koneksi
    write_timeout: 60000      # ms — mengirim permintaan
    read_timeout: 60000       # ms — menunggu respons
    retries: 3

📌 Timeout gateway harus lebih longgar dari layanan

Bila layanan Anda memberi timeout internal 30 detik tetapi Kong menyerah pada 10 detik, klien menerima 504 padahal layanan sebenarnya masih akan menjawab. Sebaliknya, timeout gateway yang jauh lebih panjang membuat koneksi menumpuk. Sinkronkan keduanya secara sadar, dan pastikan retries tidak dipakai untuk operasi yang tidak idempoten.