Belajar GitOps - FluxCD - Troubleshooting & Debugging

#Pendahuluan

Di episode 31 kalian sudah menyusun adopsi enterprise dengan proses dan struktur organisasi yang matang. Namun tak peduli seberapa rapi konfigurasinya, di produksi masalah akan tetap muncul — dan yang membedakan engineer hebat adalah kecepatannya menemukan akar masalah. Di episode 32 ini kalian belajar troubleshooting & debugging FluxCD secara sistematis: dari masalah umum yang paling sering terjadi, hingga teknik investigasi memakai CLI dan observasi mendalam.

#Masalah Umum yang Sering Terjadi

#Kegagalan Rekonsiliasi

Saat Flux tidak bisa menarik atau menerapkan konfigurasi, semua Kustomization yang terpengaruh akan masuk status Not Ready. Mulailah dengan flux get kustomizations untuk melihat kondisi masing-masing objek.

#Source Tidak Tersedia

GitRepository yang gagal berarti Flux tidak bisa menarik dari Git. Penyebab umum: repositori tidak ada, cabang berubah, kredensial salah, atau rate limit GitHub/GitLab.

Note

Selalu cek pesan message pada status objek. Flux menuliskan alasan spesifik di sana — misalnya "repository not found" atau "authentication required".

#Health Check Gagal dan Autentikasi

Health check gagal terjadi ketika readiness probe belum pernah berubah menjadi sukses dalam batas waktu yang ditentukan di spec.healthChecks. Sementara error autentikasi dan RBAC biasanya muncul saat Flux mencoba membaca atau menulis resource yang tidak diizinkan oleh kebijakan RBAC cluster.

#Teknik Debugging Dasar

#flux logs

Cara tercepat melihat apa yang sedang dilakukan Flux adalah streaming log semua controller:

Streaming log semua controller Flux

flux logs --all-namespaces --since=10m

Tambahkan --level=error untuk hanya melihat kesalahan, atau arahkan ke controller tertentu dengan --kind=Kustomization.

#flux events

Karena kontainer restart menghapus log, Flux juga menulis kejadian ke cluster sebagai Kubernetes Event. Tampilkan dengan:

Melihat event yang dihasilkan Flux

flux events --all-namespaces --since=1h

Event adalah jejak yang bertahan lebih lama dari log — sangat berguna untuk masalah yang hanya muncul sesekali.

#flux trace

Untuk masalah yang melibatkan alur source ke kustomization, flux trace menunjukkan hubungan antara objek secara visual:

Menelusuri asal sebuah resource

flux trace apps Deployment shop

#kubectl describe dan Event Inspection

Kombinasikan dengan cara konvensional: kubectl describe kustomization shop -n apps untuk membaca kondisi terakhir, lalu kubectl get events -n apps --sort-by=.lastTimestamp untuk melihat urutan kejadian.

#Debugging dengan CLI Flux

#flux get all

Sekali lihat, semua resource Flux di namespace:

Ringkasan semua resource Flux

flux get all --all-namespaces

Ini memberi peta status keseluruhan — mulai dari source, kustomization, helm release, sampai image policy.

#flux reconcile dan suspend/resume

Untuk memicu rekonsiliasi segera tanpa menunggu interval:

Paksa rekonsiliasi dan ikuti prosesnya

flux reconcile source git flux-system --with-source
flux reconcile kustomization flux-system --with-source

Bila ada perubahan yang mengunci rekonsiliasi berturut-turut, hentikan sementara dengan flux suspend kustomization shop, perbaiki, lalu lanjutkan dengan flux resume kustomization shop.

Caution

suspend menghentikan rekonsiliasi tanpa menghapus resource yang sudah ada. Pastikan Anda mencatat objek mana yang di-suspend, karena mudah terlupakan dan membuat environment tidak ter-update.

#flux export

Mengekspor sumber daya dalam bentuk YAML berguna untuk memeriksa status yang tersimpan di cluster:

Ekspor objek Flux ke YAML

flux export gitrepository shop

#Debugging Lanjutan

#Analisis Log Controller

Ketika pesan di status tidak cukup, telusuri log controller secara langsung:

Log controller tertentu dengan filter

kubectl logs -n flux-system deploy/source-controller \
  --follow --tail=200

#Inspeksi Metrics

Controller Flux mengekspos metrik Prometheus, termasuk gotk_reconcile_condition dan gotk_reconcile_duration. Nilai False pada gotk_reconcile_condition menandakan masalah yang perlu diinvestigasi:

Contoh hasil query Prometheus

{
  "metric": {
    "__name__": "gotk_reconcile_condition",
    "kind": "Kustomization",
    "name": "flux-system",
    "status": "False"
  },
  "value": [1722657600, "1"]
}

#Debugging Network dan Git

Masalah jaringan sering muncul sebagai error timeout atau TLS. Gunakan kubectl exec ke pod controller dan coba git ls-remote langsung untuk mengisolasi apakah masalah di koneksi atau di kredensial:

Tes koneksi git dari dalam pod

kubectl exec -n flux-system deploy/source-controller -- \
  git ls-remote https://github.com/devvnull/fleet.git

Tip

Buat urutan investigasi yang tetap: cek flux get all, lalu event, lalu log. Urutan ini mencegah Anda melompat langsung ke asumsi yang salah.

#Penutup

Di episode ini kalian belajar troubleshooting FluxCD secara sistematis: mengenali lima masalah umum, membaca log dan event, menggunakan flux trace, memanfaatkan flux reconcile dan suspend/resume, serta mendalami log controller dan metrik.

Inti yang harus dibawa pulang:

Status dulu, asumsi belakangan: baca kondisi objek dan event sebelum menyimpulkan penyebab.
Log adalah narasi sementara, event adalah catatan: gunakan flux events untuk masalah yang jarang muncul.
Kuasai CLI: flux get all, flux reconcile, dan flux suspend/resume menangani sebagian besar perbaikan.
Isolasi lapisan: pisahkan masalah Git, jaringan, dan RBAC dengan menguji satu per satu.
Ekspor untuk analisis: flux export dan metrik Prometheus mempercepat diagnosis.

Di episode 33, kita membahas perjalanan yang tak kalah menantang: migration strategies — berpindah dari deployment manual, Helm 2, tool GitOps lain, dan khususnya migrasi dari Flux v1 ke v2 serta dari ArgoCD ke Flux. Sampai jumpa!