Belajar 9router - Configuration Management & Versioning

#Pendahuluan

Di episode 9 kalian mengatur gateway untuk banyak tenant sekaligus. Konfigurasi mulai banyak dan saling terkait — kalau dikelola asal-asalan, satu perubahan kecil bisa merusak routing semua pelanggan. Ini titik di mana konfigurasi harus diperlakukan seketat kode.

Episode 10 membahas configuration management dan versioning: mendeklarasikan route config sebagai kode yang masuk version control, memvalidasi perubahan sebelum diterapkan, menjalankan dry run dan diff, menyiapkan rollback yang aman, serta mengelola evolusi konfigurasi untuk agent workflow yang berumur panjang. Targetnya satu: mengubah routing tanpa rasa takut.

#Route Config sebagai Kode

Prinsip pertama: seluruh konfigurasi 9router hidup sebagai file deklaratif yang masuk version control — bukan diedit lewat dashboard. Dengan begitu setiap perubahan punya riwayat, penulis, dan alasan (commit message), serta bisa di-review seperti pull request.

apiVersion: 9router/v1
revision: 42
routes:
  - name: chat-primary
    match:
      intent: chat
    target: gpt-4o-mini
  - name: chat-enterprise
    match:
      tenant: acme-corp
      intent: chat
    target: gpt-4o

Simpan file di repo bersama aplikasi, misalnya di direktori config. Sekali masuk git, kalian mendapat semua keuntungan: blame untuk mencari siapa mengubah apa, history untuk memahami mengapa keputusan dibuat, dan review untuk menahan perubahan sebelum disetujui. Aturan rilis yang sama dengan deploy kode bisa diterapkan ke deploy config.

#Validasi Config Secara Lokal

Sebelum perubahan diterapkan, config harus lulus validasi. 9router menyediakan perintah validasi yang memeriksa struktur YAML, referensi route, model target, dan policy yang dipakai benar-benar ada. Validasi ini idealnya dijalankan di CI, tepat sebelum review dan merge.

npx @9router/cli validate 9router.yaml

Checking 9router.yaml ... ok
- routes: 14 defined, 0 orphan
- policies: 5 defined, all referenced
- models: 8 targets resolve
- warnings: 2 (route chat-legacy never matched)

Perhatikan output memperingatkan chat-legacy yang tidak pernah cocok dengan request apa pun. Validator yang bagus tidak cuma menolak config rusak, tapi juga menandai konfigurasi mati. Menghapus route yang tidak terpakai mengurangi beban kognitif dan permukaan kesalahan. Jalankan npx @9router/cli validate di setiap commit dan tolak merge bila ada error.

#Dry Run dan Diff

Meski config sudah valid secara struktur, validasi tidak menjamin perilaku yang diinginkan. Untuk itu ada dry run: simulasikan perubahan terhadap traffic nyata (atau kumpulan request contoh) dan lihat dampaknya sebelum deploy. Dry run menjawab "berapa persen traffic yang akan berubah arah?".

npx @9router/cli dry-run 9router.yaml --replay traffic.json

{
  "replayed": 10000,
  "route_changed": 321,
  "model_changed": 289,
  "policy_blocked_new": 12,
  "top_shifts": [
    { "from": "chat-primary", "to": "chat-enterprise", "count": 210 }
  ]
}

Pasangkan dengan diff untuk melihat perbandingan antar dua versi config secara eksplisit: npx @9router/cli diff 9router-v41.yaml 9router-v42.yaml menampilkan route dan policy yang ditambah, dihapus, atau diubah. Kombinasi dry run dan diff memberi gambaran lengkap: apa yang berubah secara struktural dan apa dampaknya secara perilaku.

#Rollback yang Aman

Terlepas dari semua validasi, perubahan bisa tetap bermasalah di produksi. Rollback yang aman butuh tiga hal: konfigurasi lama masih tersedia, proses untuk kembali cepat, dan dampak dibatasi. 9router menyimpan riwayat revisi yang di-deploy sehingga rollback cukup memilih revisi sebelumnya.

npx @9router/cli revisions list
npx @9router/cli rollback --to revision:41 --scope route:chat-primary

Dengan scope, kalian bisa memutar balik hanya satu route yang bermasalah alih-alih seluruh config. Ini meredam risiko: satu route yang gagal tidak memaksa semua tenant kembali ke versi lama. Catat setiap rollback di log dengan alasan, dan jadikan momen itu bahan pembelajaran — biasanya rollback terjadi karena kondisi yang tidak tercakup dry run.

#Evolusi Route untuk Agent Workflow Jangka Panjang

Agent workflow yang berjalan lama — ratusan ribu request dalam satu alur — menghadapi tantangan unik: route yang benar saat alur dimulai bisa salah saat alur berakhir. Versioning membantu, tapi butuh strategi agar evolusi tidak memutus alur yang sedang berjalan.

policies:
  - name: pin-agent-revision
    rules:
      - id: pin-revision
        type: constraint
        if:
          agent_flow: true
        then:
          pinned_revision: 41

Strateginya: alur agen "dipin" ke revisi config tertentu saat dimulai, sehingga keputusan routing selama alur konsisten. Versi baru config hanya berlaku untuk alur yang baru dimulai. Ini memisahkan dua kecepatan: alur lama selesai dengan aturan lamanya, alur baru menikmati aturan baru. Tambahkan mekanisme masa transisi — misalnya alur lama diberi tenggat untuk pindah ke revisi baru — supaya tidak ada yang terjebak di config usang selamanya.

#Penutup

Konfigurasi 9router layak diperlakukan sebagai artefak produksi: version control untuk riwayat, validasi lokal dan CI untuk mencegah error, dry run dan diff untuk memahami dampak, rollback berskala untuk pemulihan cepat, dan pinning revision untuk menjaga alur agen jangka panjang. Mengelola config dengan disiplin ini membuat perubahan routing menjadi aktivitas rutin yang tenang, bukan peristiwa berisiko.

Inti yang harus dibawa pulang:

• Route config harus deklaratif, masuk version control, dan di-review seperti kode.
• Validasi di CI menangkap error struktur; jalankan sebelum merge.
• Dry run dan diff menjawab dampak perilaku, bukan hanya struktur.
• Rollback berskala (per route) meminimalkan ledakan saat pemulihan.
• Pin revision untuk agent workflow panjang agar alur yang berjalan tidak berubah di tengah jalan.

Di episode 11 kita mengamankan fondasi itu semua: Secrets & Integration Security — penyimpanan API key dan credential provider secara aman, integrasi dengan toolchain eksternal yang aman, serta strategi rotation dan least privilege. Sampai jumpa!