Belajar GitOps dengan ArgoCD - Resource Hooks & Lifecycle

#Pendahuluan

Di episode 12 sebelumnya kita mengamankan secret agar bisa hidup di GitOps. Tapi ada pertanyaan yang menggantung sejak awal seri: bagaimana menjalankan aksi tambahan di sekitar proses sync? Aplikasi yang melakukan migrasi database sebelum rilis, smoke test setelah deploy, atau backup sebelum perubahan besar — semua itu butuh eksekusi terkoordinasi, bukan sekadar "apply manifest". Pada episode ini kita membahas Resource Hooks: mekanisme ArgoCD untuk menjalankan job di titik-titik tertentu dari siklus hidup sync.

Mengapa ini penting? Deployment yang baik bukan hanya menaruh gambar yang benar, tapi juga menangani efek sampingnya: skema database, verifikasi kesehatan, pemberitahuan, hingga pemulihan saat gagal. Hooks adalah cara ArgoCD menyuntikkan logika tersebut tanpa meninggalkan paradigma GitOps — semua hook hidup di Git sebagai manifest biasa.

#Anatomi Sync: Fase-Fase

Setiap sync ArgoCD berjalan dalam lima fase berurutan:

Hook adalah resource (biasanya Job) yang ditandai dengan annotation khusus. ArgoCD menjalankannya di fase yang sesuai, dan sync hanya lanjut ke fase berikutnya jika semua hook pada fase tersebut sukses.

#Hook Berbasis Job

Cara paling umum membuat hook adalah Kubernetes Job dengan annotation hook:

hook-db-migrate.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  namespace: billing-prod
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: ghcr.io/devnull/billing-api:1.2.0
          command: ["bundle", "exec", "rails", "db:migrate"]

Saat sync dimulai, ArgoCD melihat annotation argocd.argoproj.io/hook: PreSync dan menjalankan job ini sebelum me-deploy resource utama. Jika job selesai dengan exit code 0, sync berlanjut; jika gagal, sync dihentikan di fase PreSync.

#Hook Deletion Policy

Karena hook hanya dibutuhkan saat sync, ArgoCD perlu tahu kapan harus membersihkannya. Annotation argocd.argoproj.io/hook-delete-policy mengatur ini:

Kombinasi dipisah koma, misal HookSucceeded, HookFailed — hook dibersihkan apa pun hasilnya.

#Use Case Umum

#Migrasi Database (PreSync)

Pola paling klasik: jalankan migrasi sebelum Deployment baru naik, sehingga schema dan aplikasi berubah dalam satu operasi atomik. Job db-migrate di atas adalah contohnya.

#Backup Sebelum Sync (PreSync)

Untuk perubahan berisiko, jalankan hook PreSync yang mem-backup database atau volume ke penyimpanan terpisah — jadi ada jaring pengaman sebelum manifest baru diterapkan.

#Smoke Test (PostSync)

Setelah deploy selesai, jalankan hook PostSync yang memanggil endpoint aplikasi dan memverifikasi respons — misalnya mengecek GET /health mengembalikan 200:

hook-smoke-test.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: smoke-test
  namespace: billing-prod
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: check
          image: curlimages/curl:latest
          command: ["curl", "-f", "https://api.billing.example.com/health"]

#Notifikasi (PostSync / SyncFail)

Hook bisa menjadi ujung tombak alerting sederhana — misalnya hook SyncFail yang mengirim pesan ke chat, meskipun untuk kebutuhan ini notifikasi ArgoCD (episode 17) biasanya lebih rapi.

#Rollback (SyncFail)

Jika sync gagal, hook SyncFail bisa mengeksekusi aksi pemulihan — misalnya menonaktifkan traffic, atau menjalankan skrip rollback dari image versi sebelumnya.

#Urutan Eksekusi: Sync Waves

Hook (dan semua resource) bisa diberi annotation argocd.argoproj.io/sync-wave untuk mengatur urutan eksekusi:

Wave pada hook dan resource

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "1"

Aturannya: resource dengan wave lebih kecil dijalankan lebih dulu; resource dengan wave sama dijalankan berurutan untuk hooks dan boleh paralel untuk resource sync biasa. Contoh nyata: migrasi DB (wave -1) sebelum Deployment (wave 0), lalu smoke test (wave 2). Urutan di dalam satu wave untuk hooks mengikuti urutan di manifest.

#Debugging & Logging Hook

Ketika hook gagal, cek status dan log-nya:

argocd app get billing --show-operation
kubectl get jobs -n billing-prod -l app.kubernetes.io/part-of=billing
kubectl logs job/db-migrate -n billing-prod --tail=100
kubectl describe job/db-migrate -n billing-prod

argocd app get billing --show-operation menampilkan hasil tiap fase hook; jika sebuah hook tertahan, kubectl describe job biasanya langsung menunjukkan penyebabnya (image tidak ada, restart, permission). Jika hook meninggalkan Job lama karena policy yang salah, bersihkan manual dengan kubectl delete job --all -n billing-prod.

#Kesalahan Umum (Common Pitfalls)

1. Hook gagal tanpa kebijakan pembersihan. Tanpa hook-delete-policy, Job dan Pod-nya menumpuk di namespace. Selalu tetapkan policy.
2. Migrasi berjalan ganda. Tanpa BeforeHookCreation, job migrasi dari sync sebelumnya bisa jalan lagi dan gagal. Kombinasikan dengan policy yang tepat.
3. Smoke test yang tergantung DNS. Hook PostSync sering gagal karena aplikasi belum siap menerima traffic. Tambahkan retry di dalam container atau atur wave.
4. Memakai hook untuk tugas yang bukan "one-shot". Hooks cocok untuk job sekali jalan. Untuk proses berkelanjutan, gunakan resource biasa.
5. Melupakan permission job. Job yang butuh akses ke API cluster (misal kubectl di dalam hook) harus punya ServiceAccount dan RBAC sendiri.

#Penutup

Episode ini melengkapi pemahaman siklus hidup sync: lima fase (PreSync, Sync, PostSync, SyncFail, Skip), implementasi hook berbasis Job dengan annotation argocd.argoproj.io/hook, kebijakan penghapusan hook, use case migrasi DB, smoke test, backup, notifikasi, dan rollback, pengaturan urutan dengan sync wave, serta cara debugging saat hook bermasalah.

Poin yang harus kalian bawa:

• Hook adalah Job bertanda annotation yang berjalan pada fase tertentu dari sync.
• argocd.argoproj.io/hook-delete-policy mencegah Job menumpuk.
• Migrasi DB di PreSync dan smoke test di PostSync adalah dua pola paling umum.
• Sync wave mengatur urutan eksekusi; gunakan angka negatif untuk tugas paling awal.
• Log hook bisa dilihat lewat argocd app get --show-operation dan kubectl logs.

Ada kalanya kita tidak ingin sync terjadi — misalnya jam maintenance atau masa freeze rilis. Di episode 14 selanjutnya kita membahas Sync Windows & Scheduling: window allow/deny berbasis cron, maintenance window, change freeze, dan override manual untuk emergency deployment. Sampai jumpa di episode 14!