KAL
Menu

Perkakas Debugging kubectl

Perkakas debugging inti kubectl: describe, logs, exec, port-forward, dan pembacaan event.

Daftar isi

Topik ini memperkenalkan perintah kubectl yang digunakan sehari-hari untuk debugging, yaitu penelusuran penyebab perilaku tidak normal pada aplikasi yang berjalan di kluster. Lingkupnya meliputi kubectl describe, kubectl logs, kubectl exec, dan kubectl port-forward, ditambah disiplin membaca event dari API server. Setelah membacanya, gejala seperti Pod yang berulang kali restart atau image yang gagal ditarik dapat dipetakan ke perintah pemeriksaan yang tepat.

Menilai kondisi dengan kubectl describe#

Perintah kubectl describe membaca status satu objek dari API server dan menampilkannya sebagai ringkasan teks. Untuk sebuah Pod, keluarannya memuat fase, kondisi tiap container, jumlah restart, konfigurasi probe, serta volume yang terpasang. Bagian paling bernilai justru berada di paling bawah, yaitu daftar event yang merekam keputusan scheduler, penarikan image, dan pesan error dari kubelet beserta waktunya. Susunan tersebut membuat penyebab umum kegagalan terbaca dari satu perintah tanpa membaca manifest terlebih dahulu.

bash 
# tidak-dijalankan
# menampilkan detail Pod beserta daftar event di bagian bawah keluarannya
kubectl describe pod catatan-api-7d9c4b6d5f-xk2qz -n aplikasi-catatan
text Contoh keluaran 
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  2m1s  default-scheduler  Successfully assigned aplikasi-catatan/catatan-api-7d9c4b6d5f-xk2qz to node-02
  Warning  BackOff    45s   kubelet            Back-off restarting failed container catatan-api in pod catatan-api-7d9c4b6d5f-xk2qz_aplikasi-catatan(f0e1c9a4)

Apabila ringkasan describe masih belum cukup rinci, keluaran dapat dipersempit ke bidang yang benar-benar diperlukan. Flag -o wide pada kubectl get menambahkan kolom Node dan IP Pod, sedangkan -o jsonpath mengekstrak satu bidang dari objek, misalnya {.status.podIP} yang hanya menampilkan alamat IP. Kedua bentuk keluaran ini mengurangi tebakan karena nilai yang dibaca persis seperti yang disimpan API server.

bash 
# tidak-dijalankan
# menampilkan kolom tambahan Node dan IP pada daftar Pod
kubectl get pods -n aplikasi-catatan -o wide
text Contoh keluaran 
NAME                          READY   STATUS    RESTARTS   AGE   IP           NODE
catatan-api-7d9c4b6d5f-xk2qz  1/1     Running   0          5m    10.244.1.17  node-02

Membaca log container dengan kubectl logs#

Perintah kubectl logs menampilkan keluaran standar dan error standar dari sebuah container, yaitu saluran yang digunakan aplikasi untuk menulis log. Perintah ini menjawab pertanyaan yang tidak dijawab describe, misalnya mengapa aplikasi berhenti segera setelah dijalankan. Flag --tail membatasi jumlah baris yang ditampilkan, flag -f mengikuti aliran log secara langsung, dan flag -c memilih container tertentu pada Pod multi-container. Flag --previous menampilkan log dari container yang berakhir sebelum restart terakhir, sehingga pesan penyebab crash masih terbaca.

bash 
# tidak-dijalankan
# menampilkan 20 baris terakhir log container catatan-api
kubectl logs catatan-api-7d9c4b6d5f-xk2qz -c catatan-api --tail=20 -n aplikasi-catatan
# menampilkan log container yang berakhir sebelum restart terakhir
kubectl logs catatan-api-7d9c4b6d5f-xk2qz --previous -n aplikasi-catatan
text Contoh keluaran 
[2026-11-07 09:15:04] server catatan berjalan di port 8080
[2026-11-07 09:15:11] error koneksi basis data: dial tcp 10.96.12.7:5432: connect: connection refused
[2026-11-07 09:15:11] proses berakhir dengan kode 1

Flag --previous menjadi alat utama pada kasus CrashLoopBackOff karena container yang gagal selalu berakhir segera setelah dijalankan, sehingga baris terakhir lognya memuat penyebabnya. Perlu diingat bahwa kubectl logs hanya membaca log dari Node tempat container berjalan pada saat itu. Apabila Pod dijadwalkan ulang ke Node lain atau sudah dihapus, log lama tidak dapat dibaca lagi melalui perintah ini.

Menjalankan perintah di dalam container#

Perintah kubectl exec menjalankan perintah di dalam container yang sedang berjalan. Bentuk yang paling umum adalah membuka shell interaktif dengan flag -it untuk memeriksa isi sistem berkas, variabel lingkungan, dan konektivitas dari sudut pandang aplikasi. Seluruh container dalam satu Pod berbagi jaringan yang sama, sehingga tes koneksi ke localhost dari salah satu container sekaligus menguji port container lain dalam Pod yang sama. Untuk pemeriksaan cepat, exec juga dapat menjalankan satu perintah tanpa membuka shell interaktif, dan hasilnya dicetak langsung di terminal.

bash 
# tidak-dijalankan
# menjalankan satu perintah tanpa membuka shell interaktif
kubectl exec catatan-api-7d9c4b6d5f-xk2qz -n aplikasi-catatan -- cat /etc/hostname
# membuka shell interaktif di dalam container catatan-api
kubectl exec -it catatan-api-7d9c4b6d5f-xk2qz -n aplikasi-catatan -- sh
text Contoh keluaran 
catatan-api-7d9c4b6d5f-xk2qz

Meneruskan port Pod ke komputer lokal#

Perintah kubectl port-forward meneruskan port di komputer lokal ke port pada Pod tertentu selama perintah itu berjalan. Koneksi diteruskan melalui API server, sehingga akses tidak memerlukan Service maupun pengaturan jaringan tambahan di kluster. Alat ini cocok untuk menguji respons aplikasi secara langsung, misalnya memastikan endpoint /health merespons dengan benar sebelum aturan Service ditulis. Proses penerusan berhenti ketika perintah dihentikan dengan Ctrl-C, dan port yang diteruskan kembali bebas setelahnya.

bash 
# tidak-dijalankan
# meneruskan port 8080 lokal ke port 8080 pada Pod
kubectl port-forward pod/catatan-api-7d9c4b6d5f-xk2qz 8080:8080 -n aplikasi-catatan
text Contoh keluaran 
Forwarding from 127.0.0.1:8080 -> 8080

Membaca event di tingkat namespace#

Event adalah catatan singkat yang dibuat komponen kluster setiap kali kejadian penting terjadi, misalnya Pod dijadwalkan, image ditarik, atau probe gagal. Event terikat pada namespace dan disimpan hanya untuk waktu terbatas, secara default sekitar satu jam, sehingga perlu dibaca segera setelah gejala muncul. Perintah kubectl get events menampilkan seluruh event pada satu namespace, dan flag --sort-by mengurutkannya menurut bidang mana pun, biasanya .lastTimestamp agar kejadian terbaru muncul lebih dahulu.

bash 
# tidak-dijalankan
# menampilkan event namespace diurutkan dari waktu terbaru
kubectl get events -n aplikasi-catatan --sort-by=.lastTimestamp
text Contoh keluaran 
LAST SEEN   TYPE      REASON             OBJECT                            MESSAGE
94s         Warning   BackOff            pod/catatan-api-7d9c4b6d5f-xk2qz  Back-off restarting failed container catatan-api
3m12s       Warning   Unhealthy          pod/catatan-api-7d9c4b6d5f-xk2qz  Readiness probe failed: HTTP probe failed with statuscode: 503
5m          Normal    Scheduled          pod/catatan-api-7d9c4b6d5f-xk2qz  Successfully assigned aplikasi-catatan/catatan-api-7d9c4b6d5f-xk2qz to node-02

Keluaran kubectl get events juga dapat dibaca sebagai JSON melalui -o json untuk disaring secara terprogram. Berkas berikut merupakan salinan ringkas dari bentuk keluaran tersebut pada namespace contoh, berisi lima event.

json events.json 
{
  "kind": "List",
  "apiVersion": "v1",
  "items": [
    {
      "type": "Normal",
      "reason": "Scheduled",
      "involvedObject": {
        "kind": "Pod",
        "name": "catatan-api-7d9c4b6d5f-xk2qz",
        "namespace": "aplikasi-catatan"
      },
      "lastTimestamp": "2026-11-07T09:12:31Z",
      "message": "Successfully assigned aplikasi-catatan/catatan-api-7d9c4b6d5f-xk2qz to node-02"
    },
    {
      "type": "Normal",
      "reason": "Pulled",
      "involvedObject": {
        "kind": "Pod",
        "name": "catatan-api-7d9c4b6d5f-xk2qz",
        "namespace": "aplikasi-catatan"
      },
      "lastTimestamp": "2026-11-07T09:12:33Z",
      "message": "Successfully pulled image \"catatan-api:1.4.0\" in 1.9s"
    },
    {
      "type": "Warning",
      "reason": "Unhealthy",
      "involvedObject": {
        "kind": "Pod",
        "name": "catatan-api-7d9c4b6d5f-xk2qz",
        "namespace": "aplikasi-catatan"
      },
      "lastTimestamp": "2026-11-07T09:14:50Z",
      "message": "Readiness probe failed: HTTP probe failed with statuscode: 503"
    },
    {
      "type": "Warning",
      "reason": "BackOff",
      "involvedObject": {
        "kind": "Pod",
        "name": "catatan-api-7d9c4b6d5f-xk2qz",
        "namespace": "aplikasi-catatan"
      },
      "lastTimestamp": "2026-11-07T09:15:02Z",
      "message": "Back-off restarting failed container catatan-api in pod catatan-api-7d9c4b6d5f-xk2qz_aplikasi-catatan(f0e1c9a4)"
    },
    {
      "type": "Warning",
      "reason": "FailedScheduling",
      "involvedObject": {
        "kind": "Pod",
        "name": "laporan-bulanan-28471",
        "namespace": "aplikasi-catatan"
      },
      "lastTimestamp": "2026-11-07T09:16:10Z",
      "message": "0/3 nodes are available: 3 Insufficient cpu. preemption: 0/3 nodes are available: 3 No preemption victims found for incoming pod."
    }
  ]
}

Skrip berikut menyaring event bertipe Warning dan menampilkan waktu, nama objek, serta pesannya menggunakan jq, sehingga pola yang sama dapat dilatih tanpa kluster.

bash 
# menyaring event bertipe Warning dan menampilkan waktu, objek, serta pesannya
jq -r '.items[] | select(.type == "Warning") | [.lastTimestamp, .involvedObject.name, .message] | join(" | ")' events.json
text Keluaran 
2026-11-07T09:14:50Z | catatan-api-7d9c4b6d5f-xk2qz | Readiness probe failed: HTTP probe failed with statuscode: 503
2026-11-07T09:15:02Z | catatan-api-7d9c4b6d5f-xk2qz | Back-off restarting failed container catatan-api in pod catatan-api-7d9c4b6d5f-xk2qz_aplikasi-catatan(f0e1c9a4)
2026-11-07T09:16:10Z | laporan-bulanan-28471 | 0/3 nodes are available: 3 Insufficient cpu. preemption: 0/3 nodes are available: 3 No preemption victims found for incoming pod.

Tiga baris di atas menghasilkan kesimpulan yang sama dengan pembacaan seluruh event secara manual, yaitu probe yang gagal, container yang berulang kali berakhir, dan Pod baru yang tidak dapat dijadwalkan karena CPU kluster tidak mencukupi. Baris terakhir berasal dari Pod yang berbeda, yaitu laporan-bulanan-28471, sehingga satu penyaringan memuat laporan dua kejadian yang terpisah. Pola penyaringan yang sama dapat dikembangkan menjadi pemeriksaan rutin apabila keluaran -o json dikumpulkan secara berkala.

Ringkasan#

  • kubectl describe menampilkan status objek beserta daftar event di bagian bawah, sehingga penyebab umum kegagalan sering terbaca dari satu perintah.
  • kubectl logs membaca keluaran container, dan flag --previous mengambil log container yang berakhir sebelum restart terakhir.
  • kubectl exec menjalankan perintah di dalam container, sedangkan kubectl port-forward meneruskan port Pod ke komputer lokal untuk pengujian.
  • Event namespace diurutkan dengan --sort-by dan dapat disaring secara terprogram dari keluaran -o json menggunakan jq.

Referensi#