decK: Konfigurasi sebagai Kode — Belajar Kong API Gateway

📌 Masalah Konfigurasi Manual

Mengubah Kong lewat Admin API secara langsung terasa cepat, tetapi menimbulkan masalah yang sama seperti mengubah server produksi lewat SSH: tidak ada catatan siapa mengubah apa, lingkungan staging dan produksi perlahan menyimpang, dan memulihkan keadaan setelah insiden berarti mengingat-ingat.

💡 decK menutup celah itu

Konfigurasi menjadi berkas YAML di Git. Setiap perubahan melewati pull request, terlihat sebagai diff, dan bisa diterapkan ulang secara identik ke lingkungan mana pun.

💻 Perintah Inti

# Mengambil konfigurasi yang SEDANG berjalan ke berkas
deck gateway dump -o kong.yaml

# Melihat apa yang AKAN berubah — jalankan ini sebelum apa pun
deck gateway diff -s kong.yaml

# Menerapkan
deck gateway sync -s kong.yaml

# Memeriksa keabsahan berkas tanpa menyentuh Kong
deck file validate kong.yaml

# Menggabungkan beberapa berkas menjadi satu
deck file merge tim-a.yaml tim-b.yaml -o gabungan.yaml

🚫 sync menghapus apa pun yang tidak ada di berkas

decK memaksa keadaan Kong menjadi persis seperti isi berkas. Objek yang ada di Kong tetapi tidak tercantum di YAML akan dihapus. Menjalankan sync dengan berkas parsial dapat menghapus konfigurasi tim lain dalam sekejap.

Selalu jalankan diff lebih dulu dan baca keluarannya. Untuk lingkungan yang dipakai bersama, gunakan tag seperti dijelaskan di bawah.

🏷️ Tag: Membagi Kepemilikan

tim-pesanan.yaml

_format_version: "3.0"

services:
  - name: layanan-pesanan
    url: http://layanan-pesanan:8080
    tags: ["tim-pesanan"]
    routes:
      - name: rute-pesanan
        paths: ["/pesanan"]
        tags: ["tim-pesanan"]

# Hanya menyentuh objek bertag tim-pesanan.
# Konfigurasi tim lain aman.
deck gateway sync -s tim-pesanan.yaml --select-tag tim-pesanan

🔐 Menangani Rahasia

# ❌ Rahasia langsung di berkas yang masuk Git
plugins:
  - name: key-auth
    config:
      key_names: ["apikey"]
consumers:
  - username: mitra-a
    keyauth_credentials:
      - key: "rahasia-asli-jangan-begini"

# ✅ Referensi ke variabel lingkungan
      - key: "${MITRA_A_KEY}"

# Terapkan dengan nilai dari lingkungan
MITRA_A_KEY=$(vault kv get -field=key rahasia/mitra-a) \
  deck gateway sync -s kong.yaml

⚠️ Kredensial konsumen sering lolos ke Git

Perintah deck gateway dump mengambil segalanya termasuk kunci API dan rahasia JWT konsumen. Menjalankan dump lalu langsung commit adalah cara paling umum kredensial produksi bocor ke repositori. Selalu periksa hasil dump sebelum commit, atau kecualikan entitas kredensial dengan --skip-consumers.

🔁 Di dalam Pipeline CI/CD

.github/workflows/kong.yml

name: Terapkan konfigurasi Kong

on:
  pull_request:
    paths: ["kong/**"]
  push:
    branches: [main]
    paths: ["kong/**"]

jobs:
  periksa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Validasi berkas
        run: deck file validate kong/kong.yaml
      - name: Tampilkan diff terhadap staging
        run: deck gateway diff -s kong/kong.yaml
        env:
          DECK_KONG_ADDR: ${{ secrets.KONG_ADMIN_STAGING }}

  terapkan:
    if: github.ref == 'refs/heads/main'
    needs: periksa
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Sinkronkan ke produksi
        run: deck gateway sync -s kong/kong.yaml
        env:
          DECK_KONG_ADDR: ${{ secrets.KONG_ADMIN_PROD }}

📌 Tampilkan diff di pull request

Menjalankan deck gateway diff pada tiap PR dan menempelkan hasilnya sebagai komentar membuat peninjau melihat persis apa yang akan berubah di gateway — bukan sekadar membaca perubahan YAML. Ini menangkap kesalahan seperti Route yang tanpa sadar terhapus atau plugin auth yang hilang.