Runbook deploy aman untuk Hermes Agent iOS self-hosted harus dirancang untuk satu tujuan utama: jangan sampai aplikasi iPhone kehilangan konektivitas saat backend baru dirilis. Dalam konteks agent self-hosted seperti hermex, masalah paling mahal biasanya bukan proses build server, tetapi perubahan kecil pada endpoint, TLS, auth, atau schema yang membuat client mobile gagal handshake, timeout, atau menerima respons yang tidak kompatibel.

Artikel ini fokus pada sisi operasional server: bagaimana merilis perubahan secara bertahap, memverifikasi health sebelum cutover, menyiapkan rollback cepat, memasang observability minimum yang benar-benar berguna, dan membuat runbook yang bisa dijalankan saat insiden terjadi. Tujuannya bukan membuat sistem sempurna, tetapi membuat deploy menjadi predictable, mudah diaudit, dan cepat dipulihkan.

Prinsip dasar deployment aman untuk backend mobile

Backend yang dipakai aplikasi iOS berbeda dari backend internal biasa karena client tidak selalu bisa diperbarui cepat. Saat server berubah, banyak pengguna masih menjalankan versi aplikasi lama, memakai jaringan seluler tidak stabil, dan membuka koneksi dari berbagai zona waktu. Karena itu, deploy untuk Hermes Agent iOS self-hosted sebaiknya mengikuti prinsip berikut:

  • Backward-compatible lebih dulu. Tambahkan field baru, jangan langsung menghapus field lama atau mengubah format respons tanpa masa transisi.
  • Cutover kecil dan terukur. Jangan mengganti binary, konfigurasi, migrasi schema, dan endpoint publik dalam satu langkah tanpa isolasi risiko.
  • Observability sebelum deploy. Jika log, metric, dan health endpoint belum siap, rollback akan lambat karena tim tidak tahu gejala awalnya.
  • Rollback harus lebih mudah daripada deploy. Jika rollback butuh migrasi manual atau edit config darurat, prosesnya terlalu rapuh.
  • Gunakan kontrol lalu lintas. Feature flag, canary, atau routing berbasis subset traffic membantu mendeteksi masalah sebelum semua pengguna terdampak.

Arsitektur rilis yang aman

Pisahkan komponen yang berubah

Untuk agent self-hosted, perubahan biasanya menyentuh beberapa area:

  • binary atau container aplikasi server,
  • reverse proxy atau load balancer,
  • sertifikat TLS dan domain,
  • database schema,
  • credential ke upstream service,
  • konfigurasi rate limit, timeout, atau auth.

Kesalahan umum adalah merilis semuanya sekaligus. Praktik yang lebih aman adalah memisahkan perubahan menjadi beberapa tahap:

  1. deploy kode yang kompatibel dengan schema lama dan baru,
  2. jalankan migrasi schema yang aman,
  3. aktifkan feature flag secara terbatas,
  4. geser traffic secara bertahap,
  5. bersihkan kode lama setelah masa observasi stabil.

Pilih strategi deploy: rolling, blue-green, atau canary

Tidak semua tim butuh sistem kompleks, tetapi pemilihan strategi rilis memengaruhi kemampuan rollback.

  • Rolling deploy: sederhana dan umum dipakai. Cocok jika aplikasi stateless dan ada lebih dari satu instance. Risiko utamanya adalah campuran versi lama dan baru harus tetap kompatibel.
  • Blue-green deploy: dua environment aktif, lalu traffic dipindah saat siap. Sangat baik untuk rollback cepat karena cukup mengembalikan routing ke environment lama. Biayanya lebih tinggi.
  • Canary deploy: hanya sebagian kecil traffic masuk ke versi baru. Ini ideal jika tim ingin memvalidasi konektivitas mobile dengan risiko kecil.

Untuk Hermes Agent iOS self-hosted, kombinasi blue-green untuk cutover dan canary untuk validasi awal biasanya paling aman jika infrastruktur mendukungnya. Jika tidak, rolling deploy masih layak selama health check dan rollback benar-benar disiplin.

Checklist pra-deploy

Sebelum menekan tombol deploy, pastikan checklist ini selesai. Jangan andalkan ingatan individu.

Checklist perubahan aplikasi dan API

  • Semua perubahan endpoint yang dipakai client iOS sudah ditinjau untuk kompatibilitas ke belakang.
  • Tidak ada field JSON lama yang dihapus tanpa masa transisi.
  • Perubahan auth header, token, atau signature telah diuji dengan client yang ada.
  • Timeout server tidak dipersempit tanpa analisis latensi aktual.
  • Jika ada perubahan ukuran payload, sudah dievaluasi dampaknya ke jaringan seluler.

Checklist konfigurasi dan infrastruktur

  • Variabel lingkungan sudah lengkap dan tervalidasi.
  • Secret baru tersedia di environment target sebelum instance baru aktif.
  • Domain, DNS, dan sertifikat TLS valid dan belum mendekati kedaluwarsa.
  • Health endpoint dapat diakses dari jaringan internal dan, jika perlu, dari jalur yang menyerupai client publik.
  • Rate limit, WAF, atau ACL tidak akan memblokir pola request dari aplikasi iPhone.

Checklist migrasi schema

  • Migrasi bersifat expand first: tambah tabel, kolom, atau indeks dulu; jangan langsung hapus struktur lama.
  • Migrasi yang berpotensi lama sudah diuji pada data realistis.
  • Query baru tetap bekerja walau sebagian instance masih memakai kode lama.
  • Ada rencana rollback schema atau minimal strategi roll-forward yang aman jika migrasi tidak bisa dibalik.

Checklist observability minimum

  • Log terstruktur aktif.
  • Metrik request total, error rate, dan latency per endpoint tersedia.
  • Health endpoint menguji komponen penting, bukan hanya mengembalikan 200 statis.
  • Dashboard deploy sudah menampilkan baseline sebelum rilis.
  • Alert untuk lonjakan 5xx, timeout, dan penurunan success rate aktif.

Health check sebelum cutover

Health check yang baik harus menjawab satu pertanyaan: apakah versi baru benar-benar siap melayani client mobile? Jawaban ini tidak cukup dengan endpoint /health yang selalu mengembalikan 200.

Bedakan liveness dan readiness

  • Liveness memeriksa apakah proses masih hidup.
  • Readiness memeriksa apakah instance siap menerima traffic nyata.

Untuk backend Hermes Agent, readiness check idealnya memverifikasi:

  • koneksi database aktif,
  • akses ke cache atau queue bila dipakai dalam jalur request,
  • validasi secret atau credential penting telah dimuat,
  • konektivitas ke upstream yang wajib untuk handshake atau proxy request,
  • versi aplikasi dan commit saat ini diekspos untuk audit deploy.

Contoh respons endpoint readiness

GET /readyz

{
  "status": "ok",
  "version": "git-sha-or-release-id",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "upstream": "ok"
  }
}

Jika salah satu dependency kritis gagal, lebih baik readiness gagal dan instance tidak menerima traffic, daripada terlihat hidup tetapi mengembalikan error ke client iOS.

Verifikasi jalur koneksi seperti client mobile

Sebelum cutover penuh, lakukan uji dari luar cluster atau luar host. Fokusnya bukan sekadar curl localhost, tetapi jalur yang menyerupai pengguna asli:

  1. resolve domain publik,
  2. negosiasi TLS berhasil,
  3. request ke endpoint utama menerima status code yang benar,
  4. header auth yang diperlukan diterima,
  5. latency masih dalam batas normal.

Contoh verifikasi dasar:

curl -i https://agent.example.com/healthz
curl -i https://agent.example.com/readyz
curl -i --connect-timeout 5 https://agent.example.com/api/ping

Jika ada autentikasi atau signature, siapkan skrip probe internal yang meniru request minimal dari client. Ini lebih berguna daripada ping generik karena banyak kegagalan justru muncul setelah layer auth atau routing aplikasi.

Strategi deployment bertahap

Tahap 1: deploy pasif tanpa menerima semua traffic

Deploy versi baru ke environment target, tetapi jangan langsung arahkan seluruh traffic. Pada tahap ini lakukan:

  • validasi startup log,
  • cek readiness,
  • jalankan smoke test endpoint penting,
  • pastikan metric mulai terkumpul.

Tahap 2: canary ke subset traffic

Geser sebagian kecil traffic ke versi baru. Persentasenya tidak harus besar; yang penting cukup untuk melihat pola error nyata. Pantau minimal 10-15 menit atau sesuai pola traffic aplikasi. Sinyal yang harus dipantau:

  • kenaikan error rate 4xx/5xx,
  • lonjakan latency p95 atau p99,
  • timeout koneksi upstream,
  • penurunan request sukses untuk endpoint yang dipakai mobile saat startup atau sync,
  • log error baru yang sebelumnya tidak muncul.

Tahap 3: cutover bertahap

Jika canary stabil, naikkan traffic secara bertahap. Hindari perpindahan 0% ke 100% dalam satu langkah kecuali benar-benar memakai blue-green yang sudah diuji. Pada setiap tahap, cocokkan angka baru dengan baseline sebelum deploy.

Tahap 4: verifikasi pasca-cutover

Setelah semua traffic berpindah, jangan langsung menganggap deploy selesai. Lakukan verifikasi fungsional dari sudut pandang aplikasi iPhone:

  • aplikasi bisa login atau menginisialisasi sesi,
  • permintaan sinkronisasi data berhasil,
  • request berulang tidak terkena rate limit tak terduga,
  • background retry tidak menghasilkan banjir error,
  • server tidak mengembalikan payload yang melanggar kontrak lama.

Rollback cepat saat mobile client gagal terhubung

Pada sistem yang dipakai aplikasi mobile, rollback harus dioptimalkan untuk pemulihan layanan tercepat, bukan untuk elegansi proses. Jika client iPhone gagal terhubung setelah rilis, tim butuh prosedur sederhana yang bisa dijalankan dalam hitungan menit.

Kapan rollback lebih baik daripada memperbaiki langsung

Lakukan rollback segera jika salah satu kondisi ini terjadi:

  • success rate endpoint inti turun tajam setelah deploy,
  • health endpoint readiness mulai gagal di banyak instance,
  • latency melonjak dan menyebabkan timeout di client,
  • auth atau TLS gagal pada jalur request utama,
  • penyebab belum jelas dan dampak ke pengguna sedang berlangsung.

Jangan terjebak mencoba debug panjang di production bila versi lama sebenarnya masih bisa dipulihkan cepat.

Urutan rollback yang disarankan

  1. Hentikan perluasan traffic ke versi baru.
  2. Alihkan traffic kembali ke pool atau environment versi lama.
  3. Nonaktifkan feature flag yang baru diaktifkan.
  4. Konfirmasi recovery melalui dashboard, log, dan probe eksternal.
  5. Bekukan deploy lanjutan sampai akar masalah dipahami.

Catatan penting soal migrasi database

Rollback aplikasi lebih mudah daripada rollback schema. Karena itu, desain migrasi harus menganggap kemungkinan aplikasi kembali ke versi lama. Praktik aman:

  • jangan membuat kode baru langsung bergantung pada kolom yang belum pasti ada di semua environment,
  • hindari migrasi destruktif di langkah yang sama dengan deploy aplikasi,
  • pisahkan expand, migrate, dan contract menjadi fase berbeda.

Observability minimum yang wajib ada

Tanpa observability, deploy aman hanya bergantung pada firasat. Untuk backend Hermes Agent iOS self-hosted, minimal pasang empat lapisan sinyal.

1. Log terstruktur

Gunakan log JSON atau format terstruktur lain agar mudah difilter. Setiap request idealnya punya field berikut:

  • timestamp,
  • request_id atau trace_id,
  • method dan path,
  • status_code,
  • duration_ms,
  • upstream_status bila ada proxy ke service lain,
  • client identifier yang aman bila tersedia, tanpa membocorkan data sensitif.

Contoh log:

{
  "level": "error",
  "msg": "upstream timeout",
  "request_id": "a1b2c3",
  "path": "/api/session",
  "status_code": 504,
  "duration_ms": 5021
}

Hindari log yang hanya berbentuk string bebas karena sulit dipakai saat insiden.

2. Metrik latency

Pantau latency per endpoint penting, setidaknya p50, p95, dan p99 jika sistem metric mendukung. Rata-rata saja sering menyesatkan. Pada aplikasi mobile, ekor distribusi latensi penting karena timeout biasanya dipicu oleh request lambat yang tidak dominan secara jumlah.

3. Error rate

Pisahkan error berdasarkan kelas:

  • 4xx: sering menandakan perubahan auth, validasi, atau kontrak request.
  • 5xx: biasanya menunjukkan bug server, dependency gagal, atau overload.
  • timeout: perlu dilihat terpisah dari 5xx karena bisa terjadi di proxy, upstream, atau jaringan.

4. Endpoint health

Sediakan setidaknya:

  • /livez untuk liveness,
  • /readyz untuk readiness,
  • bila perlu, endpoint internal untuk diagnostik dependency.

Health endpoint tidak boleh membocorkan secret, detail sensitif, atau data internal yang tidak perlu. Cukup tampilkan status komponen yang relevan untuk operasi.

Contoh sinyal insiden setelah rilis

Berikut beberapa gejala yang sering muncul setelah deploy backend mobile, beserta interpretasi awalnya.

Gejala 1: 200 OK tetap tinggi, tetapi user mengeluh aplikasi macet di loading

Kemungkinan penyebab:

  • endpoint health baik, tetapi endpoint bisnis utama gagal,
  • respons valid secara HTTP namun format JSON berubah,
  • latency endpoint startup naik dan memicu timeout di sisi iOS.

Apa yang dicek:

  • success rate endpoint yang dipanggil saat aplikasi dibuka,
  • ukuran payload dan perubahan field respons,
  • log parsing atau validation error bila server mencatatnya.

Gejala 2: Lonjakan 401 atau 403 sesaat setelah cutover

Kemungkinan penyebab:

  • secret atau public key berbeda antar environment,
  • header auth dibaca berbeda oleh proxy baru,
  • clock skew memengaruhi verifikasi token bertanda waktu.

Apa yang dicek:

  • sinkronisasi secret dan konfigurasi auth,
  • header forwarding di reverse proxy,
  • waktu sistem pada host baru.

Gejala 3: Banyak 502/504 hanya pada versi baru

Kemungkinan penyebab:

  • upstream dependency tidak dapat dijangkau dari subnet baru,
  • timeout proxy lebih pendek daripada waktu respons upstream,
  • DNS internal pada environment baru salah atau belum siap.

Apa yang dicek:

  • konektivitas egress dari instance baru,
  • timeout antar lapisan,
  • resolusi DNS dan routing jaringan.

Runbook verifikasi konektivitas mobile

Runbook ini dirancang untuk dijalankan cepat setelah deploy atau saat ada laporan aplikasi iPhone tidak bisa terhubung.

Langkah verifikasi cepat

  1. Cek dashboard rilis: lihat error rate, latency, dan readiness sejak waktu deploy.
  2. Uji endpoint publik: pastikan DNS, TLS, dan status code dasar normal.
  3. Uji endpoint yang benar-benar dipakai client: bukan hanya health endpoint.
  4. Bandingkan versi lama vs baru: jika canary aktif, bandingkan metrik per pool.
  5. Periksa log error terstruktur: filter berdasarkan path inti, status code, dan request_id.
  6. Validasi dependency: database, cache, upstream API, secret, dan jaringan keluar.
  7. Putuskan rollback atau lanjut investigasi berdasarkan dampak dan kejelasan akar masalah.

Checklist konektivitas yang harus lolos

  • Domain publik merespons dari jaringan luar.
  • Sertifikat TLS valid dan rantai sertifikat lengkap.
  • Endpoint readiness lulus di semua instance aktif.
  • Endpoint inti seperti init session, auth, sync, atau ping bisnis memberi respons sesuai kontrak.
  • Header penting tidak hilang setelah melewati proxy.
  • Latency tidak melonjak jauh dari baseline.
  • Error 4xx/5xx tidak naik signifikan dibanding sebelum deploy.

Sinyal yang harus dipantau selama 30 menit pertama

  • success rate request utama,
  • latency p95 dan p99,
  • jumlah timeout,
  • proporsi 401/403,
  • readiness failure per instance,
  • restart process atau container,
  • error dependency seperti database connection refused atau upstream timeout.

Feature flag dan canary sebagai pencegahan

Feature flag bukan hanya untuk tim produk. Dalam operasi backend mobile, feature flag membantu mengurangi radius dampak. Misalnya:

  • mengaktifkan jalur request baru hanya untuk subset tenant atau user internal,
  • menonaktifkan integrasi upstream baru tanpa redeploy,
  • mengembalikan perilaku lama saat parsing atau auth baru bermasalah.

Canary melengkapi feature flag dengan kontrol trafik di level infrastruktur. Pilih canary jika:

  • perubahan menyentuh jaringan, proxy, atau timeout,
  • ada risiko incompatibility yang sulit disimulasikan penuh di staging,
  • tim ingin membatasi dampak sambil melihat trafik nyata.

Namun ada trade-off: canary menambah kompleksitas observasi karena metrik harus bisa dipisahkan per versi atau per pool. Jika pemisahan sinyal belum ada, tim bisa salah membaca dampak rilis.

Postmortem ringan setelah insiden

Setelah rollback atau insiden stabil, lakukan postmortem singkat yang fokus pada pembelajaran, bukan mencari kambing hitam. Format sederhana sudah cukup jika konsisten.

Struktur postmortem

  • Ringkasan insiden: apa yang terjadi dan siapa yang terdampak.
  • Timeline: waktu deploy, deteksi, mitigasi, rollback, dan pemulihan.
  • Dampak: endpoint yang gagal, gejala pada pengguna, durasi gangguan.
  • Akar masalah teknis: misalnya mismatch config auth, readiness terlalu dangkal, atau migrasi tidak kompatibel.
  • Yang berjalan baik: misalnya rollback cepat atau alert berhasil memicu respons cepat.
  • Yang perlu diperbaiki: checklist, test, monitoring, atau proses approval.
  • Tindakan pencegahan: pemilik tugas dan target waktu.

Contoh tindakan pencegahan yang bernilai tinggi

  • tambahkan smoke test untuk endpoint mobile utama,
  • perketat readiness check agar menguji dependency kritis,
  • buat template rollback yang bisa dijalankan satu perintah atau satu perubahan routing,
  • wajibkan canary untuk perubahan auth, TLS, atau proxy,
  • buat checklist migrasi schema yang ditinjau sebelum merge.

Template runbook deploy aman

Bagian ini bisa langsung diadaptasi ke dokumen operasi tim.

Sebelum deploy

  • Pastikan dashboard baseline tersedia.
  • Pastikan change log menyebut endpoint dan dependency yang berubah.
  • Validasi config, secret, sertifikat, dan health endpoint.
  • Konfirmasi migrasi schema aman untuk coexistence versi lama dan baru.
  • Tentukan kriteria rollback sebelum deploy dimulai.

Saat deploy

  • Deploy ke environment target tanpa full traffic.
  • Jalankan readiness dan smoke test.
  • Aktifkan canary atau alihkan sebagian kecil traffic.
  • Pantau error rate, latency, dan timeout.
  • Jika stabil, tingkatkan traffic bertahap.

Setelah deploy

  • Verifikasi konektivitas dari jalur publik.
  • Uji endpoint inti yang dipakai aplikasi iPhone.
  • Pastikan tidak ada lonjakan 401, 5xx, atau readiness failure.
  • Catat release id, waktu cutover, dan hasil verifikasi.
  • Lanjutkan observasi selama periode pasca-rilis.

Jika insiden terjadi

  • Bekukan ekspansi traffic.
  • Rollback routing atau versi aplikasi server.
  • Nonaktifkan feature flag terkait.
  • Konfirmasi pemulihan dengan probe eksternal dan dashboard.
  • Buka postmortem ringan dan dokumentasikan temuan.

Penutup

Runbook deploy aman untuk Hermes Agent iOS self-hosted tidak harus rumit, tetapi harus tegas pada titik-titik yang sering gagal: kompatibilitas API, health check yang benar, observability minimum, rollout bertahap, dan rollback yang cepat. Jika tim hanya mengambil satu pelajaran, ambillah ini: deploy backend mobile harus dirancang dengan asumsi bahwa client lama masih ada dan tidak bisa diperbaiki seketika. Karena itu, pencegahan terbaik adalah rilis kecil, sinyal yang jelas, dan prosedur pemulihan yang bisa dijalankan tanpa improvisasi panjang.