Debugging Pyinfra Agentless: Identifikasi Gejala Task Deploy Macet

Task Pyinfra berhenti menunggu tanpa menyelesaikan host mana pun? Gejala awal yang paling umum adalah job terhenti pada satu atau beberapa host dengan status “waiting” atau “running” di bagian paling bawah output, tanpa error yang jelas. Untuk menjawab pertanyaan itu, periksa apakah job sudah mencapai item terakhir tapi status tidak berubah, dan apakah host tertentu sudah tidak mengirimkan data log baru selama beberapa menit. Segera catat timestamp ketika stagnasi terjadi, karena itu akan membantu korelasi dengan log remote dan aktivitas jaringan.

Debugging Pyinfra berarti menyelaraskan lapisan konsep: inventory, kondisi task, dan eksekusi SSH. Memahami bahwa Pyinfra tidak memiliki agen berarti kita bergantung penuh pada koneksi SSH. Bila job deploy macet, langkah awal adalah memastikan koneksi SSH dan host target masih responsif, serta tidak ada operasi blocking di sisi remote.

Mengumpulkan Bukti via Log dan SSH

Periksa stdout Pyinfra dan log shell

Pyinfra mencatat setiap task yang dijalankan. Saat deploy macet, gunakan opsi verbositas untuk melihat task terakhir yang berhasil dijalankan sebelum berhenti.

pyinfra @production deploy.py --debug

Output ini membawa konteks task terakhir dan status SSH. Namun, jika Pyinfra tampak diam, buka sesi SSH manual ke host terpengaruh untuk melihat apakah perintah masih berjalan atau terhenti. Jalankan ps atau strace ringan bila perlu untuk memastikan tidak ada proses lock yang menunggu input.

Cek keterhubungan jaringan secara langsung

Terutama saat banyak host: pastikan tidak ada switch NAT/timeout yang memutus sesi. Perintah sederhana seperti ssh host uptime cukup untuk memastikan SSH tetap alive. Bila Pyinfra menggunakan key tertentu, jalankan ssh -v untuk melihat handshake dan memeriksa apakah ada retries yang membekukan seluruh deployment.

Analisis Penyebab Utama: Inventory Mismatch dan Kondisional Task

Inventory yang tidak sinkron

Inventory Pyinfra menentukan host mana saja yang akan dijalankan. Masalah sering muncul ketika inventory dihasilkan secara dinamis (misal dari script) dan host tidak terdaftar di file statis, sehingga task dipanggil pada host yang tidak ada atau tidak sesuai dengan grup. Periksa generator inventory:

hosts = ["db01.example.com", "app01.example.com" ]
# pastikan nama sesuai DNS dan tidak ada whitespace

Jika inventory dibaca dari file YAML/JSON, pastikan struktur sesuai dokumentasi Pyinfra: tidak ada nested yang tidak perlu dan setiap host unik. Bila host yang macet tidak ada di inventory tetapi muncul di output Pyinfra, artinya cache atau script inventory menduplikasi host sehingga kondisional task bisa merujuk ke host yang sudah tidak valid.

Kondisional task yang gagal diam-diam

Task Pyinfra sering dipasang dengan kondisional seperti when atau unless. Contoh:

files.put("/etc/app/config", "contents", user="app")
@host.connect(hostname)
@deploy.task
@deploy.when("ansible_check.stdout == 'ok'")

Kalau kondisional gagal (hasil dari task sebelumnya tidak seperti yang diharapkan), Pyinfra akan melewatkan task berikut tanpa error fatal, yang terlihat seperti job berhenti. Pastikan kondisi tersebut memposting log atau flag agar Anda tahu kenapa Pyinfra tidak melanjutkan. Logging tambahan seperti print atau logger.info pada setiap kondisi membantu memperkirakan aliran eksekusi.

Langkah Perbaikan dan Verifikasi

Setelah mengumpulkan bukti dan memahami penyebab, langkah perbaikan berikutnya adalah:

  • Perbarui inventory dengan memastikan host yang valid dan sekali di-cache. Gunakan hashing atau timestamp untuk mendeteksi inventory yang tidak sinkron sebelum deploy.
  • Tambah logging kondisional untuk setiap when/unless sehingga Pyinfra mencetak alasan skip: ini bisa dilakukan dengan helper kecil yang mengevaluasi kondisi dan memanggil print atau logging.
  • Jalankan ulang subset host untuk memverifikasi perbaikan, misalnya pyinfra app01.example.com deploy.py, sehingga Anda tidak menjalankan seluruh group yang bisa memakan waktu.
  • Gunakan --limit untuk memastikan hanya host relevan yang diuji.

Verifikasi dilakukan dengan mengulangi deploy pada host paling kecil dan memastikan proses tidak stuck lagi. Apabila ada task yang tergantung pada host lain (multiple host dependencies), mock atau stub kondisi tersebut supaya Pyinfra tidak menunggu host yang bermasalah.

Rekomendasi Observabilitas untuk Sistem Automation Agentless

Untuk mencegah kejadian serupa, tambahkan observabilitas berikut:

  • Structured logging pada setiap task: catat host, nama task, kondisi, dan status eksekusi. Format JSON mempermudah integrasi dengan log aggregator.
  • Health check inventory: jalankan script validasi sebelum deploy untuk memeriksa konektivitas SSH, keberadaan host, dan kesesuaian nama.
  • Script heartbeat untuk setiap host: sebelum Pyinfra mengeksekusi task yang panjang, kirim log ke monitoring internal atau sistem alert sehingga Anda tahu task berhasil dimulai.
  • Gunakan monitoring daemon yang memeriksa apakah Pyinfra masih menulis log; bila tidak ada log baru selama X menit, kirim alert agar tim segera menyelidiki.

Observabilitas semacam ini membantu deteksi dini, sehingga Anda tidak hanya bergantung pada satu titik kegagalan saat job deploy berhenti.

Kesimpulan

Debugging Pyinfra agentless mengambil pola investigasi: identifikasi gejala awal, kumpulkan bukti dari log/SSH, pahami inventory/kondisional, lalu perbaiki dan verifikasi secara bertahap. Menambahkan observabilitas membuat sistem Anda responsif terhadap masalah kecil sebelum bertambah besar. Dengan pendekatan ini, Anda memperkecil kemungkinan task deploy macet tanpa kejelasan.