Belajar Puppet - Performance & Troubleshooting

#Pendahuluan

Di episode 18 kalian sudah membangun piramida pengujian untuk kode Puppet: lint, validasi sintaks, unit testing dengan rspec-puppet, hingga acceptance testing dengan Beaker di CI. Kode yang teruji adalah fondasi yang baik — tetapi di produksi, kode yang benar tidak cukup. Ia juga harus berjalan cepat dan mudah diperbaiki saat terjadi masalah.

Infrastruktur Puppet yang melayani ratusan hingga ribuan node akan menghadapi tantangan baru: catalog compilation yang semakin lambat, report yang tertunda, PuppetDB yang membengkak, dan deretan error misterius di sisi agent. Tanpa kemampuan menganalisis dan memperbaiki, hal-hal ini akan tumbuh menjadi gangguan layanan yang sulit dilacak.

Episode ini membahas sisi operasional Puppet: cara membaca waktu tiap tahap agent run, menganalisis catalog compilation dan report lag, men-tuning Puppet Server dari sisi JVM, serta teknik troubleshooting untuk masalah paling umum seperti certificate mismatch, catalog compilation error, resource conflict, dan facts yang salah.

#Anatomi Satu Agent Run

Sebelum menganalisis performa, kita harus paham apa saja yang terjadi saat puppet agent -t dijalankan. Satu agent run yang normal melewati urutan berikut:

Waktu di tiap tahap bisa dilihat pada output verbose agent:

puppet agent -t --evaltrace

Info: Applying configuration version '1739000000'
Info: Evaluated state of File[/etc/nginx/nginx.conf] (0.03 seconds)
Info: Evaluated state of Service[nginx] (0.10 seconds)

Jika --evaltrace menunjukkan satu resource menghabiskan waktu jauh lebih lama dari yang lain, itulah titik yang perlu diselidiki — misalnya sebuah exec yang menunggu timeout jaringan atau package yang sedang diunduh.

#Menganalisis Catalog Compilation

Catalog compilation adalah tahap yang paling mahal secara CPU. Setiap agent run memicu proses compile di Puppet Server, dan setiap compile membutuhkan JRuby instance dari pool. Ketika jumlah agent melonjak bersamaan — misalnya semua node melakukan run pada menit yang sama — antrean menumpuk dan agent mulai menunggu.

Indikator utama kesehatan server ada di endpoint status Trapperkeeper:

curl -s https://localhost:8140/status/v1/services \
  --cert /etc/puppetlabs/puppet/ssl/certs/puppet-server.example.net.pem \
  --key /etc/puppetlabs/puppet/ssl/private_keys/puppet-server.example.net.pem \
  --cacert /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem | jq

Selain itu, Puppet Server mengekspos metrik yang bisa dihubungkan ke Prometheus dan Grafana. Metrik yang paling penting diperhatikan: waktu kompilasi rata-rata, jumlah request yang mengantre, dan tingkat kesalahan kompilasi.

Salah satu penyebab antrean paling umum adalah semua agent berjalan pada waktu yang sama. Sebarkan jadwal run dengan splay:

[agent]
server = puppet.example.net
runinterval = 30m
splay = true
splaylimit = 5m

Dengan splay = true dan splaylimit = 5m, setiap agent menunda run secara acak hingga 5 menit setelah interval, sehingga beban server tersebar alih-alih menumpuk di satu titik.

#Report Lag dan Beban PuppetDB

Setiap agent run menghasilkan report yang dikirim ke server, lalu diteruskan ke PuppetDB untuk penyimpanan dan query. Jika volume report tinggi, PuppetDB bisa menjadi titik macet. Gejala utamanya: laporan muncul di console dengan keterlambatan, dan proses puppetdb atau pe-puppetdb memakan memori sangat besar.

Penyebab paling umum dari report lag: data historis yang menumpuk tanpa dibatasi. PuppetDB menyediakan pengaturan TTL untuk membersihkan data lama:

[global]
# Hapus report yang lebih tua dari 14 hari
report-ttl = 14d
# Hapus node yang tidak pernah report dalam 30 hari
node-ttl = 30d
# Bersihkan node beserta data terkait 7 hari setelah node-ttl
node-purge-ttl = 7d

Setelah mengubah konfigurasi, restart PuppetDB. Untuk memantau volume data yang tersimpan, gunakan query PQL sederhana:

puppet query 'reports[catalog_format, end_time, start_time, noop] {
  latest_report = true and certname = "web01.example.net"
}'

#Tuning Puppet Server dari Sisi JVM

Puppet Server berjalan di atas JVM dan JRuby. Dua kelompok pengaturan yang paling berdampak: ukuran heap JVM dan ukuran pool JRuby.

Ukuran heap JVM diatur lewat file sysconfig server:

JAVA_ARGS="-Xms2g -Xmx4g -XX:MaxMetaspaceSize=512m"

Aturan praktis yang umum: sediakan sekitar 4-8 GB heap untuk server yang melayani ribuan node, dan pastikan MaxMetaspaceSize cukup untuk menghindari kesalahan Metaspace.

Pool JRuby diatur di /etc/puppetlabs/puppetserver/conf.d/puppetserver.conf:

jruby-puppet:
  max-active-instances: 4
  max-requests-per-instance: 100000
  max-queued-requests: 0
  max-retry-delay: 1800

• max-active-instances menentukan berapa banyak request yang bisa dikompilasi secara paralel. Default 4; menaikkannya berarti memakai lebih banyak CPU dan memori.
• max-requests-per-instance memaksa JRuby di-reset setelah sejumlah request untuk mencegah kebocoran memori.
• max-queued-requests membatasi antrean; jika terlampaui, server mengembalikan kode 503 sehingga agent tidak menumpuk di antrean.

#Troubleshooting Umum

#Certificate Mismatch

Salah satu error paling sering di awal setup:

Exiting; no certificate found and waitforcert is disabled

Atau di sisi server:

Could not find certificate request for node web01.example.net

Penyebab umum: nama hostname agent berbeda dari yang didaftarkan, atau sertifikat lama masih tersimpan. Solusinya, pastikan certname agent konsisten, lalu cek status sertifikat:

sudo puppet ssl clean             # di agent, menghapus SSL lama
sudo puppet cert list             # di server, daftar certificate request
sudo puppet cert sign web01.example.net

#Catalog Compilation Error

Error kompilasi biasanya muncul di log server dan report agent. Penyebab paling umum adalah referensi resource yang tidak ada atau kesalahan data hiera. Cara terbaik untuk melihat detailnya adalah dengan meminta agent menampilkan jejak lengkap:

sudo puppet agent --test --debug --trace

Bendera --trace menampilkan jejak panggilan hingga ke lokasi kode yang bermasalah, sementara --debug memunculkan detail seperti data hiera yang dipakai dan keputusan evaluasi. Kombinasi keduanya adalah senjata utama troubleshooting.

#Resource Conflict

Error duplicate declaration terjadi ketika dua resource dengan tipe dan title yang sama dideklarasikan dua kali:

Error: Duplicate declaration: File[/etc/nginx/conf.d/app.conf] is already declared

Penyebab khas: sebuah class di-include dua kali lewat jalur berbeda, atau dua resource menggunakan title yang sama. Solusinya, pastikan setiap resource punya title unik, atau gunakan pola contain, require, dan virtual resources dari episode 8 untuk mengendalikan evaluasi.

#Facts yang Salah

Kadang catalog memilih cabang yang salah karena facts tidak sesuai — misalnya versi OS lama yang tersimpan di cache. Facts di-cache oleh Facter. Untuk menyegarkannya:

sudo rm -rf /opt/puppetlabs/facter/cache
sudo facter -p os.release.major

Jika facts yang salah datang dari custom fact atau facts yang didelegasikan dari luar, periksa bahwa fakta tersebut benar-benar dihasilkan dan tidak ter-overwrite oleh hiera data.

#Checklist Diagnostik Cepat

Ketika produksi sedang bermasalah, ikuti urutan ini:

puppet agent --test --debug --trace
puppet agent --test --noop --evaltrace
puppet config print server certname environment
puppet lookup --node web01.example.net nginx::worker_processes
puppet query 'nodes[certname] { latest_report_status = "failed" }'

Dari output yang dihasilkan, kalian bisa memutuskan apakah masalahnya di jaringan, di sertifikat, di kompilasi, atau di data — lalu masuk ke perbaikan yang tepat. Query terakhir menemukan semua node yang report terakhirnya gagal, sehingga perbaikan bisa diarahkan ke node yang benar-benar bermasalah.

#Penutup

Pada episode ini kita membahas sisi operasional Puppet: anatomi agent run dan cara mengukur tiap tahapnya, analisis catalog compilation dan report lag, pembatasan beban PuppetDB melalui TTL dan penyebaran jadwal run, tuning Puppet Server dari sisi JVM dan pool JRuby, serta troubleshooting masalah paling umum seperti certificate mismatch, catalog compilation error, resource conflict, dan facts yang salah dengan puppet agent --debug --trace.

Inti yang harus dibawa pulang:

• Ukur sebelum mengoptimasi — gunakan --evaltrace, status endpoint, dan metrik PuppetDB untuk menemukan bottleneck yang sebenarnya.
• Sebarkan beban agent dengan splay dan splaylimit agar tidak ada lonjakan run bersamaan.
• Batasi pertumbuhan data di PuppetDB melalui report-ttl, node-ttl, dan node-purge-ttl.
• Tuning JVM bertahap — naikkan heap dan max-active-instances sedikit demi sedikit sambil memantau memori.
• --debug --trace adalah teman terbaik saat menghadapi error yang tidak jelas di agent.

Di episode 20 selanjutnya, kita akan membahas fitur stabil terbaru — apa yang baru di Puppet 8 open source dan Puppet Enterprise 2025.1, termasuk Security Compliance Management dan manajemen node berbasis peran. Sampai jumpa di episode berikutnya!