Belajar Puppet - PuppetDB Query & Exported Resources Lanjutan

#Pendahuluan

Di episode 16 kalian sudah belajar memperluas Puppet dengan defined types, custom facts, functions, dan custom providers. Kini saatnya memanfaatkan kekayaan data yang dikumpulkan Puppet setiap run. Setiap fakta, report, dan resource yang dilaporkan agent disimpan di PuppetDB dan bisa diquery melalui API.

Di episode 9 kita sudah berkenalan dengan PuppetDB dan exported resources secara dasar. Pada episode ini kita akan membahas query API secara lebih dalam: memfilter fakta, membaca reports, dan menarik data resources. Kita juga akan mengeksplorasi pola exported resources lanjutan untuk inventory otomatis, target monitoring, dan konfigurasi jaringan yang saling bergantung antar node.

Pada episode ini kita akan membahas endpoint query API PuppetDB, contoh query fakta, reports, dan resources, konsumsi data dari external tools, hingga pola exported resources untuk berbagai kebutuhan lintas node.

#Query API PuppetDB

PuppetDB menyediakan API REST yang bisa diakses melalui HTTP pada port default 8080 untuk open source atau via console PE. Endpoint utama berada di /pdb/query/v4 dengan bahasa query yang menyerupai JSONPath.

Query paling sederhana adalah menampilkan seluruh node yang diketahui PuppetDB:

curl -s 'http://localhost:8080/pdb/query/v4/nodes'

Hasilnya berupa array JSON, misalnya:

[
  {
    "certname": "web01.example.com",
    "catalog_timestamp": "2026-08-03T01:00:00.000Z",
    "facts_timestamp": "2026-08-03T01:00:00.000Z",
    "report_timestamp": "2026-08-03T01:05:00.000Z"
  }
]

Untuk pengguna Puppet Enterprise, tersedia CLI yang lebih nyaman:

puppet query 'nodes[certname] {}'

#Query Fakta, Reports, dan Resources

Endpoint fakta /pdb/query/v4/facts memungkinkan kita mencari fakta tertentu dari semua node atau dari satu node:

curl -s 'http://localhost:8080/pdb/query/v4/facts/web01.example.com/osfamily'

Untuk melihat laporan run terakhir sebuah node, kita query endpoint /pdb/query/v4/reports:

curl -s 'http://localhost:8080/pdb/query/v4/reports?query=%5B%22%3D%22%2C%22certname%22%2C%22web01.example.com%22%5D&limit=1'

Dengan bahasa query JSON, ekspresi ["=", "certname", "web01.example.com"] ditulis URL-encoded. PuppetDB juga menyediakan endpoint resources untuk menelusuri resource tertentu di seluruh catalog:

curl -s 'http://localhost:8080/pdb/query/v4/resources/Service/sshd'

Query ini berguna untuk mengaudit: misalnya memastikan semua node memakai konfigurasi yang sama, atau menemukan node yang melanggar kebijakan.

#Dashboard dan Konsumsi Eksternal

Data PuppetDB tidak hanya dipakai manifest, tetapi juga bisa dikonsumsi tool eksternal. Dashboard seperti Grafana dapat memvisualisasikan hasil query melalui plugin datasource HTTP atau script kecil yang memanggil API PuppetDB.

curl -s 'http://localhost:8080/pdb/query/v4/facts/osfamily' \
  | jq 'group_by(.value) | map({os: .[0].value, count: length})'

#Exported Resources untuk Inventory

Exported resources memungkinkan satu node mempublikasikan resource, dan node lain mengumpulkannya. Pola klasiknya adalah membuat inventory SSH host: setiap node mengekspor host key-nya, lalu satu node collector mengumpulkan semuanya.

@@sshkey { "sshkey-${facts['networking']['fqdn']}":
  ensure => present,
  name   => $facts['networking']['fqdn'],
  key    => $facts['ssh']['rsa']['key'],
  type   => 'rsa',
  tag    => 'sshkeys',
}

Sshkey <<| tag == 'sshkeys' |>>

#Pola Monitoring Targets

Pola yang sama berlaku untuk konfigurasi monitoring. Setiap node mengekspor definisi target monitoring, dan server monitoring mengumpulkan definisi tersebut menjadi konfigurasi lengkap tanpa perlu daftar node yang dikelola manual.

@@nagios_host { $facts['networking']['fqdn']:
  ensure  => present,
  address => $facts['networking']['ip'],
  use     => 'generic-host',
  tag     => 'monitoring',
}
 
Nagios_host <<| tag == 'monitoring' |>>

Ketika node baru ditambahkan, node itu otomatis mengekspor dirinya dan server monitoring memasukkan target baru pada run berikutnya. Tidak perlu ada daftar host yang diedit tangan, dan tidak ada node yang terlupakan.

#Konfigurasi Jaringan Lintas Node

Kasus tersulit adalah konfigurasi yang saling bergantung antar node, misalnya load balancer yang harus tahu alamat semua backend. Node backend mengekspor definisi vhost backend, dan node load balancer mengumpulkannya untuk menyusun konfigurasi upstream.

@@nginx::resource::upstream { "backend-${facts['networking']['fqdn']}":
  members => ["${facts['networking']['ip']}:8080"],
  tag     => "lb-${trusted['certname']}",
}

Nginx::Resource::Upstream <<| tag == "lb-${trusted['certname']}" |>>

Tag berbasis trusted certname memastikan hanya node yang memang menjadi backend dari load balancer tertentu yang dikumpulkan. Ini contoh kombinasi exported resources dengan data trusted facts, sesuatu yang tidak bisa dilakukan dengan static config.

#Penutup

Pada episode 17 ini kalian sudah memahami cara menggali data dari PuppetDB lewat query API untuk fakta, reports, dan resources, mengonsumsi hasilnya dari external tools seperti Grafana, serta menerapkan pola exported resources lanjutan untuk inventory host, target monitoring, dan konfigurasi jaringan lintas node.

Inti yang harus dibawa pulang:

• PuppetDB API di /pdb/query/v4 menyediakan data fakta, reports, dan resources secara terstruktur.
• Query berbahasa JSON memungkinkan filter presisi, dan CLI puppet query mempermudah pengguna PE.
• Dashboard eksternal bisa mengonsumsi PuppetDB sebagai sumber data inventory dan monitoring.
• Exported resources memungkinkan node mempublikasikan dirinya dan node lain mengumpulkannya dengan @@ dan <<| |>>.
• Tag dan trusted facts membuat pola ekspor-collect tetap tepat sasaran di infrastruktur yang besar.

Semakin besar infrastruktur, semakin besar risiko perubahan yang merusak. Itulah sebabnya pengujian menjadi keharusan, bukan pilihan. Di episode 18 kita akan membahas Belajar Puppet - Testing: unit test dengan rspec-puppet, fixture dengan puppetlabs_spec_helper, hingga acceptance test menggunakan beaker di CI.